evmtemplate - Event Manager template file
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
}
}
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 daemon reads all valid event template files stored
in the template directory 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 modified while the
daemon is running, the evmreload -d command should be used
to instruct the daemon to reconfigure itself. Refer to
the evmreload(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 components
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 template
event. The name must be made up of two or more components
containing 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 displayed unchanged as the event's message
text. For example, if evmshow encounters an
event containing the following simple format_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 variable_specifier.
If no such variable is present,
the variable_specifier is included in the output.
For example, if an event contains a variable called
logname and the format_specifier:
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 example, if an
event contains a variable called message and the
format_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 associated 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 internationalizing 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. Identifies
the message set within the i18n_cat to be
used for translation of all internationalized
strings in the event. This item is ignored if no
i18n_cat is supplied. Identifies the I18N catalog
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 specified
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
message 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 variable_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.
If you are concerned with allowing your file to be used on
other systems 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.
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 }
}
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.
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)
[ Back ] |
