 |
Index for
Section 5 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
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 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:
Name event-name-specifier
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.
Priority equality-operator integer
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.
Timestamp time-range-specifier
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.
Age equality-operator age-specifier
Selects events that meet the age specification. See the description 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.
BEFore absolute-time-specifier
All events with a timestamp that is earlier than the absolute-time-
specifier are passed. See the description of absolute-time-specifier.
SINce 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.
Host_name host-name
All events posted from the machine host-name are passed. May be
specified as host.
CLUster_name cluster-name
All events posted from the cluster cluster-name are passed. May be
specified as cluster.
EVent_id equality-operator integer
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 EVent_id
keyword may be abbreviated to ID.
NONE or 0
A filter value of none or 0 passes no events.
ALL or 1
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-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 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.
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 supported 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 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 <
2d]"
All syslog events occurring today or
yesterday.
"[name sys.unix.syslog] and [time
2000:6:1-3:*:*:*:*]"
All syslog events occurring on June
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.
___________________________________________________________________________
SEE ALSO
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)
|
Index for
Section 5 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|