Stashes

Reference documentation

• What is a Sensu stash?
  • The Sensu key/value store
• The Sensu stash specification
  • Example Sensu stash
  • Stash definition specification
    • Stash attributes
    • content attributes
      • Direct access to stash content data

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": "silence/server-01"

"content": {
  "message": "hello world!"
}

"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.