 |
Index for
Section 5 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
EvmEvent(5)
NAME
EvmEvent - The structure of an EVM Event
DESCRIPTION
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
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
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 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 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 msgset 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
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:
· 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
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
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
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
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_count times].
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:
· 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.
RESTRICTIONS
Data types EvmTYPE_FLOAT and EvmTYPE_DOUBLE cannot be used for events
posted within the kernel.
SEE ALSO
Commands: evmshow(1)
Routines: EvmEventFormat(3)
Files: evmtemplate(4)
Event Management: EVM(5)
|
Index for
Section 5 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|