Sensu query expressions

How do Sensu query expressions work?

Sensu query expressions (SQE) are based on JavaScript expressions, and provide additional functionalities for Sensu usage (like nested parameters and custom functions) so Sensu resources can be directly evaluated. SQE should always return true or false.

New and improved expressions

Sensu 1 uses Ruby expressions, which are not available in Sensu Go, being written in Go. The existence of a Go library that provides a JavaScript VM has allowed us to embed a Javascript execution engine for filters instead. Sadly, there is no equivalent Ruby VM library.

Sensu query expressions specification

Sensu query expressions are valid ECMAScript 5 (JavaScript) expressions that return true or false. Other values are not allowed. If other values are returned, an error is logged and the filter evaluates to false.

Custom functions

  • hour: returns the hour, in UTC and in the 24-hour time notation, of a UNIX Epoch time.
// event.timestamp equals to 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC
// The following expression returns true
hour(event.timestamp) >= 17
  • weekday: returns a number representing the day of the week, where Sunday equals 0, of a UNIX Epoch time.
// event.timestamp equals to 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC
// The following expression returns false
weekday(event.timestamp) == 0

Sensu query expressions examples

Simple evaluation of an event attribute

The following example returns true if the event’s entity contains a custom attribute named Namespace that is equal to production.

event.Entity.Namespace == 'production'

Evaluating the day of the week

The following example returns true if the event occurred on a weekday.

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

Evaluating office hours

The following example returns true if the event occurred between 9 AM and 5 PM UTC.

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