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 AggreGate Server 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.

Resolution Environment

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