Silencing reference
Sensu’s silencing capability allows you to suppress event handler execution on an ad hoc basis so you can plan maintenance and reduce alert fatigue.
Silences are created on an ad hoc basis using sensuctl
.
Successfully created silencing entries are assigned a name
in the format $SUBSCRIPTION:$CHECK
, where $SUBSCRIPTION
is the name of a Sensu entity subscription and $CHECK
is the name of a Sensu check.
You can use silences to silence checks on specific entities by taking advantage of per-entity subscriptions (for example, entity:$ENTITY_NAME
).
When the check name or subscription described in a silencing entry matches an event and the handler uses the not_silenced
built-in filter, the handler will not be executed.
These silences are persisted in the Sensu datastore. When the Sensu server processes subsequent check results, it retrieves matching silences from the store. If there are one or more matching entries, the event is updated with a list of silenced entry names. The presence of silences indicates that the event is silenced.
When creating a silencing entry, you can specify a combination of checks and subscriptions, but only one or the other is strictly required.
For example, if you create a silencing entry specifying only a check, its name will contain an asterisk (or wildcard) in the $SUBSCRIPTION
position.
This indicates that any event with a matching check name will be marked as silenced, regardless of the originating entities’ subscriptions.
Conversely, a silencing entry that specifies only a subscription will have a name with an asterisk in the $CHECK
position.
This indicates that any event where the originating entities’ subscriptions match the subscription specified in the entry will be marked as silenced, regardless of the check name.
Silencing examples
This example shows a silencing resource definition that uses a per-entity subscription to silence any alerts on a single Sensu entity, i-424242
:
---
type: Silenced
api_version: core/v2
metadata:
annotations: null
labels: null
name: entity:i-424242:*
namespace: default
spec:
begin: 1542671205
check: null
creator: admin
expire: -1
expire_on_resolve: false
reason: null
subscription: entity:i-424242
{
"type": "Silenced",
"api_version": "core/v2",
"metadata": {
"name": "entity:i-424242:*",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"expire": -1,
"expire_on_resolve": false,
"creator": "admin",
"reason": null,
"check": null,
"subscription": "entity:i-424242",
"begin": 1542671205
}
}
The following example shows how to silence a check named check_ntp
on entity i-424242
, ensuring the silencing entry is deleted after the underlying issue is resolved:
---
type: Silenced
api_version: core/v2
metadata:
name: entity:i-424242:check_ntp
namespace: default
labels:
annotations:
spec:
subscription: entity:i-424242
check: check_ntp
expire_on_resolve: true
{
"type": "Silenced",
"api_version": "core/v2",
"metadata": {
"name": "entity:i-424242:check_ntp",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"subscription": "entity:i-424242",
"check": "check_ntp",
"expire_on_resolve": true
}
}
The optional expire_on_resolve
attribute used in this example indicates that when the server processes a matching check from the specified entity with status OK, the silencing entry will be removed automatically.
When used in combination with other attributes (like creator
and reason
), this gives Sensu operators a way to acknowledge that they received an alert, suppress additional notifications, and automatically clear the silencing entry when the check status returns to normal.
Silencing specification
Silenced entry names
Silences must contain either a subscription or check name and are identified by the combination of $SUBSCRIPTION:$CHECK
.
If a check or subscription is not provided, it will be substituted with a wildcard (asterisk): $SUBSCRIPTION:*
or *:$CHECK
.
Top-level attributes
type | |
---|---|
description | Top-level attribute that specifies the sensuctl create resource type. Silences should always be type Silenced . |
required | Required for silencing 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 silences in this version of Sensu, the api_version should always be core/v2 . |
required | Required for silencing entry definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of metadata about the silencing entry that includes name , namespace , and created_by as well as custom labels and annotations . The metadata map is always at the top level of the silencing entry 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 silencing entry definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the silencing entry spec attributes. |
required | Required for silences in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
Metadata attributes
name | |
---|---|
description | Silencing identifier generated from the combination of a subscription name and check name. |
required | false - This value cannot be modified. |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that the silencing entry belongs to. |
required | false |
type | String |
default | default |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created the silence or last updated the silence. Sensu automatically populates the created_by field when the silence is created or updated. |
required | false |
type | String |
example |
|
labels | |
---|---|
description | Custom attributes to include with observation data in events that you can use for response and web UI view filtering. If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data. Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels. |
required | false |
type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. |
default | null |
example |
|
annotations | |
---|---|
description | Non-identifying metadata to include with observation data in events that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu. In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views. |
required | false |
type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default | null |
example |
|
Spec attributes
check | |
---|---|
description | Name of the check the entry should match. |
required | true, unless subscription is provided |
type | String |
example |
|
subscription | |
---|---|
description | Name of the subscription the entry should match. |
required | true, unless check is provided |
type | String |
example |
|
begin | |
---|---|
description | Time at which silence entry goes into effect. In epoch. |
required | false |
type | Integer |
example |
|
expire | |
---|---|
description | Number of seconds until the entry should be deleted. |
required | false |
type | Integer |
default | -1 |
example |
|
expire_on_resolve | |
---|---|
description | true if the entry should be deleted when a check begins to return OK status (resolves). Otherwise, false . |
required | false |
type | Boolean |
default | false |
example |
|
creator | |
---|---|
description | Person, application, or entity responsible for creating the entry. |
required | false |
type | String |
default | null |
example |
|
reason | |
---|---|
description | Explanation of the reason for creating the entry. |
required | false |
type | String |
default | null |
example |
|
Silence all checks on entities with a specific subscription
In this example, you’ll completely silence any entities subscribed to appserver
.
Just as in the example of silencing all checks on a specific entity, you’ll create a silencing entry that specifies only the appserver
subscription:
---
type: Silenced
api_version: core/v2
metadata:
name: appserver
namespace: default
labels:
annotations:
spec:
subscription: appserver
{
"type": "Silenced",
"api_version": "core/v2",
"metadata": {
"name": "appserver",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"subscription": "appserver"
}
}
Silence a specific check on entities with a specific subscription
To silence a check mysql_status
that is running on Sensu entities with the subscription appserver
:
---
type: Silenced
api_version: core/v2
metadata:
name: appserver:mysql_status
namespace: default
labels:
annotations:
spec:
subscription: appserver
check: mysql_status
{
"type": "Silenced",
"api_version": "core/v2",
"metadata": {
"name": "appserver:mysql_status",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"subscription": "appserver",
"check": "mysql_status"
}
}
Silence a specific check on every entity
To silence the check mysql_status
on every entity in your infrastructure, regardless of subscriptions, you only need to provide the check name:
---
type: Silenced
api_version: core/v2
metadata:
name: mysql_status
namespace: default
labels:
annotations:
spec:
check: mysql_status
{
"type": "Silenced",
"api_version": "core/v2",
"metadata": {
"name": "mysql_status",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"check": "mysql_status"
}
}
Delete a silence
To delete a silencing entry, you must provide its name.
Subscription-only silencing entry names will contain an asterisk (or wildcard) in the $SUBSCRIPTION
position, similar to this example:
name: appserver:*
{
"name": "appserver:*"
}
Check-only silencing entry names will contain an asterisk (or wildcard) in the $CHECK
position, similar to this example:
name: '*:mysql_status'
{
"name": "*:mysql_status"
}