EvmFilter - Event filter
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 reporting. 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 arbitrarily complex. Complex filters are created
by combining simple filters.
A simple filter has the following format: [keyword expr] |
all | 1 | none | 0
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 host_name), it may be
omitted. Keywords may be abbreviated, and in the following
paragraphs the minimum abbreviation for each is indicated
by upper-case letters.
Possible values for keyword and the associated expr are:
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 following table for a description of equalityoperator.
May be specified as prio. All events
with a timestamp that is within the time-rangespecifier
are passed. See the description of timerange-specifier.
May be specified as time.
Selects events that meet the age specification.
See the description of age-specifier. The equality-operator
must specify less-than or less-thanor-equal,
meaning "newer than", or greater-than or
greater-than-or-equal, meaning "older than." The
"equal" or "not equal" 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
posted from the machine host-name are passed. May
be specified as host. All events posted from the
cluster cluster-name are passed. May be specified
as cluster. 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 equalityoperator.
The EVent_id keyword may be abbreviated
to ID. A filter value of none or 0 passes no
events. A filter value of all or 1 passes all
events.
The available equality-operator specifiers and their
alternate representations are shown in the following
table. The alternate representations 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 w (weeks), d (days), h
(hours), m (minutes) or s (seconds). An age-specifier
produces an absolute time value relative to the present
time, and is most likely to be useful in retrieving historical
events through evmget or the event viewer. It is
not meaningful 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 1d is given, events are selected relative
to 12:00 a.m. on the same day. A value of 2d would
select events relative to 12:00 a.m. the previous day. A
value of 0d is valid, and is equivalent to 1d. 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 24h is given at 15:23:14,
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: year:month-of-year:day-ofmonth:day-of-week:hours:minutes:seconds
Any component in the time range may be replaced by an
asterisk (*) character 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 timerange-specifier.
It has only six components, and does not
allow the use of wild cards. It has the following format:
year:month-of-year:day-of-month:hours:minutes:seconds
In both forms of time specification, the range of values
for each component 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 NOT.
A complex filter is composed of two or more simple filters,
combined using the AND (& or keyword AND) and OR (|
or keyword OR) logical operators. Component 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: @filename:filtername
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 example, 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.
Successive versions of EVM may evolve the filter syntax by
adding new keywords or operators. If you use EVM's remote
connection facilities to connect to a system running an
older version of EVM, and you attempt to retrieve or subscribe
for events using a filter with syntax that is not
supported by the older version, you will receive a
response indicating that the filter is invalid. To determine
what syntax is supported by the older system, log
into the system and view this reference page.
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 myco.
"![name myco.*]" All events with names that do not
start with myco.
"[name ?.?.?]" Any event with a name that has at
least three components.
"[name myco.myapp.*]" Any event with a name that has the
first two components myco.myapp.
"[name myco.myapp]" Any event with a name that has the
first two components myco.myapp.
Identical in meaning to the previous
filter string.
"[name sys.unix.syslog]" Events which have sys.unix.syslog as
the first three components of the
name.
"[name myco.myapp.*.showme]" Any event name that starts with the
components myco.myapp and ends with
showme, 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, inclusive.
"[time *:*:*:*:00-02:*:*]" All events occurring between midnight
and 2:59:59 a.m., inclusive.
"[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 priority greater
than 500
"[name myco.myapp] & [pri >= 500]" All events that have names starting
with myco.myapp and priority at
least 500.
"[name myco.myapp] | [pri >= 500]" All events that have names starting
with myco.myapp or that have priority
at least 500.
"[name sys.unix.syslog] & [age < All syslog events occurring today or
2d]" yesterday.
"[name sys.unix.syslog] and [time All syslog events occurring on June
2000:6:1-3:*:*:*:*]" 1, 2 or 3, 2000.
"none" Passes no events.
"0" Passes no events.
"all" Passes all events.
"1" Passes all events.
"@sys" Specifies an indirect filter. The
filter string is the default filter
contained in a filter file named sys
or sys.evf.
"@sys:advfs" Specifies an indirect filter. The
filter string is the filter named
advfs contained in a filter file
named sys or sys.evf.
----------------------------------------------------------------------------
Commands: evmget(1), evmshow(1), evmwatch(1)
Routines: EvmConnSubscribe(3), EvmFilterCreate(3), EvmFilterDestroy(3), EvmFilterIsFile(3), EvmFilterReadFile(3),
EvmFilterSet(3), EvmFilterTest(3)
Files: evmfilterfile(4)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
EvmFilter(5)
[ Back ] |