Searches

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

With the saved searches feature, you can apply search parameters to your entities, events, and resources and save them to etcd in a namespaced resource named searches.

The saved searches feature is designed to be used directly in the web UI. However, you can create, retrieve, update, and delete saved searches with the searches API.

Searches specification

Top-level attributes

type
description Top-level attribute that specifies the sensuctl create resource type. Searches should always be type Search.
required Required for search entry definitions in wrapped-json or yaml format for use with sensuctl create.
type String
example
"type": "Search"
api_version
description Top-level attribute that specifies the Sensu API group and version. For searches in this version of Sensu, the api_version should always be searches/v1.
required Required for search entry definitions in wrapped-json or yaml format for use with sensuctl create.
type String
example
"api_version": "searches/v1"
metadata
description Top-level collection of metadata about the search that includes name and namespace. The metadata map is always at the top level of the search definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. See metadata attributes for details.
required Required for search entry definitions in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example
"metadata": {
  "name": "us-west-server-incidents",
  "namespace": "default"
}
spec
description Top-level map that includes the search spec attributes. The spec contents will depend on the search parameters you apply and save.
required Required for silences in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example
"spec": {
  "parameters": [
    "entity:server-testing",
    "check:server-health",
    "status:incident",
    "labelSelector:region == \"us-west-1\""
  ],
  "resource": "core.v2/Event"
}

Metadata attributes

name
description Search identifier generated from the combination of a subscription name and check name.
required true
type String
example
"name": "us-west-server-incidents"
namespace
description Sensu RBAC namespace that the search belongs to.
required false
type String
default default
example
"namespace": "default"

Spec attributes

parameters
description Parameters the search will apply.
required true
type Array
example
"parameters": [
  "entity:server-testing",
  "check:server-health",
  "status:incident",
  "labelSelector:region == \"us-west-1\""
]
resource
description Fully qualified name of the resource included in the search.
required true
type String
example
"resource": "core.v2/Event"

Parameters

action
description For filter searches, the type of filter to include in the search: allow or deny.
required false
type String
example
"action:allow"
check
description Name of the check to include in the search.
required false
type String
example
"check:server-health"
class
description For entity searches, the entity class to include in the search: agent or proxy.
required false
type String
example
"class:agent"
entity
description Name of the entity to include in the search.
required false
type String
example
"entity:server-testing"
event
description Name of the event to include in the search.
required false
type String
example
"event:server-testing"
fieldSelector
description Field selector to include in the search.
required false
type Filter statement
example
"fieldSelector: entity.name == \"1b04994n\""
labelSelector
description Label selector to include in the search.
required false
type Filter statement
example
"labelSelector:region == \"us-west-1\""
published
description If true, the search will include only published resources. Otherwise, false.
required false
type Boolean
example
"published:true"
silenced
description If true, the search will include only silenced events. Otherwise, false.
required false
type Boolean
example
"silenced:true"
status
description Status of the events, entities, or resources to include in the search.
required false
type String
example
"status:incident"
subscription
description Name of the subscription to include in the search.
required false
type String
example
"subscription:web"
type
description For handler searches, the type of hander to include in the search: pipe, set, tcp, or udp.
required false
type String
example
"type:pipe"

Examples

Search for events with any status except passing

The following saved search will retrieve all events that have any status except passing:

type: Search
api_version: searches/v1
metadata:
  name: events-not-passing
  namespace: default
spec:
  parameters:
  - status:incident
  - status:warning
  - status:critical
  - status:unknown
  resource: core.v2/Event
{
  "type": "Search",
  "api_version": "searches/v1",
  "metadata": {
    "name": "events-not-passing",
    "namespace": "default"
  },
  "spec": {
    "parameters": [
      "status:incident",
      "status:warning",
      "status:critical",
      "status:unknown"
    ],
    "resource": "core.v2/Event"
  }
}

Search for published checks with a specific subscription and region

The following saved search will retrieve all published checks for the us-west-1 region with the linux subscription:

type: Search
api_version: searches/v1
metadata:
  name: published-checks-linux-uswest
  namespace: default
spec:
  parameters:
  - published:true
  - subscription:linux
  - 'labelSelector: region == "us-west-1"'
  resource: core.v2/CheckConfig
{
  "type": "Search",
  "api_version": "searches/v1",
  "metadata": {
    "name": "published-checks-linux-uswest",
    "namespace": "default"
  },
  "spec": {
    "parameters": [
      "published:true",
      "subscription:linux",
      "labelSelector: region == \"us-west-1\""
    ],
    "resource": "core.v2/CheckConfig"
  }
}