Adding a Client

Sensu clients are pieces of infrastructure that Sensu monitors for you. The Sensu client software allows you to register a running instance of itself as capable of running any checks they might be eligible for.

Infrastructure sometimes includes hardware or services that don’t necessarily support running the Sensu client software but still needs to be monitored. For those cases, proxy clients let you monitor anything you can tell Sensu about.

Adding a Sensu Client

One of the first challenges new Sensu users often encounter is learning what is required to get a remote Sensu client to communicate with the Sensu server. If you’re in a hurry, skip ahead to add a remote Sensu client for step-by-step instructions.

Alternatively, once you understand the two requirements for adding Sensu clients, you’ll know everything you need to start deploying Sensu clients to your entire infrastructure. Please continue reading to learn how adding Sensu clients starts with configuration and is ultimately all about the transport.

It starts with configuration

Sensu is designed to be operated via configuration. This core philosophy is what enables Sensu to work so seamlessly with modern automation solutions and configuration management platforms. To learn more about how Sensu is configured, please consult the Sensu configuration reference documentation.

The Sensu client requires a minimal amount of configuration to enable it to automatically register itself with the Sensu server, which configuration includes a client definition (e.g. the client name, address, and subscriptions), and a transport definition.

It’s all about the transport

The Sensu processes use a transport (a message bus) for communication. By default this is RabbitMQ, but modern versions of Sensu have added support for alternative transports including Redis. Without a transport connection, a Sensu client will be unable to send monitoring data (e.g. keepalive messages, check results, etc). In order to connect to the transport, the Sensu client will need three pieces of information:

  • Which transport to use (this tells Sensu which transport library should it load, and which configuration scope should it use to obtain connection details)
  • A valid transport definition (this provides Sensu with an IP address or hostname, and any security credentials needed to connect to the transport)
  • Network access to the transport socket (i.e. the Sensu client will need outbound network access, and the transport will need to be configured to listen for remote network connections)

Add a remote Sensu client

With the exception of Sensu clients that are running on the Sensu server (which is very useful and strongly recommended), all Sensu clients are essentially “remote clients” as they have to establish network communication to send monitoring data (e.g. client keepalives and check results). Please note the following steps that are required to add a remote Sensu client:

  1. Configure the client. Create a client definition, located at /etc/sensu/conf.d/client.json with the following contents (replacing the values for the client name, address, and subscriptions with the corresponding values for the client you are adding):

      "client": {
        "name": "i-041256",
        "address": "",
        "subscriptions": [

  2. Tell the client which transport to use. Create a transport definition at /etc/sensu/conf.d/transport.json with the following contents (replacing the value for the transport name with the corresponding value for the transport you are using; e.g. use "transport": "redis" if you are using the Redis transport).

      "transport": {
        "name": "rabbitmq",
        "reconnect_on_error": true

  3. Tell the client how to connect to the transport. Create a transport definition at /etc/sensu/conf.d/rabbitmq.json (or /etc/sensu/conf.d/redis.json if you are using the Redis transport). NOTE: please consult the corresponding reference documentation for RabbitMQ or Redis for more configuration examples and detailed information on how to configure Sensu’s connection.

  4. Start the client Start the Sensu client and verify connectivity by consulting the Sensu client log file: NOTE: The service command will not work on CentOS 5, the sysvinit script must be used, e.g. sudo /etc/init.d/sensu-client start

    sudo service sensu-client start

Proxy Clients

Sometimes, a logical piece of infrastructure isn’t a device we can run Sensu on. Fundamentally, Sensu gives you the flexibility to separate how checks run from where they run, which lets you monitor arbitrary, named ‘black box’ devices or services.

For example, you may have a router that you can’t run Sensu on but publishes interesting information over SNMP that you want to gather metrics from. Or maybe you monitor which other datacenters are visible/online to you, or have any number of creative use cases. You can create a proxy client that can have attributes for use in check execution, allowing you to use the client registry naturally for ‘managed’ and ‘unmanaged’ infrastructure. See the reference for creating proxy clients or details on writing checks against them for more.


Intro to Checks