EvmEvent - The structure of an EVM Event
An EVM event is a self-contained data structure, which can
be manipulated 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 [Toc] [Back]
The event structure includes two types of data items:
Standard data items, with predefined names 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 [Toc] [Back]
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 combined 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 nonzero,
the system time when the latest
occurrence of this event was
generated.
Event Identifier
EVENT_ID Identifies the event. See the
description following this table.
Host Name
HOST_NAME Name of the posting node.
Host IP Address
HOST_IP IP address of the posting node.
Cluster Event
CLUSTER_EVENT In a cluster environment, a value of
EvmTRUE indicates that the event was
posted on behalf of the cluster, not
the individual node, and will be
distributed to every node in the
cluster.
Cluster Name
CLUSTER_NAME In a cluster environment, the name
of the posting cluster.
Cluster IP Address
CLUSTER_IP In a cluster environment, the IP
address of the posting cluster.
Cluster Member ID
MEMBER_ID In a cluster environment, the node's
cluster ID.
Kernel Only
KERNEL_ONLY If present and EvmTRUE for an event
generated in the kernel, the event
will not be 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 posting
process.
Priority
PRIORITY Indicates the importance of the
event. Does not affect the order of
event distribution. 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 catalog.
I18N message id
I18N_MSG_ID I18N message id for the event.
Format
FORMAT Event format text. See the
EvmEventFormat(3) and evmtemplate(4)
reference pages for a description of
the format string.
Reference
REF Reference to event explanation text.
-----------------------------------------------------------
Event Name [Toc] [Back]
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 [Toc] [Back]
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. This may happen if the
event is a cluster event posted in another node. 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 [Toc] [Back]
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.
----------------------------------------------------------------
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 imminent 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 attention.
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 normally.
Events in this range
typically will not be
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
will not be 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 Id [Toc] [Back]
If you plan to internationalize your events, you will 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 id in the event
- but 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 will probably want to supply
these items as global values, so that you need only to
specify them once.
Cluster event [Toc] [Back]
You should set the cluster event data item only if your
application is cluster-aware, and is posting the event on
behalf of the cluster, rather than an individual node.
Cluster events are distributed to all nodes in the cluster.
Formatting an Event for Display [Toc] [Back]
Although an event is an opaque binary structure, it can be
formatted into a human-readable string by using the
evmshow(1) command or by calling the EvmEventFormat(3)
function. Formatting is essential for human-oriented output,
but may not be necessary for an application program
that will simply extract any variable data the event contains,
and take 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 $ character - for example $temp. You include
standard data items by preceding their names with @ - for
example, @timestamp.
The EvmEventFormat(3) routine automatically converts data
items or variables into displayable form, regardless of
their types.
You can escape the special meaning of a $ or @ characters
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 will result 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 [Toc] [Back]
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: 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 interpreted
directly. The size must be specified
explicitly.
-----------------------------------------------------------
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)
EvmEvent(5)
[ Back ] |
