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.
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 |
|
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
{
"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"
}
}
|
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"
]
}
|
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"
}
}