Designing Event Templates

Deciding What to Put in an Event Template

Deciding which data items must be supplied by event posters, and which data items must be supplied by templates is a design-level decision. As a general rule, including constant data items in the event template is better than hardcoding them into an event by posting programs.

A key benefit of the event template mechanism is that it enables you to centralize the constant attributes of all events in your application, making it very easy to change them during the development cycle. This also provides a single place to look for the information after the application has been deployed.

As a general rule, minimize the amount of event information that you hard code into a posting application program, and provide as much as information possible into the event template. Typically, your application must only provide the following information:

The template must generally include the following entities:

Although the posting application is generally expected to supply values for variable data items when it posts an event, including the variable in the template is helpful because this makes the template more valuable as a point of documentation. In the template, you must typically set variable values to 0 (or for string variables, set an empty string). In some special cases, providing a real default value in a template (which can be overridden by the poster) may be useful — if this is the case, describe the situation as a comment in the template file.

Example 2-2 “ Event Template File” is an example of an event template file containing one event.

Example 2-2  Event Template File

# Example event file priority 200 # Default priority ref cat:myapp_exp.cat # Global reference event

{ name myco.myapp.env.temperature format "Temperature is $temperature" var { name temperature type FLOAT value 0,0 } }

You can include as many variables as you like in an event. However, opaque variables (binary structures) are not supported in templates.

Matching the Names of Posted Events with Event Template Names

Each time an attempt is made to post an event, EVM searches its template database for the template whose event name matches the name of the posted event. If no match is found, EVM returns an error code to the program that posted the event. If a match is found, EVM then combines the data items held in the template with the items supplied by the posting program. This operation generates the merged event that is distributed to subscribers. For more information about merging operation, see “Merging Data Items from Templates and Posted Events”.

The template-matching process requires a match only between the leftmost components of a posted event's name and all of the components of a template event's name. EVM searches for the best match in its database, using the following rules:

HP recommends that you provide a separate template for each distinct event your application posts, because this enables you to centralize the event's unique information by storing it in the template. However, the benefit of the best-match mechanism is that it enables you to extend an event's name with different instance information each time you post it; for example, you can add a device name or temperature value as additional components. These additional instance components makes it easier to filter and sort events. For examples of ways to extend an event's name, see “Reserved Component Names” .

Table 2-5 “Name Matching Examples” lists some examples of event name matching between event templates and posted events.

Merging Data Items from Templates and Posted Events

After the EVM daemon successfully validates a posted event, it merges the data items contained in the posted event with any data items contained in the template, and distributes the merged event to any clients that have subscribed to the event. The merge process provides the event designer maximum flexibility in deciding which text and data items are to be provided by the template and which are to be provided by the poster.

Figure 2-1 “Posted Event and Template Merging” illustrates the concept of event merging.

Figure 2-1 Posted Event and Template Merging

If the same data item is supplied in both the template and the posted event, the posted value is used in the merged event.

The merge process yields a binary event structure that contains a combination of the data items from the posted event and the template. The merged event is distributed to subscribers in its binary form, not as a formatted message, and subscribers must use the EVM API functions to format the event for display or to extract information from it. For more information about API functions, see Chapter 3 “The EVM Programming Interface”.

Installing Template Files — Location, Naming, Ownership, and Permission Requirements

Event template files must normally be installed as part of the product or application installation process. System templates are stored in subdirectories under /usr/share/evm/templates, while third-party product and local application templates must be stored under the local template directory, /var/evm/adm/templates. To enable the EVM daemon to locate the additional templates, a link is provided from the system template directory to the local directory.

To add templates for a product or local application, the application's installation process must create an appropriately named subdirectory of the local template directory and install its templates in the new directory. EVM's template search policy follows symbolic links. Hence, you must also install the templates in a directory more closely associated with the application, and connect it to the local directory with a link.

Template files must have the suffix .evt, must be owned by root or bin, and must have one of the following access permissions: 0600, 0400, 0640, or 0440. In addition, ensure that the new directory is given appropriate permissions.

After you install the file, enter (as superuser) the evmreload -d command to cause EVM to recognize the new templates, and then check for any errors. For more information about this command, see evmreload(1M).

Checking Event Template Registration

You can determine whether your templates are registered by using evmwatch with the -i option. For example, the following command lists the names of all event templates registered for the myapp application:

 evmwatch -i -f "[name myco.myprod.myapp]" | evmshow -t "@name"

Use the -d option of evmshow to display the template details.

	NOTE: The evmwatch command does not return the templates of any events for which you do not have access authorization. Hence, you must log in as superuser to view your templates.

Establishing Translations for Event Text (I18N)

The objective of event internationalization (I18N) is to enable an event's format data item, and the values of any string variables contained in the event, to be converted to another language for display. If you are developing a product that is used internationally, you can include support for translation of any or all of these items.

Different users may want to view the same stored event in different languages. Language interpretation must be performed at the same time when the event is formatted for presentation, not when it is posted. It is impractical for an event to carry the text in all possible languages. Hence, its associated message catalog must be available when the event is formatted. Product developers are responsible for providing message catalogs and for including them during installation along with their products. In case the catalog is not available, an internationalized event can carry a default native-language string.

The following data items support internationalization of events:

All message identifiers for the event must relate to the same message catalog, and they must all belong to the same message set (1, by default).

In general, the catalog ID, set ID, and message ID for the event format string must be supplied in the event template, because the format string is usually fixed. If events contain string-type variables, the variables are likely to refer to items such as device names or application names, which usually are not translated, regardless of the language for display. Hence, in most cases, it is not necessary to supply a message ID. In rare cases, where the value of a string variable needs to be translated, the poster must supply the message ID.

Table 2-6 “Example Data Item Values for an Internationalized Event ” lists some examples of internationalized values for an example event.

English and French versions of temperature.cat contain:

If the format function cannot interpret the events from a catalog, it uses values that are carried in the event and returns the following message regardless of the user's locale:

 "Temperature at sensor S27 is high"

If an event file is passed to another system for analysis, the associated catalog file may not be available. If the event includes default values, as in the previous example, it can still be displayed in the original language. If the event does not include defaults, the formatted string can still show the event name, along with any variables. For example:

 Event "myco.myprod.env.temp": $sensor = "S27" $temperature = 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 "high"

For additional information on I18N issues, see the System Administration document.