Stashes

Reference documentation

What is a Sensu stash?

A Sensu stash is a JSON document containing arbitrary JSON Hash data which is accessible via the Stashes API. The most common use of the Sensu Stashes are via Sensu handlers, which may access the Stashes API to create and/or read “state” information that persists between handler executions.

NOTE: Prior to Sensu 0.26, the ability to silence notifications was implemented in external libraries like sensu-plugin using specially crafted stashes. Silencing via stashes is deprecated in favor of new native silencing. Please see the silencing reference documentation for more details.

The Sensu key/value store

The Stashes API provides a key/value store for Sensu, where arbitrary JSON data (i.e. the “values”) can be created, accessed, and deleted via an arbitrary path (i.e. the “keys”).

The Sensu stash specification

Example Sensu stash

The following is an example Sensu stash.

{
  "path": "path/to/my/stash",
  "content": {
    "message": "hello world!",
    "foo": "bar"
  },
  "expire": -1
}

Stash definition specification

Stash attributes

path
description The path (or “key”) the stash will be created and/or accessible at.
type String
required true
example
"path": "silence/server-01"
content
description Arbitrary JSON data.
type Hash
required false
example
"content": {
  "message": "hello world!"
}
expire
description How long should the stash exist before it is removed by the API, in seconds
type Integer
required false
default -1
example
"expire": 3600

content attributes

By default (i.e. if no content is provided), Sensu stash content is an empty JSON Hash (i.e. {}). Because stashes are just JSON documents, it is possible to define arbitrary JSON data inside the content Hash in a similar fashion as custom attributes may be defined for other Sensu primitives (e.g. clients, checks, etc).

NOTE: no built-in Sensu features define a specification for stash content, so there are no “supported” stash formats — all Sensu stashes are treated as custom data.

Direct access to stash content data

It is important to note that the Stashes API provides multiple endpoints for access Sensu stash data (e.g. /stashes and /stashes/:path). While the /stashes API endpoints provide access to complete stash definitions, the /stashes/:path endpoints provide direct access to stash content data.

Please note the following example exercise to demonstrate the effect of direct access to stash content data:

  1. Let’s assume we’re starting out with an empty key/value store.

    $ curl -s http://localhost:4567/stashes | jq .
    []

  2. Now let’s create a stash with a path called ‘direct-access/example-1’ via the /stashes (POST) API:

    $ curl -s -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"path": "direct-access/example-1", "content":{"message":"hello world"}}' \
    http://localhost:4567/stashes
    
    HTTP/1.1 201 Created
    Content-Type: application/json
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
    Access-Control-Allow-Credentials: true
    Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
    Content-Length: 32
    Connection: keep-alive
    Server: thin
    
    {"path":"direct-access/example-1"}

  3. Now let’s create a stash with a path called direct-access/example-2 via the /stashes/:path (POST) API (i.e. using direct access to stash content data):

    $ curl -s -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"message": "hello world"}' \
    http://localhost:4567/stashes/direct-access/example-2
    
    HTTP/1.1 201 Created
    Content-Type: application/json
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
    Access-Control-Allow-Credentials: true
    Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
    Content-Length: 32
    Connection: keep-alive
    Server: thin
    
    {"path":"direct-access/example-2"}
    NOTE: in the above example, we are not providing a complete stash definition (e.g. defining the path and content attributes), because the /stashes/:path API provides direct access to stash content data.

  4. Now let’s see what our stashes looks like:

    $ curl -s http://localhost:4567/stashes | jq .
    [
     {
       "expire": -1,
       "content": {
         "message": "hello world"
       },
       "path": "direct-access/example-1"
     },
     {
       "expire": -1,
       "content": {
         "message": "hello world"
       },
       "path": "direct-access/example-2"
     }
    ]
    As you can see, even though we didn’t provide a complete stash definition in step 3, the resulting stash is the same format as the stash created in step 2.