Filter Expressions

Filter expressions help fine-tune a given filter by showing only events that match a specific formula defined by an Iotellect 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 Iotellect Server contexts.

You are now entering an "advanced" section of this article. Before you can actually understand filter expressions, you'll need to have a profound understanding of references and expressions. These have their own chapters, under System Internals. We advise you to skip there now, read those chapters until you really understand references and expressions, and then come back here for an in-depth review of filter expressions.

• You can include references to the "default data table" within the Filter Expression. These are references such as firstname - no need to state an explicit context path and a variable name (such as users.admin:childInfo$firstname). Iotellect Server treats the Data Table of the event currently being filtered as the Default Data Table, and these references point there.

• You can also refer to environment variables, such as env/level (an event's severity level, which is not included in the event's Data Table but is just a property of an event,. More about event properties can be found in the Events article in the System Internals section). A full list of environment variables defined when an event is being filtered is here.

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.

If the Parameterized flag is enabled in the Filter Rule, the Parameterizer Source Data field is used to build a Filter Expression in real-time upon filter activation. For further details, see Parameterized Filters.

If a filter expression is not specified in Filter Rules record, all events that satisfy Context Mask, Event Name and Level options defined by this record will be shown.

Example:

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

If we open the Data field for any login event shown in the Event Log, we will see its data in a Data Table Editor component as shown below:

We see that data for the Login event has a number of fields, among them: 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 a 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.

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.

If a filter expression is not specified in Custom Highlighting record, all events that satisfy Context Mask, Event Name and Level options defined by this record will be highlighted.

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.

As a baseline, you can find the formalized filter expression resolution environment below.

Was this page helpful?

Tell us more

Send

Thank you!