EVM Event Content

The format, type, and purpose of the data carried in events varies widely. In a simple case, an event is a simple text message. In a more complicated case, an event can be a complex set of binary data that requires an understanding of its format to be able to translate it. For two co-operating applications, an event can be a simple binary flag or count.




	NOTE: However, an event is not required to carry data. In some cases, transmitting only a particular event type from poster to subscriber may be all that the subscriber needs to recognize that a particular status change has occurred.

Event data is complicated because it has to be translated in to various formats. For an event to be human readable, it must be possible to combine numeric data with explanatory text. At the same time, the information in the same event may need to be seen as binary data by a subscribing process. In addition, it may also be necessary to have the human-readable form in multiple languages.

The EVM data mechanism enables data to be carried in any way that is appropriate to the event. The constructs that provide this capability are the EVM format data item (one of EVM's standard data items) and the EVM variable data items.

Event data structures contain following types of data items:

Standard data items — A fixed set of items with predefined names.
Variable data items — Items whose names and types are typically defined by the event designer.

When you create an event, you can include any number of data items. When you post the event, EVM automatically adds certain environmental standard data items, such as the host name and the timestamp.

Standard Data Items

Standard data items are data items that are commonly required in an event and are understood (and may be acted upon) by EVM. The names of standard data items are specified as enumerated constants; consequently, the names themselves do not take up a significant amount of space in an event.

Some standard data items are inserted in an event by the application that posts the event or by the template for the event. Others are automatically inserted, per requirements, by EVM components. You can extract any data item from an event.

Table 2-1 “Standard Data Items” lists the items that require special attention. The standard data items are described in EvmEvent(5).

Table 2-1 Standard Data Items

Data Item	Description
Event name (“Event Name Data Item”)	Specifies the name of the event.
Format (“Event Format Data Item”)	Specifies the event message string.
Priority (“Event Priority Data Item”)	Indicates the importance of the event to its subscribers. Does not affect the order of event distribution.
I18N catalog (“I18N Catalog Name, Message Set ID, and Message ID Data Items”)	Specifies the name of the I18N catalog file for internationalized events.
I18N msgset ID (“I18N Catalog Name, Message Set ID, and Message ID Data Items”)	Identifies the message set within the I18N message catalog.
I18N message ID (“I18N Catalog Name, Message Set ID, and Message ID Data Items”)	Specifies the I18N message ID for the event format.
Reference (“Reference Data Item”)	Provides a reference to the event explanation text.

The following sections discuss the standard data items defined in Table 2-1 “Standard Data Items”.

Event Name Data Item

The event name data item is a character string that identifies an event, generally indicating the origin and the reason for which the event was generated. An event name uniquely identifies a particular type of event. Different instances of the same event have the same name.

EVM uses the event name to decide if a user is authorized to post or access a particular event, and to find template information for the event. Client applications can use event names in conjunction with an event filter to select the events that they want to receive, and to decide on any action that they need to take when an event arrives. For more information about filters, see “Using Event Filters”. The system administrator can use event names to search the event logs for events that are of particular interest.

Following are the characteristics of an event name:

A name is a series of one or more components, separated by dots.
A component is made up of one or more letters, digits, and underscore characters, in any order.
There is no restriction on the number of components in a name.
A name cannot begin or end with a dot.

An event cannot be posted unless it contains an event name with at least three components.

The components of an event name represent an event hierarchy, beginning with the first (left-most) component. The first component is the most general and identifies at a global level, the entity that is responsible for posting the event. The remaining components adds a further level of detail. This detail includes the component that determine that an event must be posted, and information about what happened. The last component provides the most specific information. For example, in the event name sys.unix.fs.filesystem_full:

sys.unix indicates that the event is a system event, posted by a component of the operating system.
fs indicates that the event is posted by the file system component.
filesystem_full indicates that the incident being reported is that a file system is full.

A basic event name that indicates what happened can be extended when the event is posted, by adding more components to give additional information. You can extend the preceding sample event name with information about which file system is full by appending the name of the file system as an extra component, for example, sys.unix.fs.filesystem_full.usr. Although the name is extended, the event is still a sys.unix.fs.filesystem_full event because all of the components of the shorter name match the extended name. A search for an event named sys.unix.fs.filesystem_full still finds the event with the extended name.

The naming scheme provides an open-ended way to identify events, which enables you to provide detail to any level. Careful naming helps subscribers to select specific events or event classes for viewing and monitoring: the more detail you include in the event name, the more precise the specification criteria can be. For example, given the event name myco.myprod.env.temp.ok and myco.myprod.env.temp.high, a system administrator can monitor all temperature-related events by specifying myco.myprod.env.temp or restrict monitoring to events that report a high temperature by specifying myco.myprod.env.temp.high.

To avoid confusion and possible incorrect action by the system administrator or monitoring software, ensure that you provide a unique name to each new event. You can avoid duplicating a name that is already in use by adhering to the following established conventions:

For events that are posted by third-party products or applications, ensure the first three name components identify the vendor of the product, the product, and the program or product component that posts the event. To ensure that the vendor component is globally unique, you must avoid choosing two or three initials for this component — instead, use the full company name or an abbreviation that no other company is likely to choose.
If you are a user, application developer, or an administrator generally follow the same conventions that HP recommends for product vendors, identifying the organization in the first component. However, you can also choose to use the prefix local, because this prefix must never clash with events that are posted by any externally-developed products that you may install.
Ensure the second component identifies the application or group that is responsible for posting the event. For example, your events can begin with the components myco.payroll or myco.admin.
The first two components of all events that are posted by a UNIX system are sys.unix, and the third component identifies the subsystem that posts the event. The use of sys as a first component is reserved for system events.

To prevent name clashes, do not use the reserved names as the first component of events, except for its specific naming convention. For more information about reserved event names, see Table 2-2 “Reserved Event Names”. After you have chosen and published an event name, avoid changing it because the events that an application posts are part of its external interface, and other applications or product components may depend upon receiving them.

Table 2-2 “Reserved Event Names” lists the reserved event names that have specific meanings.

Table 2-2 Reserved Event Names

Name Use Examples

sys Operating system events sys.unix.evm.logger.config_err

local

Local user organization use

local.app.payroll.started

test Available for local test event posting

Reserved Component Names

The more detail you include in an event name, the easier it is for an administrator to use an EVM filter to find particular types of events. For example, the event sys.unix.hw.registered.cpu reports that the operating system's hardware management subsystem has detected and registered a processor. The event contains the hardware ID of the processor in a variable data item and you can view the hardware ID if you display the event with the evmshow. For more information about the variable data items, see “Variable Data Items”. If you are tracing a problem that is related to that processor, you can use an event filter to select only the events that include that hardware ID. You cannot filter events by the values of the variables that they contain. You can only make this selection if the name of the event also includes the information that you want to select. In this case, the hardware management subsystem makes the selection possible by extending the name with the hardware ID that is assigned to each device that it registers. If the hardware ID is 2, you can search for related events with the following command:

evmget -A -f "[name sys.unix.hw.*.2]"

This example, the asterisk (*) wildcard character ensures that you find all events posted by the hardware subsystem that include the identifier 2, regardless of what they are reporting. However, this filter may not select all of the events for the device that interests you, because subsystems other than the hardware subsystem can also report information about the processor, and you may want to include those events in the search. You can increase the scope of the search by specifying [name *.2]. However, other events in the log with the number 2 in their names, and not relevant to the hardware IDs are included in the results.

The convention of reserved component names enables you to select related events, regardless of which subsystem or application posts them. By convention, a reserved component name begins with an underscore character (_) and always identifies a particular type of entity. The posting subsystem or application appends the reserved component name to the base event name before posting the event. Depending on the entity being identified, the following component may then identify the specific instance.

Although the reserved component names are generally defined on behalf of a particular subsystem or application, after a name is defined, its use is not restricted — anything that has information to report about the entity can include the reserved name and entity identifier in the events that it posts. For example, the reserved component name _hwid specifies a hardware device identifier, as defined by the hardware management subsystem, and must be followed by the device-ID. Continuing with the above example, the name of the event that reports the registration of the processor is sys.unix.hw.registered.cpu._hwid.2. You can find all events that relate to all hardware devices with the following command:

evmget -A -f "[name *._hwid]"

You can then narrow the search to the processor that most interests you with the following command:

evmget -A -f "[name *._hwid.2]"

The use of the wildcard in the filter for all components except the hardware ID components ensures that the search yields all related events, regardless of which subsystem or application posted them, provided that the posters followed the convention.

The reserved component name convention requires that when a reserved component name is used, the posted event must contain a variable with the same name (including the leading underscore) and value. This convention enables a subscribing client to retrieve the value from the event through EVM's normal API functions, rather than parsing the event name to find the value. The EvmEventPost( ) automatically finds any variables in an event whose name begins with an underscore, because the convention may require the same information to be added to the event twice. For more information about automatic name extension, see EvmEventPost(3).

An event can include any number of trailing reserved component names, in any order and in any component position following the event's base name. Each reserved component must be followed immediately by its associated value component.

You need not include a reserved component in an event's template name when registering the event, because the EVM name matching scheme finds the best match for a posted event. In the previous example, the template (and the base name of the event) is sys.unix.hw.registered. Reserved components are appended to the name to provide a further level of detail when the event is posted.

The convention of defining reserved component names that begin with a single underscore is reserved for system use. For local sites and third-party product vendors, establish your own conventions using a double underscore to start reserved component names, for example, _ _prod_code.

Comparing Event Names

Use EVM's API functions to compare the name of an event with the name you are looking for. Do not use strcmp(); the name of the incoming event may have more components than you expected. For more information on event name matching, see “Matching Event Names”.

Event Format Data Item

The format data item is a human-readable character string that summarizes the event. The format line is expanded and displayed in the following situations:

When the event is displayed using the evmshow command
When a program calls a display API function such as EvmEventFormat()

The format data item can include references to other data items contained in the event. Consider the following examples:

 Application close-down has started
	 Close-down of application $app has started

In the second example, $app is replaced by the name of the application, provided that the event contains a variable value with that name. The line is displayed as:

Close-down of application payroll has started

For more information about variables, see “Variable Data Items”.

A format line must begin with a brief and consistent identification of the posting component, and it must be a concise indication of what happened. Consider the following guidelines:

Do not write a full sentence, but ensure that the sentence can be clearly understood.
Do not write multiple sentences and do not include a period at the end of the message. Use the event's explanation text to provide the full and more grammatical description of what happened. For information on how explanation text is handled, see “Writing Event Explanation Text” .
Place the most important information — the phrase that tells the administrator what happened — at the beginning of the line to make it unnecessary for the administrator to look for the required information. Variable data is better placed towards the end of the line.
You need not include a reference to every variable in the format string. The administrator can easily obtain the variable data by requesting a detailed description of the event. However, you must include the key data, such as the name of a file system or device.

You can include variable names for substitution by preceding them with the $ character, for example, $app. If necessary, you can include standard data items by preceding their names with the @ character, for example, @host_name. You can specify standard data item names in uppercase or lowercase. However, variable names are case sensitive.

You can escape the special meaning of $ and @ characters in the format text by preceding them with a backslash (\). To include a literal backslash in the text, use a double backslash (\\). To separate the name of the data item or variable from adjacent text, you can surround the name in braces, for example, ${app}.

You can control the display of a variable or data item by following its name by a percent sign (%) and a format specifier. The format specifier can include the minimum width of the display field and the display format. For example, the following format string specifies that the variable named device_id must be displayed in hexadecimal notation and the temperature must be displayed as a floating-point number with 2 decimal places. For example:

The cabinet temperature for device 0x$device_id%x is $temperature%.2 degrees

The corresponding event is displayed as:

The cabinet temperature for device 0x7a is 62.4 degrees

For a full list of valid format specifiers, see evmshow(1) manpage.

Table 2-3 “Substituting Variables into Event Text” lists examples that show how variables and data items are substituted in to an event's format text to produce a formatted version of the event.

Table 2-3 Substituting Variables into Event Text

Format Data Item	Variable Data Item	Resulting Text
`Application started`	None	`Application started`
`Debug message: $msg`	`msg (string) = "Checkpoint reached"`	`Debug message: Checkpoint reached`
`Temperature too high: $temp`	`temp (float) = 87.2`	`Temperature too high: 87.2`
`This event was posted by @user_name`	None	`This event was posted by jem`

Event Priority Data Item

The priority of an event is used as the basis for selecting events for logging, sorting, reviewing, and taking action — human or automated. The priority is not used to establish the order in which events are delivered to subscribing EVM clients; events are delivered in the order in which they are received by the EVM daemon. The priority is an integer value in the range 0-700, with 0 being the least significant priority. For information about various priority levels, see EvmEvent(5).

You can expect that system administrators respond to event priorities in the following ways:

Configure the logger to log all events with priority 200 (notice level) or higher.
Configure the logger to send mail or issue an alert (for example, page someone) when an event of priority 600 (alert level) or higher is posted.
Use evmshow command to search for all events with priority 300 (warning level) or higher.
Use evmshow command to view logged events of all priorities to analyze problems or to verify that the system is operating correctly.

Consider the following guidelines while working with event priorities:

Do not hardcode the priority into the posting code. The priority must always be established in the template file.
When choosing the priority of an event, try to be consistent with other events in your own application and other similar applications. Do not try to use the full range of possible priorities if they are not applicable to your application. Use the priority information provided in EvmEvent(5) as a guideline, and check the existing templates to find out what priorities are being used by similar events.
Choose the priority of an event carefully and objectively. You must consider what you are reporting, not the possible consequences. For example, some application failures are critical, but many are not. The determination of which applications are critical must be left to a higher-level component. The higher-level component can subscribe to error events and issue a critical-level event if it is notified of an application error that it is critical.
Based on these considerations, events that indicate an error situation, but do not necessarily meet the critical criteria must be given a priority of 400 (error level), not 500 (critical level). On the other hand, an event reporting an excessive system temperature is almost always critical.
Event priorities for events that are related to each other must be established independently of each other. For example, if you post a failure event with a priority of 500 to indicate that an application has failed, and later you post a related event to indicate that is restored, the second event must have a lower priority, for example, 200. Giving the restore event a priority of 500 may cause an action that is not appropriate for the event.

I18N Catalog Name, Message Set ID, and Message ID Data Items

If your events contain text that is likely to be viewed by administrators in different countries, consider internationalizing them. To internationalize your events, you need to supply an I18N catalog file containing the format strings for all the events.




	NOTE: You must still include the text within the event, if the catalog file is not available when the event text is viewed.

The catalog file must be located according to normal I18N rules, and you must include the name of the file in your event specifications. You can provide different versions of the catalog file for different language locales. For more information, see the System Administration document.

You can optionally break the catalog file in to multiple message sets, and specify the message set ID in your events.




	NOTE: All messages pertaining to a particular event must belong to the same set.

The data items I18N_catalog and I18N_msgset_id define the catalog name and, if applicable, the message set for the format text and any string variables contained in the event with an associated message ID. The I18N_format_msg_id data item provides the message ID for the format text. If no catalog or message ID is supplied, the format text specified in the format data item is used to display the event summary.

For information on how to establish translations for event text, see “Establishing Translations for Event Text (I18N)” .

Reference Data Item

The reference data item is used to find the event explanation text for a detailed display of the event. The value of this item is passed to the event channel's explain script, along with the name of the event, to enable it to identify the explanation text associated with the event. The format of the field may be different for each channel, because each channel can have its own explain script. However, for events that are stored in and retrieved from the EVM log (the evmlog channel), this item must contain a string of the following form:

cat:catalog_name[:set_number]

Where:

catalog_name is the name of an I18N catalog containing the explanation text for the event.

To enable the explain script to locate the appropriate message, each explanation message in the catalog must begin with the name of the event enclosed in braces.

set_number is the number of the catalog message set containing the explanation. If no set number is supplied, the whole catalog is searched.

Third-party product vendors and local applications must not add explanations to the explanation catalog, evmexp.cat, but must provide separate catalogs. The value of this item must be set as a global data item in the template file.

For information about how to write event explanation text, see “Writing Event Explanation Text”.

Variable Data Items

You can use the variable data items in your events to provide any information that is different for each instance of an event. For example, if you are posting an event because you have detected a high temperature, you can include the actual temperature as a floating-point value in a variable data item.

Following are the properties of variable data items:

Name
Type
Value
Size (implicit for most types)
I18N message ID (optional — applies to string variables only)

A variable name can be made up of any combination of uppercase or lowercase alphanumeric characters and the underscore (_) character. Names must be meaningful. The variable name is carried inside the event. Large physical events have longer names.

A variable data item can be extracted and used directly by the subscriber, or combined with the event format text string to produce a formatted version of the event for display.

Table 2-4 “EVM's Variable Data Types” lists the variable types that EVM supports.

Table 2-4 EVM's Variable Data Types

Type Identifier	Size and Type
`EvmTYPE_BOOLEAN`	8-bit integer
`EvmTYPE_CHAR`	8-bit character
`EvmTYPE_INT16`	16-bit signed integer
`EvmTYPE_INT32`	32-bit signed integer
`EvmTYPE_INT64`	64-bit signed integer
`EvmTYPE_UINT8`	8-bit unsigned integer
`EvmTYPE_UINT16`	16-bit unsigned integer
`EvmTYPE_UINT32`	32-bit unsigned integer
`EvmTYPE_UINT64`	64-bit unsigned integer
`EvmTYPE_FLOAT`	32-bit floating-point value
`EvmTYPE_DOUBLE`	64-bit floating-point value
`EvmTYPE_STRING`	Null-terminated character string
`EvmTYPE_OPAQUE`	Binary data whose size must be specified explicitly

In general, because variables contain information that is specific to an instance of an event, they must be included in the event by the poster. However, for documentation purpose, it is also useful to include variable names and types along with dummy values, in the template version of the event. For information on templates, see “Designing Event Templates”.