Filter responses with sensuctl

COMMERCIAL FEATURE: Access sensuctl response filtering in the packaged Sensu Go distribution. For more information, see Get started with commercial features.

Sensuctl supports response filtering for all commands using the list verb. For information about response filtering methods and available label and field selectors, see API response filtering.

Sensuctl-specific syntax

You can use the same methods, selectors, and examples for sensuctl response filtering as for API response filtering, except you’ll format your requests with the --label-selector and --field-selector flags instead of cURL.

The standard sensuctl response filtering syntax is:

sensuctl RESOURCE_TYPE list --SELECTOR 'FILTER_STATEMENT'

To create a sensuctl response filtering command:

  • Replace RESOURCE_TYPE with the resource your filter is based on.
  • Replace SELECTOR with either label-selector or field-selector, depending on which selector you want to use.
  • Replace FILTER_STATEMENT with the filter to apply.

For example:

sensuctl event list --field-selector 'linux notin event.entity.subscriptions'

Sensuctl response filtering commands will also work with a single equals sign between the selector flag and the filter statement:

sensuctl event list --field-selector='linux notin event.entity.subscriptions'

The examples demonstrate how to construct sensuctl filter statements for different selectors and operators.

Operators quick reference

Sensuctl response filtering supports two equality-based operators, two set-based operators, one substring matching operator, and one logical operator.

operator description example
== Equality check.publish == true
!= Inequality check.namespace != "default"
in Included in linux in check.subscriptions
notin Not included in slack notin check.handlers
matches Substring matching check.name matches "linux-"
&& Logical AND check.publish == true && slack in check.handlers

For details about operators, see API response filtering operators.

Examples

Filter responses with label selectors

Use the --label-selector flag to filter responses using custom labels.

For example, to return entities with the proxy_type label set to switch:

sensuctl entity list --label-selector 'proxy_type == switch'

Filter responses with field selectors

Use the --field-selector flag to filter responses using specific resource attributes.

For example, to return entities with the switches subscription:

sensuctl entity list --field-selector 'switches in entity.subscriptions'

To retrieve all events that equal a status of 2 (CRITICAL):

sensuctl event list --field-selector 'event.check.status == "2"'

To retrieve all entities whose name includes the substring webserver:

sensuctl entity list --fieldSelector 'entity.name matches "webserver"'

Use the logical AND operator

To use the logical AND operator (&&) to return checks that include a linux subscription in the dev namespace:

sensuctl check list --field-selector 'linux in check.subscriptions && dev in check.namespace'

Combine label and field selectors

You can combine the --label-selector and --field-selector flags in a single command.

For example, this command returns checks with the region label set to us-west-1 that also use the slack handler:

sensuctl check list --label-selector 'region == "us-west-1"' --field-selector 'slack in check.handlers'