evmtemplate(4)evmtemplate(4)NAMEevmtemplate - Event Manager template file
SYNOPSIS
event {
name event_name
format format_specifier
priority priority
i18n_catalog i18n_cat
i18n_set_id i18n_set
i18n_msg_id i18n_msg
reference reference_string
cluster_event cluster_event
var {
name variable_name
type variable_type
value variable_value
i18n_msg_id variable_value
}
}
DESCRIPTION
A template event is a description of an event that is held centrally by
EVM. The template is used for the following purposes: To register the
event with the EVM daemon, so that it will allow the event to be
posted. To centralize event information. This makes it easy to review
and maintain details such as the associated message text and the event
priority, and minimizes the amount of information that must be hard-
coded into an application.
On startup, and each time the evmreload -d command is run, the EVM dae‐
mon reads all valid event template files stored in the template direc‐
tory tree rooted at /usr/share/evm/templates, or in any directory tree
linked to that directory, including the local template tree rooted at
/var/evm/adm/templates. There is no limit to the number of template
files that can be installed in the tree, or to the number of templates
that can be included in each file.
Template file names must end with the suffix .evt, and the files must
be owned by root or bin, and must have permissions of 0400, 0600, 0440
or 0640 to be recognized. If template files are added, deleted or mod‐
ified while the daemon is running, the evmreload -d command should be
used to instruct the daemon to reconfigure itself. Refer to the evm‐
reload(8) reference page for more information.
Every template event must contain a name data item with at least two
components. A template typically also contains constant items such as
the event priority and the message format string.
When a client posts an event, it must include in the posted event a
name with at least three components. The posted event also typically
contains any applicable variable data along with environmental items
such as a timestamp and the name of the posting system.
When the EVM daemon receives a posted event, it searches its template
database for the template event whose name best matches the name in the
posted event. If it cannot find a matching template, the daemon
rejects the posting attempt. Otherwise, the daemon merges the data
items held in the two versions of the event, yielding a merged event
which it distributes to subscribers.
A template event name does not have to be identical to the name of a
posted event to be considered a match. If it has fewer name components
than the posted event, a template event is still considered a match if
all components in the template name exactly match their equivalent com‐
ponents in the posted name. If the template name is longer than the
name of the posted event however, it cannot be a match. In determining
the template that best matches the name of the posted event, the daemon
selects the matching template with the most components.
The following table shows some examples of event name matching. In the
final example, the template does not match the posted event because the
template has too many components.
───────────────────────────────────────────────────────────────
Posted Name Template Name Match?
───────────────────────────────────────────────────────────────
myco.myprod.env myco.myprod.env Yes
myco.myprod.env.temp.high.70 myco.myprod.env Yes
myco.myotherprod myco.myprod No
myco.myotherprod myco.myotherprod.start No
───────────────────────────────────────────────────────────────
The syntax of an event template file is identical to the syntax of a
file given as input to the evmpost command. The following keywords may
be specified in a template file: This keyword introduces an event
group. The body of the group is delimited by braces. Names the tem‐
plate event. The name must be made up of two or more components con‐
taining only alphanumeric and underscore (_) characters, and separated
by dot (.) characters. Event format text. The format_specifier is a
string that will be used to produce a formatted message for display if
the event is passed through the evmshow(1) command, the sysman(8) event
viewer, or the EvmEventFormat(3) library function.
If a format_specifier contains no special characters, it is dis‐
played unchanged as the event's message text. For example, if
evmshow encounters an event containing the following simple for‐
mat_specifier, it displays the string exactly as specified: EVM
logger: Logger started
If the format_specifier contains variable-specifier in the form
$variable_name, and either the posted event or the template
event contains a variable with that name, the variable_value
will be included in the formatted output in place of the vari‐
able_specifier. If no such variable is present, the vari‐
able_specifier is included in the output. For example, if an
event contains a variable called logname and the format_speci‐
fier:
EVM logger: Started eventlog $logname
then evmshow might display the event as: EVM logger: Started
eventlog /var/evm/evmlog/evmlog.20000228
If the format_specifier contains a data-item-specifier in the
form @item_name, the data-item-specifier is replaced with the
value of the corresponding data item from the event. For exam‐
ple, if an event contains a variable called message and the for‐
mat_specifier is:
EVM user msg (@user_name): $message
then evmshow might display the event as: EVM user msg (steve):
Engineering group is off-site today
If the data item is not present in the event, a hyphen character
(-) is output in its place. An @ character that is not associ‐
ated with a valid item name is unchanged in the output.
Any characters in the format_specifier that are not part of a
variable_name or data-item-specifier are output unchanged.
If no format_specifier is supplied in either the template file
or the posted event, a default event message is used when the
event is formatted for display. Indicates the importance of the
event, but does not affect the order of event distribution. The
priority must be an integer value in the range 0 (lowest) to
700. See the EvmEvent(5) reference page for the meanings of
specific priority values. The name of an I18N catalog file
holding text strings to be displayed in place of the strings
contained in the event. This item is used for internationaliz‐
ing events. If it is omitted, the strings contained in the
event will be used when the event is formatted for display.
Refer to the Programmer's Guide for more information. Identi‐
fies the message set within the i18n_cat to be used for transla‐
tion of all internationalized strings in the event. This item
is ignored if no i18n_cat is supplied. Identifies the I18N cat‐
alog message to be used in place of the format data item when
the event is formatted for display. This item is ignored if no
i18n_cat is supplied. If an i18n_set has been specified, the
i18n_msg must refer to a message identifier within the given
set. If the catalog is missing, or if the i18n_set or i18n_msg
values do not refer to a message in the catalog, the event's
format data item is used. This text string is intended to be
used by an event channel's explanation function to retrieve
explanation text for the event. The format of the string is
defined by the event channel. If this Boolean value is set to
TRUE, and the event is posted in a cluster environment, the
event is distributed to all members of the cluster. The default
value is FALSE. This keyword introduces a variable group, with
the body of the group being delimited by braces. An event may
include any number of variable groups.
Although actual variable values are most likely to be included
in the posted version of an event, and will override the values
specified in the template version, it is usually helpful to
include the variables in the template event as well, specifying
dummy values such as zero, to provide documentation of the
expected contents. For example, the template version will be
seen if the results of an evmwatch -i command are piped into
evmshow -d.
The following keywords are recognized in a variable group: The
name must be made up of alphanumeric and underscore characters.
The type of the variable item. See the EvmEvent(5) reference
page for a list of types. All EVM variable types may be speci‐
fied except for OPAQUE. If this keyword is omitted a type of
STRING is assumed. Value for the variable. A value must be
specified in the template, but usually should be overridden by
the value in the posted version of the event. Values supplied
in the template should be default or nonnormal values that will
be recognized as incomplete when the event is interpreted. For
STRING variables, the i18n_msg identifies the I18N catalog mes‐
sage to be used in place of the variable_value when the event is
formatted for display. This item is ignored if no i18n_cat is
supplied for the event. If an i18n_set has been specified, the
i18n_msg must refer to a message identifier within the given
set. If the catalog is missing, or if the i18n_set or i18n_msg
values do not refer to a message in the catalog, the vari‐
able_value is used.
Any items specified outside an event group are global items, which will
be included in each following template that does not include them
explicitly.
NOTES
If you are concerned with allowing your file to be used on other sys‐
tems that support EVM in the future, you should use the built-in macro
@SYS_VP@ in place of the first two components (sys.unix) of the name of
any system event. This will make it unnecessary to change the file if
the other system uses a different event name prefix.
EXAMPLES
The following file is an example of an event template file.
# My example event file priority 200
event {
name myco.myapp.env.humid
format "myapp: Humidity is $humidity"
var { name humidity type INT16 value 0 } }
event {
name myco.myapp.env.temp.normal
format "myapp: Temperature is normal ($temp)"
var { name temp type FLOAT value 0.0 } }
event {
name myco.myapp.env.temp.high
priority 500
format "myapp: Temperature exceeds 80F ($temp)"
var { name temp type FLOAT value 0.0 } }
event {
name myco.myapp.env.app_terminated
priority 300
format "myapp: Production monitoring terminated - code
$exit_code"
var { name exit_code type INT16 value 0 } }
FILES
The root of the directory tree containing system event template files.
The root of the directory tree containing local event template files.
This directory is accessed from the system template directory through a
symbolic link.
SEE ALSO
Commands: evmpost(1), evmshow(1), evmd(8), sysman(8)
Routines: EvmEventCreate(3), EvmEventDump(3), EvmEventFormat(3),
EvmEventPost(3), EvmItemSet(3)
Files: evmdaemon.conf(4)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
Programmer's Guide
System Administration
evmtemplate(4)
