Searches reference
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
:
---
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:
---
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 |
{
"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 |
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"
}
}
|
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 |
|
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"
}
|
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"
}
|
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"
]
}
|