Filters

How do Sensu filters work?

Sensu filters are applied when event handlers are configured to use one or more filters. Prior to executing a handler, the Sensu server will apply any filters configured for the handler to the event data. If the event is not removed by the filter(s), the handler will be executed. The filter analysis flow performs these steps:

  • When the Sensu server is processing an event, it will check for the definition of a handler (or handlers). Prior to executing each handler, the Sensu server will first apply any configured filters for the handler.
  • If multiple filters are configured for a handler, they are executed sequentially.
  • Filter statements are compared with event data.
  • Filters can be inclusive (only matching events are handled) or exclusive (matching events are not handled).
  • As soon as a filter removes an event, no further analysis is performed and the event handler will not be executed.

NOTE: Filters specified in a handler set definition have no effect. Filters must be specified in individual handler definitions.

Inclusive and exclusive filtering

Filters can be inclusive "action": "allow" (replaces "negate": false in Sensu 1) or exclusive "action": "deny" (replaces "negate": true in Sensu 1). Configuring a handler to use multiple inclusive filters is the equivalent of using an AND query operator (only handle events if they match inclusive filter x AND y AND z). Configuring a handler to use multiple exclusive filters is the equivalent of using an OR operator (only handle events if they don’t match x OR y OR z).

  • Inclusive filtering: by setting the filter definition attribute "action": "allow", only events that match the defined filter statements are handled.
  • Exclusive filtering: by setting the filter definition attribute "action": "deny", events are only handled if they do not match the defined filter statements.

Filter statement comparison

Filter statements are compared directly with their event data counterparts. For inclusive filter definitions (like "action": "allow"), matching statements will result in the filter returning a true value; for exclusive filter definitions (like "action": "deny"), matching statements will result in the filter returning a false value, and the event will not pass through the filter. Filters that return a true value will continue to be processed via additional filters (if defined), mutators (if defined), and handlers.

Filter statement evaluation

When more complex conditional logic is needed than direct filter statement comparison, Sensu filters provide support for statements evaluation using govaluate expressions. If the evaluated expression returns true, the statement is a match.

Filter specification

Filter naming

Each filter definition must have a unique name within its organization and environment.

  • A unique string used to name/identify the filter
  • Cannot contain special characters or spaces
  • Validated with Go regex \A[\w\.\-]+\z

Filter attributes

action
description Action to take with the event if the filter statements match. NOTE: see Inclusive and exclusive filtering for more information.
required true
type String
allowed values allow, deny
example
"action": "allow"
statements
description Filter statements to be compared with event data.
required true
type Array
example
"statements": [
  "event.Check.Team == 'ops'"
]
when
description The when definition scope, used to determine when a filter is applied with time windows. See the sensuctl documentation for the supported time formats.
required false
type Hash
example
"when": {
  "days": {
    "all": [
      {
        "begin": "17:00 UTC",
        "end": "08:00 UTC"
      }
    ]
  }
}
organization
description The Sensu RBAC organization that this filter belongs to.
required false
type String
default current organization value configured for sensuctl (for example: default)
example
"organization": "default"
environment
description The Sensu RBAC environment that this filter belongs to.
required false
type String
default current environment value configured for sensuctl (for example: default)
example
"environment": "default"

when attributes

days
description A hash of days of the week (ex: monday) and/or all. Each day specified can define one or more time windows, in which the filter is applied. See the sensuctl documentation for the supported time formats.
required false (unless when is configured)
type Hash
example
"days": {
  "all": [
    {
      "begin": "17:00 UTC",
      "end": "08:00 UTC"
    }
  ],
  "friday": [
    {
      "begin": "12:00 UTC",
      "end": "17:00 UTC"
    }
  ]
}

Filter Examples

Handling production events

The following example filter definition, entitled production_filter, will match event data with a custom entity definition attribute "environment": "production".

{
  "name": "production_filter",
  "action": "allow",
  "statements": [
    "event.Entity.Environment == 'production'"
  ]
}

Handling non-production events

The following example filter definition, entitled development_filter, will discard event data with a custom entity definition attribute "environment": "production".

Note that action is deny, making this an exclusive filter; if evaluation returns false, the event will be handled.

{
  "name": "development_filter",
  "action": "deny",
  "statements": [
    "event.Entity.Environment == 'production'"
  ]
}

Handling state change only

Some teams migrating to Sensu have asked about reproducing the behavior of their old monitoring system which alerts only on state change. This state_change_only inclusive filter provides such.

{
  "name": "state_change_only",
  "action": "allow",
  "statements": [
    "event.Check.Occurrences == 1"
  ]
}

Handling repeated events

The following example filter definition, entitled filter_interval_60_hourly, will match event data with a check interval of 60 seconds, and an occurrences value of 1 (the first occurrence) -OR- any occurrences value that is evenly divisible by 60 via a modulo operator calculation (calculating the remainder after dividing occurrences by 60).

{
  "name": "filter_interval_60_hourly",
  "action": "allow",
  "statements": [
    "event.Check.Interval == 60",
    "event.Check.Occurrences == 1 || event.Check.Occurrences % 60 == 0"
  ]
}

The next example will apply the same logic as the previous example, but for checks with a 30 second interval.

{
  "name": "filter_interval_30_hourly",
  "action": "allow",
  "statements": [
    "event.Check.Interval == 30",
    "event.Check.Occurrences == 1 || event.Check.Occurrences % 120 == 0"
  ]
}

Handling events during “office hours” only

This filter evaluates the event timestamp to determine if the event occurred between 9 AM and 5 PM UTC on a weekday. Remember that action is equal to allow, so this is an inclusive filter. If evaluation returns false, the event will not be handled. The when attribute could also be used to achieve the same result.

{
  "name": "nine_to_fiver",
  "action": "allow",
  "statements": [
    "weekday(event.Timestamp) >= 1 && weekday(event.Timestamp) <= 5",
    "hour(event.Timestamp) >= 9 && hour(event.Timestamp) <= 17"
  ]
}

NOTE: Sensu handles dates and times in UTC (Coordinated Universal Time), therefore when comparing the weekday or the hour, you should provide values in UTC.