EvmFilter(5) File Formats Manual EvmFilter(5)
NAME
EvmFilter - 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 only be 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 fil-
ters.
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 speci-
fied 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 consid-
ered to match when the event name matches as many components as included in the filter.
The event-name-specifier may include the * and 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 equality-
operator. May be specified as prio. 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 time. Selects events that meet the age specification. See the descrip-
tion of age-specifier. The equality-operator must specify less-than or less-than-or-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 the
EvmEvent(5) reference page for a description of the event_id. See the following table for a description of equality-operator. 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 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 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-of-month: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 time-range-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 the evmfilterfile(4) reference page 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.
NOTES
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 sup-
ported by the older system, log into the system and view this reference page.
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 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 com-
ponents myco.myapp.
"[name myco.myapp]" Any event with a name that has the first two com-
ponents 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 1st, 2000.
"[time 2000:6:1,3:*:*:*:*]" Any event posted on June 1st or June 3rd, 2000.
"[time 2000:6:1-3:*:*:*:*]" Any event posted between June 1st and June 3rd,
2000.
"[time 2000:6:1-3,5-7:*:*:*:*]" Any event posted between June 1st and June 3rd,
2000, or between June 5th and June 7th, 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 1st,
2000.
"[before 2000:6:1:03:00:00]" All events occurring before 3:00 a.m. on June
1st, 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] & All syslog events occurring today or yesterday.
[age < 2d]"
"[name sys.unix.syslog] and All syslog events occurring on June 1, 2 or 3,
[time 2000:6:1-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.
---------------------------------------------------------------------------------------
SEE ALSO
Commands: evmget(1), evmshow(1), evmwatch(1)
Routines: EvmConnSubscribe(3)
Files: evmfilterfile(4),
Event Management: EVM(5)
EVM Events: EvmEvent(5)
delim off
EvmFilter(5)