Sensu query expressions reference

Sensu query expressions (SQEs) are JavaScript-based expressions that provide additional functionality for using Sensu, like nested parameters and custom functions.

SQEs are defined in event filters, so they act in the context of determining whether a given event should be passed to the handler. SQEs always receive a single event and some information about that event, like event.timestamp or event.check.interval.

SQEs always return either true or false. They are evaluated by the Otto JavaScript VM as JavaScript programs.

Syntax quick reference

operator description
=== Identity
!== Nonidentity
== Equality
!= Inequality
&& Logical AND
|| Logical OR
< Less than
> Greater than
<= Less than or equal to
>= Greater than or equal to

Specification

SQEs are valid ECMAScript 5 (JavaScript) expressions that return either true or false. Other values are not allowed. If an SQE returns a value besides true or false, an error is recorded in the Sensu backend log and the filter evaluates to false.

Custom functions

hour

The custom function hour returns the hour of a UNIX epoch time (in UTC and 24-hour time notation).

For example, if an event.timestamp equals 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC, the following SQE returns true:

hour(event.timestamp) >= 17

weekday

The custom function weekday returns a number that represents the day of the week of a UNIX epoch time. Sunday is 0.

For example, if an event.timestamp equals 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC, the following SQE returns false:

weekday(event.timestamp) == 0

sensu.CheckDependencies

The sensu.CheckDependencies SQE takes zero or more checks as arguments. It returns true if all the specified checks are passing or false if any of the specified checks are failing.

If you do not specify any checks, the sensu.CheckDependencies SQE always returns true.

You can refer to the checks as strings. In this example, if all checks named database or disk are passing, the following SQE returns true:

sensu.CheckDependencies("database", "disk")

If you pass the check names as strings, Sensu assumes that the entities are the same as those in the events being filtered.

You can also refer to the checks in objects that include both the entity and check name. For example:

sensu.CheckDependencies({entity: "server01", check: "disk"}, {entity: "server01", check: "database"})

In both cases, if no event matches the specified entities and checks, Sensu will raise an error.

Examples

Evaluate an event attribute

This SQE returns true if the event’s entity contains a custom attribute named namespace that is equal to production:

event.entity.namespace == 'production'

Evaluate an array

To evaluate an attribute that contains an array of elements, use the .indexOf method. For example, this expression returns true if an entity includes the subscription system:

entity.subscriptions.indexOf('system') >= 0

Evaluate the day of the week

This expression returns true if the event occurred on a weekday:

weekday(event.timestamp) >= 1 && weekday(event.timestamp) <= 5

Evaluate office hours

This expression returns true if the event occurred between 9 AM and 5 PM UTC:

hour(event.timestamp) >= 9 && hour(event.timestamp) <= 17

Evaluate labels and annotations

Although you can use annotations to create SQEs, we recommend using labels because labels provide identifying information.

This expression returns true if the event’s entity includes the label webserver:

!!event.entity.labels.webserver

Likewise, this expression returns true if the event’s entity includes the annotation www.company.com:

!!event.entity.annotations['www.company.com']