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 for weekday, hour, minute, and second
Together, the weekday
, hour
, minute
, and second
custom functions provide granular control of time-based filter expressions, comparable to cron scheduling.
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
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
minute
The custom function minute
returns the minute of the hour (0 through 59) 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 false
:
minute(event.timestamp) <= 30
second
The custom function second
returns the second of the minute (0 through 59) 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
:
second(event.timestamp) >= 30
seconds_since custom function
The custom function seconds_since
returns the number of seconds (using float64) between the current time and an event’s timestamp.
For systems with event processing pressure, you can use seconds_since
to create alerts for events that are not handled within a certain period.
For example, the following SQE represents a 30-second time budget for event processing:
seconds_since(event.timestamp) > 30
sensu.CheckDependencies custom function
Use the sensu.CheckDependencies
SQE to filter events based on the results of a different check.
The sensu.CheckDependencies
SQE takes zero or more checks as arguments against the event being filtered.
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
.
If no event matches the specified checks, Sensu will raise an error.
You can refer to checks as strings, objects, arrays of strings, and arrays of objects in the sensu.CheckDependencies
SQE.
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 pass entity names and check names in objects to reference checks on specific entities.
String example
In this example, if all checks named database
or disk
are passing, the SQE returns true
:
sensu.CheckDependencies("database", "disk")
Object example
You can 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"})
String and object example
This example mixes string and object references in the same expression.
It passes a check name (disk
) as well as an object that includes entity and check names:
sensu.CheckDependencies("disk", {entity: "server01", check: "database"})
Array examples
You can use sensu.CheckDependencies
to evaluate a check that contains an array of elements, which is useful for evaluating arrays parsed from event annotations.
This example references an array of three check names:
sensu.CheckDependencies(["port1", "port2", "port3"])
This example references an array of objects that each include both an entity and a check name:
sensu.CheckDependencies([{entity: "router", check: "port1"}, {entity: "router", check: "port2"}])
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']