Tokens

How do tokens work?

When a check is scheduled to be executed by an agent, it first goes through a token substitution step. Any tokens matching attribute values in the check are applied, and then the check is executed. Invalid templates or unmatched tokens will return an error, which is logged and sent to the Sensu backend message transport. Checks with token matching errors will not be executed.

New and improved tokens

Sensu 2.0 uses the Go template package to implement token substitution. Instead of using triple colons ::: as in 1.x token substitution, 2.0 token substitution uses double curly braces around the token, and a dot before the attribute to be substituted, such as: {{ .System.Hostname }}.

Sensu tokens specification

Token substitution syntax

Tokens are invoked by wrapping references to entity or custom attributes with double curly braces, such as {{ .ID }} to substitute an entity’s ID value. Nested Sensu entity attributes can be accessed via dot notation (ex: System.Arch).

  • {{ .ID }} would be replaced with the entity ID attribute
  • {{ .URL }} would be replaced with a custom attribute called url
  • {{ .Disk.Warning }} would be replaced with a custom attribute called warning nested inside of a JSON hash called disk

Token substitution default values

In the event that an attribute is not provided by the entity, a token’s default value will be substituted. Token default values are separated by a pipe character and the word default (| default), and can be used to provide a “fallback value” for entities that are missing a specified token attribute.

  • {{.URL | default "https://sensu.io"}} would be replaced with a custom attribute called url. If no such attribute called url is included in the client definition, the default (or fallback) value of https://sensu.io will be used to substitute the token.

Unmatched tokens

If a token is unmatched during check preparation, the agent check handler will return an error, and the check will not be executed. Unmatched token errors will look similar to the following:

error: unmatched token: template: :1:22: executing "" at <.System.Hostname>: map has no entry for key "System"

Check config token errors will be logged by the agent, and sent to Sensu backend message transport as a check failure.

Examples

Token substitution for check thresholds

In this example check configuration, the check-disk-usage.rb command accepts -w (warning) and -c (critical) arguments to indicate the thresholds (as percentages) for creating warning or critical events. If no token substitutions are provided by a check configuration, it will use default values to create a warning event at 80% disk capacity (i.e. {{ .Disk.Warning | default 80 }}), and a critical event at 90% capacity (i.e. {{ .Disk.Critical | default 90 }}).

{
  "check_hooks": null,
  "command": "check-disk-usage.rb -w {{.Disk.Warning | default 80}} -c {{.Disk.Critical | default 90}}",
  "environment": "{{ .Environment | default \"production\" }}",
  "handlers": [],
  "high_flap_threshold": 0,
  "interval": 60,
  "low_flap_threshold": 0,
  "name": "check-disk-usage",
  "organization": "default",
  "proxy_entity_id": "",
  "publish": true,
  "round_robin": false,
  "runtime_assets": [],
  "stdin": false,
  "subdue": null,
  "subscriptions": [
    "staging"
  ],
  "timeout": 0
}

The following example entity would provide the necessary attributes to override the .Disk.Warning, .Disk.Critical, and .Environment tokens declared above.

{
  "class": "agent",
  "deregister": false,
  "deregistration": {},
  "environment": "staging",
  "id": "example-hostname",
  "keepalive_timeout": 60,
  "last_seen": 1523387195,
  "organization": "default",
  "redact": [
    "password",
    "passwd",
    "pass",
    "api_key",
    "api_token",
    "access_key",
    "secret_key",
    "private_key",
    "secret"
  ],
  "subscriptions": [
    "entity:example-hostname",
    "staging"
  ],
  "system": {
    "hostname": "example-hostname",
    "os": "linux",
    "platform": "ubuntu",
    "platform_family": "debian",
    "platform_version": "16.04",
    "network": {
      "interfaces": [
        {
          "name": "lo",
          "addresses": [
            "127.0.0.1/8",
            "::1/128"
          ]
        },
        {
          "name": "eth0",
          "mac": "52:54:00:20:1b:3c",
          "addresses": [
            "93.184.216.34/24",
            "2606:2800:220:1:248:1893:25c8:1946/10"
          ]
        }
      ]
    },
    "arch": "amd64"
  },
  "user": "agent",
  "region": "us-west-1",
  "team": "ops",
  "disk": {
    "warning": 75,
    "critical": 85
  }
}