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 shows how Sensu coordinates check execution based on subscriptions.
For example, the
check_cpu check includes the
All three entities include the
system subscription, so all three entities will execute the
However, only the
database01 entities will execute
check_sshd_process — the
webserver01 entity does not include the
linux subscription required to execute
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
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.
Suppose you have a Sensu agent entity with the
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:
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 entity.
For example, if you want your agent entity to execute checks for the
webserver subscription, you can add it with the
sensu-agent start --subscriptions linux,webserver --log-level debug
Now your agent entity will execute checks with the
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 agent entities:
- To configure subscriptions for a check, add one or more subscription names in the check
- To configure subscriptions for an agent entity, specify a subscription that matches one subscription in each check that the agent’s entities should execute.
The Sensu backend schedules checks once per interval for each agent entity with a matching subscription.
For example, if you have three entities configured with the
system subscription, a check configured with the
system subscription results in three monitoring events per interval: one check execution per entity per interval.
WARNING: Make sure that your checks and entities share only one subscription.
Entities receive a separate check request for each matching subscription, even if the requests are for the same check.
This can result in check execution errors as well as unexpected results for check
history and the features that rely on it.
In addition to the subscriptions defined in the agent configuration, Sensu agent entities subscribe automatically to subscriptions that match their entity
For example, an agent entity with
name: "i-424242" subscribes to check requests with the subscription
This makes it possible to generate ad hoc check requests that target specific entities via the API.
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 core/v2/checks API endpoints, whether the
publish attribute is set to
To target the subscriptions defined in the check, include only the check name in the request body (for example,
To override the check’s subscriptions and target an alternate entity or group of entities, add the subscriptions attribute to the request body:
Monitor multiple servers
You can use subscriptions to configure monitoring and observability for multiple servers with different operating systems and monitoring requirements.
For example, suppose you want to set up monitoring for these servers:
Six Linux servers:
- Get CPU, memory, and disk status for all six
- Get NGINX metrics for four
- Get PostgreSQL metrics for two
Six Windows servers:
- Get CPU, memory, and disk checks for all six
- Get SQL Server metrics for two
This diagram shows the subscriptions to list for each of the 12 servers (the entities) and for each check to achieve the example monitoring configuration:
In this scenario, none of the Windows servers should execute the NGINX metrics check, so the
check_nginx subscriptions do not match any subscriptions listed for any of the Windows servers.
Two of the six Windows servers should execute the SQL Server metrics check, so the subscription listed in the
check_sqlsrv definition matches a subscription listed for those two Windows server entities.
Subscription naming considerations
Consistent subscription naming helps you group and filter different entities and quickly understand which entities will be affected by any changes.
Subscriptions based on function are helpful when you’re creating silences.
For example, if you need to silence all webservers for maintenance, it’s easier to silence the affected entities if they all include a subscription like
webserver instead of identifying and silencing all of your webserver entities individually.
Other function-based subscriptions might be
Subscription naming is also important in the context of API and sensuctl filters and web UI searches.
Consistent subscription naming means that search queries like
"linux" in checks.subscriptions will actually retrieve all of your checks that run on Linux agents.
To make subscriptions more granular, use camel case to append information about environment, roles, entity type, or any other category as needed.
For example, you can use
webserverProd to specify a distinction between development and production webservers while preserving your ability to find all webserver entities with a search query like
"webserver" in entity.subscriptions.