Event Filters

Real-time event monitoring is an important feature of most remote device management applications. It may be used for monitoring security systems or medical applications, for inspection of IT equipment failures, etc. Devices usually generate many different events, and when you're running a system which contains many Devices, your LinkServer will get many events which aren't very important, but some which might be critical. So, when you have a human operator, it is unnecessary for them to monitor all events, but some events may require attention. To filter out the less significant events and concentrate on the more important ones, use Event Filters. Filters also help monitor different system events, such as Scheduled Job execution, Alert escalation etc.

An Event Filter is used to hide non-significant events and highlight the most important ones. It is a set of rules instructing the Event Log component in LinkServer User Interface (e.g. Event Log in AggreGate Client) to adjust the visualization of incoming events for the needs of the user's business role.

Working With Event Filters

To start using an event filter, the user must activate it by selecting it from the Filters drop-down list in the Event Log component. This is what filter selection looks like in the AggreGate Client Event Log:

The Event Log component has two sections:

Filters may be selected separately for each section. If a filter is selected in Real-time Events section, the Event Log starts listening for all categories of events listed in the Event Data table. When a filter is selected in the Event History section, LinkServer loads all events satisfying Filter Rules list (see below) from the database and shows the first few rows, allowing the user to scroll through the whole list and sort it.

The most important property of an event filter is Filter Rules, defining which events to show. During filter activation every Enabled record in the Filter Rules table is processed and events satisfying the following conditions are shown in event log:

All of these field names, in bold above, are described below. Each filter record may also define a highlighting color that will be used to highlight events of this category in Event Log.

By default, the following columns are visible in the Event Log:

Event Level column uses a set of icons to indicate level of events:

Event Highlighting

Events can be color-highlighted in the Event Log. This color may be defined in the Filter Rules record or by a Custom Highlighting rule. Custom highlighting rules have higher priority, so if an event matches a custom highlighting rule, the color defined for it in Filter Rules will be ignored.

The color defined by a custom highlighting rule is used to highlight an event if:

Here is what the event list looks like in the AggreGate Client Event Log:

Administering Event Filters

Event Filter Structure

Each event filter has several properties:

The Filter Rules property defines which events are shown when the event filter is active, while Filter Info, Primary Visible Fields and Additional Visible Fields describe which parameters and fields are shown for every event. More information about filter properties can be found here.

Event Categories

An event category is a way to "group" events: A category contains all events of a certain type which happened in all contexts corresponding to a certain context mask. For example, you might make a category containing all of the login events of all Device Serveres belonging to the user joe. You could call it Joe's Device Server Logins and use it to view just this isolated data set -- which of Joe's devices logged in, and when.

Event categories are stored in one single global list in <%LS %>. This list is used as a template for all newly created event filters: Its content is copied to the Filter Rules property of every new created event filter. This property can the be edited (and the list thus changed) without affecting the global Event Categories list.

To edit the global list, you need to be able to access your Event Filters context at Admin permission level. You could then execute the Edit Event Categories action and modify the list. When the master list of event categories is changed, existing event filters are not affected, but new filters "pass" only those events whose type and context mask match those defined in the Categories list.

Every event filter may be changed to show other events by editing its Filter Rules: the existing table in Filter Rules (stemming from the Event Categories list) is just a suggestion.

The table of event categories has three fields:

The table of event categories shown in Filter Rules contains several additional fields which let you further filter every event type. These are fields such as Filter Expression (explained later on), Event Level, etc. They're all described under Event Filters.

The Sequence of Creating an Event Filter

So, given this information about Event Categories, you can now see what's the ordinary sequence of operations to get a newly-created filter to pass only the data you're interested in:

Default List of Event Categories

The default list of event categories contains events that may be useful for most system administrators and operators. Here is a brief overview of its contents:

Here is what the list of categories looks like in AggreGate Client:

Filter Expressions

Filter expressions help fine-tune a given filter by showing only events that match a specific formula defined by an AggreGate Expression, or highlighting these events in color within a broader list of events. This expression may include references to the cells of an event's Data Table containing event-specific data. (If you're not sure what's an event's Data Table, check out Event Data Table within Events).

For example, the Data Table for a login event contains a username field. So, when filtering for login events, you could use a filter expression containing a reference to this table, to further refine your filter and pass only logins of the user Joe.

It is also possible to refer the filtering environment and data from various LinkServer contexts.

How References Are Used Within filter Expressions

Filter Expressions in Filter RULES

Every record in Filter Rules table may have its own Filter Expression. This can be a bit tricky to grasp: the Filter Rules table is already a filter in itself -- it defines a mask, an event name and an event level, and only events matching these categories are shown. But the optional filter expression lets you make the filter even more granular and accurate. What if you have events that all match the mask, event name and level, and yet you only want to show some of them? That's where a filter expression comes in handy. Again, this may seem abstract for now, but you can skip down to the example and it'll all make much better sense.

The filter expression must resolve to a Boolean value: TRUE of FALSE. If it resolves to FALSE, the event is filtered out and not shown in Event Log. If it resolves to TRUE, the event passes the filter and is shown.

Example:

Assuming that we are monitoring user logins. In Filter Rules, we have a category with the following settings:

It we double-click any login event shown in Event Log, we'll see its data in a Data Table Editor component. Here is a screenshot from the Data Table Editor in AggreGate Client:

We see that data for the Login event has two fields: Username (authenticated user) and Permissions (current contents of his permissions table).

To refer to these fields from our Filter Expression we need to use field names instead of their descriptions. Field names are shown in tooltips that appear when the mouse hovers over field description:

From this tooltip we see that the first field's name is username. This name may be used to create a Filter Expression that will let us to filter out only logins of a particular user.

Let's say we want to filter only Charlie's logins. We'll use the following Filter Expression:

{username} == 'charlie'

When this expression is evaluated, the {username} reference resolves to the contents of the username field in the event's Data Table. This field is a String type, so the resolution results in a String value. This value is then compared with the String literal charlie. If they are equal, the event passes the filter and it is shown in the Event Log, otherwise it is filtered out.  When we put this expression in the Filter Expression field of the Filter Rules table and activate the filter, only logins of Charlie will be visible in Event Log.

The exact effect shown in this example could have also been accomplished by restricting the filter's context to users.charlie, but this example just serves to illustrate the point. It's more useful if you want to display logins from several users, for example, but not display logins from other users.

Filter Expressions in Custom Highlighting

Every record in the Custom Highlighting table may also contain a Filter Expression. If such an expression is set and evaluates to TRUE, custom highlighting rule is applied to this event.

Example:

Some events are critical to the functioning of the system. Such events fire at a high level, such as Error or Fatal. We can highlight events that were fired at Error level in orange. Event level is indicated with a special icon in the Event Log, but custom highlighting might help system operators notice these events more easily.

To highlight events coming from Devices, we have to add a new rule to the Custom Highlighting table:

To match events fired at Error level, we may use the following expression:

{env/level} == 4

Alternatively, we can add a rule to highlight Fatal events in red. It will contain the following Filter Expression:

{env/level} == 5

If we just want to highlight all events whose level is greater than Error (I.e, greater than level 4), we might as well just enter "4" in the Level field of the custom highlighting table of the event. We could accomplish the same thing using an expression, {env/level} > 4.

Event Filtering Environment

When events are filtered, several environment variables are defined:

You can refer to these variables in filter expressions. The exact syntax of referring to them (as well as what are environment variables, and what are reference) is covered in the References article, within System Internals. Specifically, Environment Variables are described near the end of the article.

Parameterized Filters

Filter parameterization is useful when you want to let an operator configure a filter at runtime. The record in Filter Rules is marked as Parameterized, filter may require user to input one or more parameters during its activation (i.e. selection from a drop-down list in Event Log).

As covered above, the Filter Rules property contains many lines (records), each describing an event type which the filter passes. Each record may contain a filter expression (which may be parameterized). Even if the Filter Rules property contains more than one such parameterized Filter Expression, all filter parameters are entered in one single dialog. The Event Filter uses an Edit Data UI Procedure to prompt for filtering parameters.

When the Parameterized option is enabled in the Filter Rules record, the filter processing engine considers the Filter Expression as parameterization data. For more information, see Parameterization Engine.

Here is an example of filter parameterization data:

<form>

<format>

  <![CDATA[

        <<username><S><D=Username>>

  ]]>

</format>

<expression>

  {username} ~= '.*<e>{username}</e>.*'

</expression>

</form>

A filter containing this parameterized expression will ask for a Username parameter upon activation:

This filter will pass only events whose username field contains the value entered by an operator as the Username parameter, because resulting Filter Expression will be:

{username} ~= '.*<e>VALUE_OF_USERNAME_PARAMETER_ENTERED_BY_USER</e>.*'

Again, this isn't really supposed to make much sense at this point of the manual -- it's just a glimpse at the power of parameterized filters. To really understand how this works, you have to read about the Parameterization Engine.

Auto-Parameterization

This function automatically generates parameterization data for event categories selected from within Filter Rules. You can auto-parameterize a Filter Rules record only if it doesn't already contain a Filter Expression. The auto-parameterization process flow is described here.
Parameterization data generated by this function defines two parameters per every field in the event's Data Table. I.e, when applying auto-parameterization to an event which has only one field defined in its Event Format property, the user will be prompted to enter two values upon filter execution.

For example, if we apply auto-parameterization to the Administration Events category, parameterization data will define two parameters: Filter by 'Info (administration)' and Info (administration):

The first parameter enables filtering by the Info field of the Info event (in the administration context). The second parameter contains the expected value for the field. Only events with an Info field equal to this value will pass the filter.

Event Filter Configuration

Filter Properties

This defines the basic options of an event filter.

These may be accessed via the childInfo variable.

Filter RULES

This property defines a list event categories that will be shown when this filter is active.

Important: Once you edit this property, save and then reload your filter. Doing so will update the Additional Visible Fields property according to the event types you selected here, and this is important.

These may be accessed via the rules variable.

Primary Visible Fields

This property what columns to show in the event log when displaying a given event.

These may be accessed via the shownFields variable.

Additional Visible Fields

As covered above, events have additional fields. These are event-specific data, such as username (in the case of a login event). This property lets you configure which of these additional fields will be shown in the event log.

Once you've configured which event types your filter should pass (i.e, once you've customized the Filter Rules table to your liking), you must save the table. After saving and reloading filter configuration, the Additional Visible Fields list will be updated.

This list will now contain all additional fields, but only for those event types passed by the filter you're editing (and actually, even for disabled event categories). So you're going to have a whole slew of additional fields which you're going to have to choose from.

Let's say you have a filter passing both login events and alert events. The Additional Visible Fields list for this filter will let you enable (make visible) all fields for both event types. So you'll have name (for Alerts, to show the Alert name in the list) and also username (for Logins, to show who logged in). If you enable username, there will be an additional username column in the filter's table when you're viewing it in the Event Log. For lines showing login events, this column will contain the username. For lines showing alert events, this column will just be blank (no value at all, because it's inapplicable).

We advise you to select your fields wisely at this point - otherwise you'll end up with an extremely wide list for this filter in the Event Log, and scrolling it can be uncomfortable.

These may be accessed via the additionalFields variable.

Custom Highlighting

This table defines special highlighting rules.

These may be accessed via the customHighlighting variable.

Built-In Event Filters

LinkServer distribution contains two predefined Event Filters: