Hooks
How do hooks work?
Hooks are executed in response to the result of a check command execution
and based on the exit status code of that command (ex: 1
).
Hook commands can optionally receive JSON serialized Sensu client data via
STDIN.
You can create, manage, and reuse hooks independently of checks.
Check response types
Each type of response (ex: non-zero
) can contain one or more hooks, and
correspond to one or more exit status code. Hooks are executed, in order of
precedence, based on their type:
1
to 255
ok
warning
critical
unknown
non-zero
You can assign one or more hooks to a check in the check definition.
See the check specification to configure the check_hooks
attribute.
Check hooks
The hook command output, status, executed timestamp and duration are captured
and published in the resulting event.
You can use sensuctl
to view this data:
sensuctl event info entity_name check_name --format yaml
type: Event
api_version: core/v2
metadata:
namespace: default
spec:
check:
...
hooks:
- command: df -hT / | grep '/'
duration: 0.002904412
executed: 1559948435
issued: 0
metadata:
name: root_disk
namespace: default
output: "/dev/mapper/centos-root xfs 41G 1.6G 40G 4% /\n"
status: 0
stdin: false
timeout: 60
Hooks specification
Top-level attributes
type |
|
description |
Top-level attribute specifying the sensuctl create resource type. Hooks should always be of type HookConfig . |
required |
Required for hook definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
String |
example |
|
api_version |
|
description |
Top-level attribute specifying the Sensu API group and version. For hooks in Sensu backend version 5.2, this attribute should always be core/v2 . |
required |
Required for hook definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
String |
example |
|
metadata |
|
description |
Top-level collection of metadata about the hook, including the name and namespace as well as custom labels and annotations . The metadata map is always at the top level of the hook definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. See the metadata attributes reference for details. |
required |
Required for hook definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
Map of key-value pairs |
example |
"metadata": {
"name": "process_tree",
"namespace": "default",
"labels": {
"region": "us-west-1"
},
"annotations": {
"slack-channel" : "#monitoring"
}
}
|
spec |
|
description |
Top-level map that includes the hook spec attributes. |
required |
Required for hook definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
Map of key-value pairs |
example |
"spec": {
"command": "ps aux",
"timeout": 60,
"stdin": false
}
|
Spec attributes
command |
|
description |
The hook command to be executed. |
required |
true |
type |
String |
example |
"command": "sudo /etc/init.d/nginx start"
|
timeout |
|
description |
The hook execution duration timeout in seconds (hard stop). |
required |
false |
type |
Integer |
default |
60 |
example |
|
stdin |
|
description |
If the Sensu agent writes JSON serialized Sensu entity and check data to the command process’ STDIN. The command must expect the JSON data via STDIN, read it, and close STDIN. This attribute cannot be used with existing Sensu check plugins, nor Nagios plugins etc, as Sensu agent will wait indefinitely for the hook process to read and close STDIN. |
required |
false |
type |
Boolean |
default |
false |
example |
|
name |
|
description |
A unique string used to identify the hook. Hook names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z ). Each hook must have a unique name within its namespace. |
required |
true |
type |
String |
example |
|
namespace |
|
description |
The Sensu RBAC namespace that this hook belongs to. |
required |
false |
type |
String |
default |
default |
example |
"namespace": "production"
|
labels |
|
description |
Custom attributes to include with event data, which can be queried like regular attributes. You can use labels to organize hooks into meaningful collections that can be selected using filters and tokens. |
required |
false |
type |
Map of key-value pairs. Keys can contain only letters, numbers, and underscores, but must start with a letter. Values can be any valid UTF-8 string. |
default |
null |
example |
"labels": {
"environment": "development",
"region": "us-west-2"
}
|
annotations |
|
description |
Arbitrary, non-identifying metadata to include with event data. In contrast to labels, annotations are not used internally by Sensu and cannot be used to identify hooks. You can use annotations to add data that helps people or external tools interacting with Sensu. |
required |
false |
type |
Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default |
null |
example |
"annotations": {
"managed-by": "ops",
"slack-channel": "#monitoring",
"playbook": "www.example.url"
}
|
Examples
Hooks can be used for rudimentary auto-remediation tasks, for example, starting
a process that is no longer running.
NOTE: Using hooks for auto-remediation should be approached
carefully, as they run without regard to the number of event
occurrences.
type: HookConfig
api_version: core/v2
metadata:
annotations: null
labels: null
name: restart_nginx
namespace: default
spec:
command: sudo systemctl start nginx
stdin: false
timeout: 60
{
"type": "HookConfig",
"api_version": "core/v2",
"metadata": {
"name": "restart_nginx",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"command": "sudo systemctl start nginx",
"timeout": 60,
"stdin": false
}
}
Capture the process tree
Hooks can also be used for automated data gathering for incident triage, for
example, a check hook could be used to capture the process tree when a process
has been determined to be not running etc.
type: HookConfig
api_version: core/v2
metadata:
annotations: null
labels: null
name: process_tree
namespace: default
spec:
command: ps aux
stdin: false
timeout: 60
{
"type": "HookConfig",
"api_version": "core/v2",
"metadata": {
"name": "process_tree",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"command": "ps aux",
"timeout": 60,
"stdin": false
}
}