Schedule observability data collection

or click any element in the pipeline to jump to it.

Sensu’s schedule function is based on subscriptions: transport topics to which the Sensu backend publishes check requests. The subscriptions you specify in your Sensu agent definition determine which checks the agent will execute. The Sensu backend schedules checks, publishes check execution requests to entities, and processes the observation data (events) it receives from the agent.

Agent and backend

The Sensu agent is a lightweight process that runs on the infrastructure components you want to monitor and observe. The agent registers with the Sensu backend as an entity with type: "agent". Agent entities are responsible for creating status and metrics events to send to the backend event pipeline.

The Sensu backend includes an integrated structure for scheduling checks using subscriptions and an event pipeline that applies event filters, mutators, and handlers, an embedded etcd datastore for storing configuration and state, and the Sensu API, Sensu web UI, and sensuctl command line tool.

The Sensu agent is available for Linux, macOS, and Windows. The Sensu backend is available for Debian- and RHEL-family distributions of Linux. Learn more in the agent and backend references.

Follow the installation guide to install the agent and backend.


Subscriptions are at the core of Sensu’s publish/subscribe pattern of communication: subscriptions are transport topics to which the Sensu backend publishes check requests. Sensu entities become subscribers to these topics via their individual subscriptions attribute.

Each Sensu agent’s defined set of subscriptions determine which checks the agent will execute. Agent subscriptions allow Sensu to request check executions on a group of systems at a time instead of a traditional 1:1 mapping of configured hosts to monitoring checks.

In each check’s definition, you can specify which subscriptions should run the check. At the same time, your entities are “subscribed” to these subscriptions. Subscriptions make sure your entities automatically run the appropriate checks for their functionality.

The following example shows the resource definition for a check with the system and linux subscriptions. This check would run on any entities whose definitions also specify the system or linux subscriptions.

type: CheckConfig
api_version: core/v2
  name: check-cpu
  check_hooks: null
  command: check-cpu-usage -w 75 -c 90
  env_vars: null
  - slack
  high_flap_threshold: 0
  interval: 60
  low_flap_threshold: 0
  output_metric_format: ""
  output_metric_handlers: null
  proxy_entity_name: ""
  publish: true
  round_robin: false
  - check-cpu-usage
  secrets: null
  stdin: false
  subdue: null
  - system
  - linux
  timeout: 0
  ttl: 0
  "type": "CheckConfig",
  "api_version": "core/v2",
  "metadata": {
    "name": "check-cpu"
  "spec": {
    "check_hooks": null,
    "command": "check-cpu-usage -w 75 -c 90",
    "env_vars": null,
    "handlers": [
    "high_flap_threshold": 0,
    "interval": 60,
    "low_flap_threshold": 0,
    "output_metric_format": "",
    "output_metric_handlers": null,
    "proxy_entity_name": "",
    "publish": true,
    "round_robin": false,
    "runtime_assets": [
    "secrets": null,
    "stdin": false,
    "subdue": null,
    "subscriptions": [
    "timeout": 0,
    "ttl": 0

Subscriptions typically correspond to a specific role or responsibility. For example, you might add all the checks you want to run on your database entities to a database subscription. Rather than specifying these checks individually for every database you are monitoring, you add the database subscription to your database entities and they run the desired checks automatically.

Read the subscriptions reference to learn more.

Communication between the agent and backend

The Sensu agent uses WebSocket (ws) protocol to send and receive JSON messages with the Sensu backend. For optimal network throughput, agents will attempt to negotiate the use of Protobuf serialization when communicating with a Sensu backend that supports it. This communication is via clear text by default.

Follow Secure Sensu to configure the backend and agent for WebSocket Secure (wss) encrypted communication.