Subscriptions reference

Sensu uses the publish/subscribe model of communication. The publish/subscribe model is powerful in ephemeral or elastic infrastructures, where the names and numbers of things change over time.

Because Sensu uses the publish/subscribe model, you can write checks even if you don’t know the specific names of the entities that should run the checks. Likewise, your entities do not need to know the specific names of the checks they should execute. The Sensu backend coordinates check execution for you by comparing the subscriptions you specify in your checks and entities to determine which entities should receive execution requests for a given check.

The diagram below uses overlap between entities and checks to show how Sensu coordinates check execution based on subscriptions. For example, the check_cpu check includes the system subscription. All three entities include the system subscription, so all three entities will execute the check_cpu check. However, only Entity A and Entity C will execute check_sshd_process — Entity B does not include the linux subscription required to execute check_sshd_process.

Venn diagram example of Sensu check execution based on subscriptions

Sensu check execution based on subscriptions

Sensu subscriptions are equivalent to topics in a traditional publish/subscribe system. Sensu entities become subscribers to these topics via the strings you specify with the agent subscriptions flag. Sensu checks have a subscriptions attribute, where you specify strings to indicate which subscribers will execute the checks. For Sensu to execute a check, the check definition must include a subscription that matches the subscription of at least one Sensu entity.

As loosely coupled references, subscriptions avoid the fragility of traditional host-based monitoring systems. Subscriptions allow you to configure check requests in a one-to-many model for entire groups or subgroups of entities rather than a traditional one-to-one mapping of configured hosts or observability checks.

Configure subscriptions

Sensu automatically executes a check when the check definition includes a subscription that matches a subscription for at least one Sensu entity. In other words, subscriptions are configured for both checks and agents:

  • To configure subscriptions for a check, add one or more subscription names in the check subscriptions attribute.
  • To configure subscriptions for an agent, configure the subscriptions by specifying the subscriptions that include the checks the agent’s entities should execute.

The Sensu backend schedules checks once per interval for each agent with a matching subscription. For example, if you have three agents configured with the system subscription, a check configured with the system subscription results in three monitoring events per interval: one check execution per agent per interval.

In addition to the subscriptions defined in the agent configuration, Sensu agent entities subscribe automatically to subscriptions that match their entity name. For example, an agent entity with name: "i-424242" subscribes to check requests with the subscription entity:i-424242. This makes it possible to generate ad hoc check requests that target specific entities via the API.

NOTE: You can directly add, update, and delete subscriptions for individual entities via the backend with sensuctl, the entities API, and the web UI.

Publish checks

If you want Sensu to automatically schedule and execute a check according to its subscriptions, set the publish attribute to true in the check definition.

You can also manually schedule ad hoc check execution with the check API, whether the publish attribute is set to true or false. To target the subscriptions defined in the check, include only the check name in the request body (e.g. "check": "check_cpu"). To override the check’s subscriptions and target an alternate entity or group of entities, add the subscriptions attribute to the request body:

  "check": "check_cpu",
  "subscriptions": [


Suppose you have a Sensu agent with the linux subscription:

sensu-agent start --subscriptions linux --log-level debug

For this agent to run a check, you must have at least one check with linux specified in the subscriptions attribute, such as this check to collect status information:

type: CheckConfig
api_version: core/v2
  name: collect_info
  namespace: default
  - slack
  interval: 10
  publish: true
  - linux
  "type": "CheckConfig",
  "api_version": "core/v2",
  "metadata": {
    "namespace": "default",
    "name": "collect_info"
  "spec": {
    "command": "",
    "handlers": [
    "interval": 10,
    "publish": true,
    "subscriptions": [

If this is your only check for the linux subscription, this is the only check that your agent will execute. If you add more checks that specify the linux subscription, your agent will automatically run those checks too (as long as the publish attribute is set to true in the check definitions).

You can also add more subscriptions for your agent. For example, if you want your agent to execute checks for the webserver subscription, you can add it with the subscriptions flag:

sensu-agent start --subscriptions linux,webserver --log-level debug

Now your agent will execute checks with the linux or webserver subscriptions.

To directly add, update, and delete subscriptions for individual entities, use sensuctl, the entities API, or the web UI.