Searches reference

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.

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"
  }
}

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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "name": "us-west-server-incidents"
}
namespace
description Sensu RBAC namespace that the search belongs to.
required false
type String
default default
example 
namespace: default
{
  "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"
{
  "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
{
  "resource": "core.v2/Event"
}

Parameters

action
description For event filter searches, the type of filter to include in the search: allow or deny.
required false
type String
example 
parameters:
- action:allow
{
  "parameters": [
    "action:allow"
  ]
}
check
description Name of the check to include in the search.
required false
type String
example 
parameters:
- check:server-health
{
  "parameters": [
    "check:server-health"
  ]
}
class
description For entity searches, the entity class to include in the search: agent or proxy.
required false
type String
example 
parameters:
- class:agent
{
  "parameters": [
    "class:agent"
  ]
}
entity
description Name of the entity to include in the search.
required false
type String
example 
parameters:
- entity:server-testing
{
  "parameters": [
    "entity:server-testing"
  ]
}
event
description Name of the event to include in the search.
required false
type String
example 
parameters:
- event:server-testing
{
  "parameters": [
    "event:server-testing"
  ]
}
published
description If true, the search will include only published resources. Otherwise, false.
required false
type Boolean
example 
parameters:
- published:true
{
  "parameters": [
    "published:true"
  ]
}
silenced
description If true, the search will include only silenced events. Otherwise, false.
required false
type Boolean
example 
parameters:
- silenced:true
{
  "parameters": [
    "silenced:true"
  ]
}
status
description Status of the events, entities, or resources to include in the search.
required false
type String
example 
parameters:
- status:incident
{
  "parameters": [
    "status:incident"
  ]
}
subscription
description Name of the subscription to include in the search.
required false
type String
example 
parameters:
- subscription:web
{
  "parameters": [
    "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 
parameters:
- type:pipe
{
  "parameters": [
    "type:pipe"
  ]
}