EvmFilter(5)EvmFilter(5)NAMEEvmFilter - EVM (Event Management) event filter
DESCRIPTION
An event filter is a specification of a set of interesting events.
Event subscribers use filters to tell the EVM daemon which events they
want to receive. For example, one subscriber may be only interested in
receiving events reporting hardware errors, while another may want to
receive all high-priority events, regardless of what they are report‐
ing. If a subscriber does not set a filter, it will receive no events.
The Event Viewer and some of the EVM user commands also use filters to
select events for viewing or processing.
A filter is an ASCII character string. It can be very simple or arbi‐
trarily complex. Complex filters are created by combining simple fil‐
ters.
A simple filter has the following format:
The format of expr is specific to the type of filter. The left and
right square brackets and are required. Keywords may be specified in
any mix of upper and lower case, and where the underscore character is
included in a full-length keyword (as in it may be omitted. Keywords
may be abbreviated, and in the following paragraphs the minimum abbre‐
viation for each is indicated by upper-case letters.
Possible values for keyword and the associated expr are as follows:
Selects events with a name matching the event-name-specifier.
Names are considered to match when the event name matches as
many components as included in the filter.
The event-name-specifier may include the and the characters
as wildcards in any component position. The represents 0 or
more components with any value. The represents exactly one
component. Any event-name-specifier includes an implied
trailing wildcard.
Only events with a priority meeting the specified evaluation will be
passed.
The integer value may be 0 to 700, inclusive. See the fol‐
lowing table for a description of equality-operator. May be
specified as
All events with a timestamp that is within the
time-range-specifier are passed. See the description of
time-range-specifier. May be specified as
Selects events that meet the age specification.
See the description of age-specifier. The equality-operator
must specify or meaning "newer than", or or meaning "older
than." The or operators are not allowed.
All events with a timestamp that is earlier than the
absolute-time-specifier are passed. See the description of
absolute-time-specifier.
All events with a timestamp that is equal to or later than the
absolute-time-specifier are passed. See the description of
absolute-time-specifier.
All events with an
event_id meeting the specified evaluation will be passed.
See EvmEvent(5) for a description of the event_id. See the
following table for a description of equality-operator. The
keyword may be abbreviated to
A filter value of none or 0 (zero) passes no events.
A filter value of all or 1 passes all events.
The available equality-operator specifiers and their alternate repre‐
sentations are shown in the following table. The alternate representa‐
tions may be used in any mix of upper and lower case.
Operator Alternate Meaning
─────────────────────────────────────────────
= eq Equal
> gt Greater Than
< lt Less Than
>= ge Greater Than or Equal
<= le Less Than or Equal
!= ne Not Equal
─────────────────────────────────────────────
An age-specifier comprises an integer value followed immediately by one
of the letters or An age-specifier produces an absolute time value rel‐
ative to the present time, and is most likely to be useful in retriev‐
ing historical events through or the event viewer. It is not meaning‐
ful to use an age-specifier when setting a filter for use by the EVM
logger or evmwatch.
If a period of weeks is specified, the period is converted to days by
multiplying it by 7. When calculating an absolute time for an age
specified in weeks or days, the first day is always regarded as the
period from the previous midnight until the present time, and earlier
days are counted from midnight to midnight. For example, if an age-
specifier of is given, events are selected relative to 12:00 a.m. on
the same day. A value of would select events relative to 12:00 a.m.
the previous day. A value of is valid, and is equivalent to See the
following examples for more information.
If a period of hours, minutes or seconds is specified, an absolute time
is calculated by subtracting the age from the current time, without
regard to day boundaries. For example, if an age-specifier of is given
at events are selected relative to 15:23:14 on the previous day.
A time-range-specifier consists of seven colon-separated fields in the
following format:
Any component in the time range may be replaced by an asterisk charac‐
ter as a wildcard, meaning that any value in this component will match
the filter. You can specify multiple discrete values for a component
by separating them with a comma. You can specify a range by using a
hyphen to separate the starting and ending values for the range. An
absolute-time-specifier is very similar to the time-range-specifier.
It has only six components, and does not allow the use of wild cards.
It has the following format:
In both forms of time specification, the range of values for each com‐
ponent is shown in the following table.
Specifier Range
─────────────────────────────
year 1970 to 2030
month-of-year 1 to 12
day-of-month 1 to 31
day-of-week 0 (Sun) to 6
hours 0 to 23
minutes 0 to 59
seconds 0 to 59
─────────────────────────────
Any expression may be inverted (logically negated) by the use of the
NOT operator, the exclamation mark or the keyword
A complex filter is composed of two or more simple filters, combined
using the AND or keyword and OR or keyword logical operators. Compo‐
nent filter expressions may be grouped in parentheses and to set the
precedence of test operations. The order of precedence of logical and
grouping operators (highest to lowest) is:
Event filters can be direct or indirect. A direct filter is a text
string appearing at the point of filter specification. An indirect
filter is contained in a file, and is referred to using the following
syntax:
See evmfilterfile(4) for more information about using indirect filters.
If an event being evaluated does not contain the item being compared in
a filter expression, the expression always yields no match. For exam‐
ple, if the timestamp item is missing from the event and you include
the before keyword in a filter string, that part of the filter will
return no match.
Notes
Successive versions of EVM may evolve the filter syntax by adding new
keywords or operators.
EXAMPLES
The following table shows a number of filter specifications, and the
interpretation given to each.
Filter String Interpretation
───────────────────────────────────────────────────────
"[name *]" Any named event.
"[name myco.*]" All events with
names that start
with
"![name myco.*]" All events with
names that do not
start with
"[name ?.?.?]" Any event with a
name that has at
least three compo‐
nents.
"[name myco.myapp.*]" Any event with a
name that has the
first two components
"[name myco.myapp]" Any event with a
name that has the
first two components
Identical in meaning
to the previous fil‐
ter string.
"[name sys.unix.syslog]" Events which have as
the first three com‐
ponents of the name.
"[name myco.myapp.*.showme]" Any event name that
starts with the com‐
ponents and ends
with no matter how
many components are
included between.
"[age < 1d]" Any event posted
today.
"[age < 4w]" Any event posted
within the last 4
weeks.
"[age lt 30s]" Any event posted
within the last 30
seconds.
"[age gt 1d]" Any event posted
before today.
"[time 2000:6:1:*:*:*:*]" Any event posted on
June 1, 2000.
"[time 2000:6:1,3:*:*:*:*]" Any event posted on
June 1 or June 3,
2000.
"[time 2000:6:1-3:*:*:*:*]" Any event posted
between June 1 and
June 3, 2000.
"[time 2000:6:1-3,5-7:*:*:*:*]" Any event posted
between June 1 and
June 3, 2000, or
between June 5 and
June 7, 2000, inclu‐
sive.
"[time *:*:*:*:00-02:*:*]" All events occurring
between midnight and
2:59:59 a.m., inclu‐
sive.
"[since 2000:6:1:03:00:00]" All events occurring
after 3:00 a.m. on
June 1, 2000.
"[before 2000:6:1:03:00:00]" All events occurring
before 3:00 a.m. on
June 1, 2000.
"[prio > 500]" All events with pri‐
ority greater than
500
All events that have names starting with myco.myapp and priority at
least 500.
All events that have names starting with myco.myapp or that have prior‐
ity at least 500.
All evm events occurring today or yesterday.
All evm events occurring on June 1, 2 or 3, 2000.
Passes no events.
Passes no events.
Passes all events.
Passes all events.
Specifies an indirect filter.
The filter string is the default filter contained in a filter
file named or
Specifies an indirect filter. The filter string is the filter named
contained in a filter file named or
SEE ALSO
Commands
evmget(1), evmshow(1), evmwatch(1).
Routines
EvmConnSubscribe(3), EvmFilterCreate(3), EvmFilterDestroy(3), EvmFil‐
terIsFile(3), EvmFilterReadFile(3), EvmFilterSet(3), EvmFilterTest(3).
Files
evmfilterfile(4).
Event Management
EVM(5).
EVM Events
EvmEvent(5).
EvmFilter(5)