Searches reference

COMMERCIAL FEATURE: Access the web UI in the packaged Sensu Go distribution. For more information, read Get started with commercial features.

With the saved searches feature in the web UI, 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 enterprise/searches/v1 API endpoints.

Search for events with any status except passing

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

YMLJSON
---
type: Search
api_version: searches/v1
metadata:
  name: events-not-passing
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"
  },
  "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:

YMLJSON
---
type: Search
api_version: searches/v1
metadata:
  name: published-checks-linux-uswest
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"
  },
  "spec": {
    "parameters": [
      "published:true",
      "subscription:linux",
      "labelSelector: region == \"us-west-1\""
    ],
    "resource": "core.v2/CheckConfig"
  }
}

Search specification

Top-level attributes

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
YMLJSON
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. Read 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
YMLJSON
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
YMLJSON
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"
  }
}
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
YMLJSON
type: Search
{
  "type": "Search"
}

Metadata attributes

name
description Search identifier generated from the combination of a subscription name and check name.
required true
type String
example
YMLJSON
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
YMLJSON
namespace: default
{
  "namespace": "default"
}

Spec attributes

parameters
description Parameters the search will apply.
required true
type Array
example
YMLJSON
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
YMLJSON
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
YMLJSON
parameters:
- action:allow
{
  "parameters": [
    "action:allow"
  ]
}
check
description Name of the check to include in the search.
required false
type String
example
YMLJSON
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
YMLJSON
parameters:
- class:agent
{
  "parameters": [
    "class:agent"
  ]
}
entity
description Name of the entity to include in the search.
required false
type String
example
YMLJSON
parameters:
- entity:server-testing
{
  "parameters": [
    "entity:server-testing"
  ]
}
event
description Name of the event to include in the search.
required false
type String
example
YMLJSON
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
YMLJSON
parameters:
- published:true
{
  "parameters": [
    "published:true"
  ]
}
silenced
description If true, the search will include only silenced events. Otherwise, false.
required false
type Boolean
example
YMLJSON
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
YMLJSON
parameters:
- status:incident
{
  "parameters": [
    "status:incident"
  ]
}
subscription
description Name of the subscription to include in the search.
required false
type String
example
YMLJSON
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
YMLJSON
parameters:
- type:pipe
{
  "parameters": [
    "type:pipe"
  ]
}