EvmEvent(5)EvmEvent(5)NAME
EvmEvent - structure of an EVM Event
DESCRIPTION
An EVM event is a self-contained data structure, which can be manipu‐
lated and accessed using EVM API functions. Application code can:
· Create, duplicate and destroy an event.
· Set and retrieve the values of standard data items contained within
the event.
· Add variable data items to the event, and set and retrieve their
values.
· Post the event to the EVM daemon for distribution to subscribers.
· Read events from an open file descriptor.
· Write events to an open file descriptor.
Command line utilities are provided that allow users access to these
capabilities.
The Contents of an Event
The event structure includes two types of data items:
1. Standard data items, with predefined names
2. Variable data items, with names and types defined at the time they
are added to the event
When you create an event you can include as many data items as you
like. When you post the event, the API functions automatically add
the standard items which pertain to the current environment, such as
the host name and timestamp.
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.
Data item/Id Description
─────────────────────────────────────────────────────
Event Name
NAME Names the event. Must match a
name in the daemon's template
database if the event is to be
posted.
Time Posted
TIMESTAMP UNIX system time when the
first occurrence of this event
was generated.
Repeat Count
REPEAT_COUNT Number of instances of the
same event that have been com‐
bined into a single stored
event. The Time Posted and
Last Timestamp items indicate
when the first and last
instances of the event were
posted.
Last Timestamp
LAST_TIMESTAMP If Repeat Count is present and
non-zero, the system time when
the latest occurrence of this
event was generated.
Event Identifier
EVENT_ID Identifies the event. See the
description following this ta‐
ble.
Kernel Only
KERNEL_ONLY If present and for an event
generated in the kernel, the
event is not propagated from
the kernel to user space.
Process ID
PID PID of the process which
posted the event.
Parent Process ID
PPID PID of the parent of the
process which posted the
event.
User name
USER_NAME Name of the owner of the post‐
ing process.
Priority
PRIORITY Indicates the importance of
the event. Does not affect
the order of event distribu‐
tion. See the description
following this table.
I18N catalog
I18N_CATALOG Name of I18N catalog file for
internationalized events.
I18N message set id
I18N_SET_ID Identifies the message set
within the I18N message cata‐
log.
I18N message id
I18N_MSG_ID I18N message identification
for the event.
Format
FORMAT Event format text. See the
EvmEventFormat(3) and evmtem‐
plate(4) reference pages for a
description of the format
string.
Reference
REF Reference to event explanation
text.
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 syntacti‐
cally 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 combi‐
nation 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, let‐
ting 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 compo‐
nents 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:
· Each posted event receives an unsigned integer event identification
number, with a value greater by one than that of the previous event
posted through the same EVM daemon.
· The event identifier of the first event posted after the daemon is
started or restarted is zero.
· The event identifier wraps back to zero after it has reached its
maximum value.
· If a daemon receives an event that already contains an identifier,
it does not generate a new identifier for the event.
· New event identifiers are assigned only to events which the daemon
validates and accepts for distribution.
· If an event is accepted and does not already contain an identifier,
a new identifier is assigned to it even if there are no subscribers
for the event.
Event Priority
EVM uses an event's priority value solely for filtering, sorting and
presentation purposes - it does not use it to prioritize the distribu‐
tion 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 pri‐
ority, and a description of the priority.
───────────────────────────────────────────────────────────────────────
Default
EVM Priority/Name Notification Description
───────────────────────────────────────────────────────────────────────
700
Emergency Log, mail to root A dangerous situation has been
detected and immediate action
either is required or has been
taken.
600 - 699
Alert Log, mail to root A dangerous situation is immi‐
nent and immediate action
either is required or has been
taken.
500 - 599
Critical Log, mail to root A failure has been detected
that renders some part of the
system inoperable.
400 - 499
Error Log A non-critical failure has
been detected in or by some
component of the system or
application.
300 - 399
Warning Log Some aspect of the system or
application requires atten‐
tion.
200 - 299
Notice Log Notification of an expected
operational event that the
component is designed to deal
with.
100 - 199
Information None A normal operational event,
for example, an application
has started or terminated nor‐
mally. Events in this range
typically is not saved in the
system EVM log file.
1 - 99
Debug None Program debug information.
Events in this range may be
monitored for informational
purposes, but typically is not
saved in the system EVM log
file.
0
None Application Priority 0 should be used for
events that are specifically
intended to be subscribed to
by programs, and are not
expected to be interesting to
administrators.
───────────────────────────────────────────────────────────────────────
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 command or by calling the
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 You include standard data items by pre‐
ceding their names with for example
The routine automatically converts data items or variables into dis‐
playable 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
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 under‐
score are reserved for system use.
EVM's variable data items have these properties:
· A name
· A type
· A value
· A size (implicit for most types)
· An I18N message id (for string variables only)
The following table shows the variable types that EVM supports:
Type Identification Remarks
───────────────────────────────────────────────────────
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 - cannot be inter‐
preted directly. The size must
be specified explicitly.
───────────────────────────────────────────────────────
Restrictions
Data types and cannot be used for events posted within the kernel.
SEE ALSO
Commands
evmshow(1).
Routines
EvmEventFormat(3).
Files
evmtemplate(4).
Event Management
EVM(5).
EvmEvent(5)
