EvmEvent(5)

The Contents of an Event

The event structure includes two types of data items:

Standard Data Items

Standard data items are those which are commonly required in an event, and which are understood and may be acted upon by EVM. The following table is a list of the standard data items that may be contained in an event. The identifier is the keyword used to post, display, or format the item.

Event Name

The event name is the primary means of identifying an event. It must be present for an event to be posted. Although it can be any syntactically valid string, the name should generally identify the posting facility and indicate what happened.

The event name is an ASCII character string, made up of a dot-separated series of components, with the left-most component representing the top of a notational hierarchy. Component substrings may include any combination of letters, digits and underbar characters. There is no restriction on the number of components that can be included in an event name. An event template must contain at least two components. An event must contain at least three components to be accepted for posting.

The naming scheme provides an open-ended way to identify events, letting you provide detail to any level. Careful naming gives the system administrator an intuitive and precise way to select events for viewing and monitoring and facilitates the identification of the system components which issue events and the recognition of patterns that warn of problems. The more detail included in the event name, the more precise the specification criteria can be.

Event Identifier

The event identifier data item is a numeric quantity, assigned to an event by the EVM daemon as the event is posted. In combination with the host and timestamp data items, the value can be used to produce a unique identity for an event.

The daemon assigns identifiers according to the following rules:

Event Priority

EVM uses an event's priority value solely for filtering, sorting and presentation purposes - it does not use it to prioritize the distribution sequence. The priority is an integer value in the range 0-700, with zero being the least significant priority. This table indicates the event priority, the default action taken by evmlogger for that priority, and a description of the priority.

Catalog Name and Message Set Identification

If you plan to internationalize your events, you need to supply an I18N catalog file containing the format strings for all of the events, and include the name of the file in the event. You also can break the file into multiple message sets, and give the message set identification in the event. However, note that all messages pertaining to a particular event must belong to the same set. If all events described in a single template file use messages from the same catalog or message set or both, you probably want to supply these items as global values, so that you need only to specify them once.

Formatting an Event for Display

Although an event is an opaque binary structure, it can be formatted into a human-readable string by using the evmshow command or by calling the EvmEventFormat() function. Formatting is essential for human-oriented output, but may not be necessary for an application program that simply extracts any variable data the event contains, and takes the necessary action.

The starting point for formatting an event is the format data item. A format is a text string that may contain a simple piece of text, the names of standard data items, or the names of variables whose values are to be substituted into the text, or any combination of these.

You include variable names for substitution by preceding them with a dollar ($) character, for example $temp. You include standard data items by preceding their names with @, for example @timestamp.

The EvmEventFormat() routine automatically converts data items or variables into displayable form, regardless of their types.

You can escape the special meaning of a $ or @ character in the format text by preceding it with a backslash (\). To include a literal backslash in the text, use a double backslash.

If an event does not include a format data item, formatting it results in a default text string that includes the event name and any variables the event may contain.

If the event includes a repeat count, then the repeat count is prepended to the output in the form [repeat_counttimes].

Variable Data Items

You can use variable data items in your events to provide data that may be different each time the event is posted.

You can give the variable any name you like. The name is a string that is carried with the event, and can be used by a subscriber to extract the data in its original form. A variable name can be made up of any combination of upper or lower case alphanumeric characters and the underscore character. By convention, names beginning with an underscore are reserved for system use.

EVM's variable data items have these properties:

The following table shows the variable types that EVM supports:

Restrictions

Data types EvmTYPE_FLOAT and EvmTYPE_DOUBLE cannot be used for events posted within the kernel.

Commands

evmshow(1).

Routines

EvmEventFormat(3).

Files

evmtemplate(4).

Event Management

EVM(5).