Sensu Client

Reference documentation

What is a Sensu client?

Sensu clients are monitoring agents, which are installed and run on every system (e.g. server, container, etc) that needs to be monitored. The client is responsible for registering the system with Sensu, sending client keepalive messages (the Sensu heartbeat mechanism), and executing monitoring checks. Each client is a member of one or more subscriptions – a list of roles and/or responsibilities assigned to the system (e.g. a webserver, database, etc). Sensu clients will “subscribe” to (or watch for) check requests published by the Sensu server (via the Sensu Transport), execute the corresponding requests locally, and publish the results of the check back to the transport (to be processed by a Sensu server).

Client keepalives

What is a client keepalive?

Sensu Client keepalives are the heartbeat mechanism used by Sensu to ensure that all registered Sensu clients are still operational and able to reach the Sensu Transport. Sensu clients publish keepalive messages containing client configuration data to the Sensu transport every 20 seconds. If a Sensu client fails to send keepalive messages over a period of 120 seconds (by default), the Sensu server (or Sensu Enterprise) will create a keepalive event. Keepalives can be used to identify unhealthy systems and network partitions (among other things), and keepalive events can trigger email notifications and other useful actions.

Client registration & the client registry

In practice, client registrations happens when a Sensu server processes a client keepalive message for a client that is not already registered in the Sensu client registry (based on the configured client name or source attribute). This client registry is stored in the Sensu data store, and is accessible via the Sensu Clients API.

All Sensu client data provided in client keepalive messages gets stored in the client registry, which data is used to add context to Sensu Events and to detect Sensu clients in an unhealthy state.

Registration events

If a Sensu event handler named registration is configured, or if a Sensu client definition includes a registration attribute, the Sensu server will create and process a Sensu event for the client registration, applying any configured filters and mutators before executing the configured handler(s).

Registration events are useful for executing one-time handlers for new Sensu clients. For example, registration event handlers can be used to update external Configuration Management Databases (CMDBs) such as ServiceNow, etc.

To configure a registration event handler, please refer to the Sensu event handler documentation for instructions on creating a handler named registration. Alternatively, please see Client definition registration attributes, below.

WARNING: registration events are not stored in the event registry (in the Sensu data store), so they are not accessible via the Sensu API; however, all registration events are logged in the Sensu server log.

Proxy clients

Sensu proxy clients (formerly known as “Just-in-time” or “JIT” clients) are dynamically created clients, added to the client registry if a client does not already exist for a check result.

Proxy client registration differs from keepalive-based registration because the registration event happens while processing a check result (not a keepalive message). If a check result includes a source attribute, a proxy client will be created for the source, and the check result will be stored under the newly created client. Sensu proxy clients allow Sensu to monitor external resources (e.g. on systems and/or devices where a sensu-client cannot be installed, such a network switches), using the defined check source to create a proxy clients for the external resource. Once created, proxy clients work much in the same way as any other Sensu client; e.g. they are used to store check execution history and provide context within event data.

NOTE: keepalive monitoring is not supported for proxy clients, as they are inherently unable to run a sensu-client.

Proxy client example

Proxy clients are created when a check result includes a source attribute, as follows:

{
  "check": {
    "status": 0,
    "command": "check-http.rb -u https://sensuapp.org",
    "subscribers": [
      "demo"
    ],
    "interval": 60,
    "name": "sensu-website",
    "source": "sensuapp.org",
    "issued": 1458934742,
    "executed": 1458934742,
    "duration": 0.637,
    "output": "CheckHttp OK: 200, 78572 bytes\n"
  },
  "client": "sensu-docs"
}

NOTE: this source attribute can be provided in a check definition, or included in a check result published to the Sensu client input socket.

By default, proxy client data includes a minimal number of attributes. The following is an example of proxy client data that is added to the registry.

{
  "name": "switch-x",
  "address": "unknown",
  "subscriptions": [],
  "keepalives": false
}

The Sensu API can be used to update proxy client data in the client registry. To update proxy client data, please refer to the Client API reference documentation.

Create a proxy client via the client socket

The following is an example of how to create a proxy client payload via the client socket, using netcat:

echo '{"source": "mysql_01", "name": "app_01", "output": "could not connect to mysql", "status": 1}' | nc localhost 3030

How are keepalive events created?

Sensu servers (including Sensu Enterprise) monitor the Sensu client registry for stale client data, detecting clients that have failed to send client keepalive messages for more than 120 seconds (by default). When a Sensu server detects that a client hasn’t sent a keepalive message within the configured threshold, the Sensu server (or Sensu Enterprise) will create an event (this is different from how events are created for monitoring checks; see “How are Sensu events created?”).

Client keepalive configuration

For more information on configuring client keepalives, please see the client keepalive attribute reference documentation (below).

Sensu client keepalives are published to the Sensu transport every 20 seconds. Client keepalive behavior can be configured per Sensu client, allowing each Sensu client to set its own alert thresholds and keepalive event handlers. By default, client data is considered stale if a keepalive hasn’t be received in 120 seconds (WARNING). By default, keepalive events will be sent to the Sensu handler named keepalive if defined, or the default handler will be used.

To configure the keepalive check for a Sensu client, please refer to the client keepalive attributes reference documentation.

Client signature

Sensu client definitions may specify a unique string identifier as their signature, which is included in each keepalive message.

Once a client advertises a signature via keepalives, the server will expect that signature to be present in any keepalives or check results originating from the client. Any keepalives or check results which do not contain a matching signature will be dropped with an “invalid client signature” warning in the log.

A client can begin to use a signature if one was not previously configured, but removing a client signature requires deleting the client.

Providing a unique client signature prevents other clients from accidentally or maliciously submitting keepalives or check results using the same client name.

Client subscriptions

What is a client subscription?

Sensu’s use of the publish/subscribe pattern of communication allows for automated registration & de-registration of ephemeral systems. At the core of this model are Sensu client subscriptions.

Each Sensu client has a defined set of subscriptions, a list of roles and/or responsibilities assigned to the system (e.g. a webserver, database, etc). These subscriptions determine which monitoring checks are executed by the client. Client 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. Sensu checks target Sensu client subscriptions, using the check definition attribute subscribers.

Round-robin client subscriptions

Round-robin client subscriptions allow checks to be executed on a single client within a subscription, in a round-robin fashion. To create a round-robin client subscription, prepend the subscription name with roundrobin:, e.g. roundrobin:elasticsearch. Any check that targets the roundrobin:elasticsearch subscription will have its check requests sent to clients in a round-robin fashion, meaning only one member (client) in the subscription will execute a roundrobin check each time it is published.

The following is a Sensu client definition that includes a round-robin subscription.

{
  "client": {
    "name": "i-424242",
    "address": "8.8.8.8",
    "subscriptions": [
      "production",
      "webserver",
      "roundrobin:webserver"
    ]
  }
}

The following is a Sensu check definition that targets a round-robin subscription.

{
  "checks": {
    "web_application_api": {
      "command": "check-http.rb -u https://localhost:8080/api/v1/health",
      "subscribers": [
        "roundrobin:webserver"
      ],
      "interval": 20
    }
  }
}

Client subscription configuration

To configure Sensu client subscriptions for a client, please refer to the client subscriptions attribute reference documentation.

In addition to the subscriptions defined in the client configuration, Sensu clients also subscribe automatically to a subscription matching their client name. For example, a client named i-424242 will subscribe to check requests for the subscription client:i-424242. This makes it possible to generate ad-hoc check requests targeting specific clients via the /request API.

Client socket input

What is the Sensu client socket?

Every Sensu client has a TCP, UDP and HTTP socket listening for external check result input. The Sensu client socket(s) listen by default on localhost port 3030 for TCP/UDP and 3031 for HTTP and expect JSON formatted check results, allowing external sources (e.g. your web application, backup scripts, etc.) to push check results without needing to know anything about Sensu’s internal implementation. An excellent client socket use case example is a web application pushing check results to indicate database connectivity issues.

To configure the Sensu client socket for a client, please refer to the client socket attributes.

HTTP Socket

The HTTP socket, just like the TCP and UDP sockets, accepts check results, but it requires a well-formed HTTP request and exposes other functionality that is not possible with the raw TCP/UDP sockets. In exchange for a bit more complexity, the HTTP socket interface has the advantage of being more expressive than a raw TCP/UDP socket, both in the requests that it accepts and how it responds, and so exposes more functionality. The following endpoints are available for the HTTP socket:

GET /info

This endpoint returns 200 OK with some basic Sensu information like the version and transport metrics.

POST /results This endpoint expects an application/json body with a check result

GET /settings

This endpoint responds with 200 OK and the sensu configuration. Due to the possible sensitive nature of the client settings (e.g passwords might be in the config) this endpoint is protected using HTTP basic authentication and by default the information returned is redacted (e.g common config keys like ‘password’ have their values replaced by ‘REDACTED’). See the ‘redact’ configuration option if you need control over what is redacted. This endpoint accepts the optional query string ?redacted=false to disable redaction.

Refer to the http client socket attributes for details on configuring the HTTP basic authentication details that this endpoint requires.

GET /brew

This endpoint gets you some fresh coffee. Try it!

Any requests for unknown endpoints will get a 404 with some help information in the body.

At the moment only unsecure HTTP (no HTTPS) is supported.

To configure the Sensu HTTP client socket, please refer to the http client socket attributes.

Example client socket usage

The following is an example demonstrating external check result input via the Sensu client TCP socket. The example uses Bash’s built-in /dev/tcp file to communicate with the Sensu client socket.

echo '{"name": "app_01", "output": "could not connect to mysql", "status": 1}' > /dev/tcp/localhost/3030

Netcat can also be used, instead of the TCP file:

echo '{"name": "app_01", "output": "could not connect to mysql", "status": 1}' | nc localhost 3030

You can do the same using the HTTP socket:

curl -v -H "Content-Type: application/json" -X POST -d '{"name": "app_01", "output": "could not connect to mysql", "status": 1}' localhost 3031

Creating a “dead man’s switch”

The Sensu client socket(s) in combination with check TTLs can be used to create what’s commonly referred to as “dead man’s switches”. Outside of the software industry, a dead man’s switch is a switch that is automatically triggered if a human operator becomes incapacitated (source: Wikipedia). Sensu is more interested in detecting silent failures than incapacited human operators. By using Check TTLs, Sensu is able to set an expectation that a Sensu client will continue to publish results for a check at a regular interval. If a Sensu client fails to publish a check result and the check TTL expires, Sensu will create an event to indicate the silent failure. For more information on check TTLs, please refer to the check attributes reference documentation.

A great use case for the Sensu client socket is to create a dead man’s switch for backup scripts, to ensure they continue to run successfully at regular intervals. If an external source sends a Sensu check result with a check TTL to the Sensu client socket, Sensu will expect another check result from the same external source before the TTL expires.

The following is an example of external check result input via the Sensu client TCP socket, using a check TTL to create a dead man’s switch for MySQL backups. The example uses a check TTL of 25200 seconds (or 7 hours). A MySQL backup script using the following code would be expected to continue to send a check result at least once every 7 hours or Sensu will create an event to indicate the silent failure.

echo '{"name": "backup_mysql", "ttl": 25200, "output": "backed up mysql successfully | size_mb=568", "status": 0}' | nc localhost 3030
echo '{"name": "backup_mysql", "ttl": 25200, "output": "failed to backup mysql", "status": 1}' | nc localhost 3030

Standalone check execution scheduler

In addition to subscribing to client subscriptions and executing check requests published by the Sensu server, the Sensu client is able to maintain its own/separate schedule for standalone checks.

Because the Sensu client shares the same check scheduling algorithm as the Sensu server, it is not only possible to have consistency between subscription checks and standalone checks — it’s also possible to maintain consistency between standalone checks across an entire infrastructure (assuming that system clocks are synchronized via NTP).

Client configuration

Example client definition

The following is an example Sensu client definition, a JSON configuration file located at /etc/sensu/conf.d/client.json. This client definition provides Sensu with information about the system on which it resides. This is a production system, running a web server and a MySQL database. The client ‘name’ attribute is required in the definition, and must be unique.

{
  "client": {
    "name": "i-424242",
    "address": "8.8.8.8",
    "subscriptions": [
      "production",
      "webserver",
      "mysql"
    ],
    "socket": {
      "bind": "127.0.0.1",
      "port": 3030
    }
  }
}

Client definition specification

The client definition uses the { "client": {} } configuration scope.

client attributes

name
description
A unique name for the client. The name cannot contain special characters or spaces.
required
false
default
System hostname as determined by Ruby Socket.gethostname
type
String
validation
/^[\w\.-]+$/
example
"name": "i-424242"
address
description
An address to help identify and reach the client. This is only informational, usually an IP address or hostname.
required
false
default
Non-loopback IPv4 address as determined by Ruby Socket.ip_address_list
type
String
example
"address": "8.8.8.8"
subscriptions
description
An array of client subscriptions, a list of roles and/or responsibilities assigned to the system (e.g. webserver). These subscriptions determine which monitoring checks are executed by the client, as check requests are sent to subscriptions. The subscriptions array items must be strings.
required
true
type
Array
example
"subscriptions": ["production", "webserver"]
safe_mode
description
If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the check.
required
false
type
Boolean
default
false
example
"safe_mode": true
redact
description
Client definition attributes to redact (values) when logging and sending client keepalives.
required
false
type
Array
default
[
  "password", "passwd", "pass",
  "api_key", "api_token", "access_key",
  "secret_key", "private_key",
  "secret"
]
example
"redact": [
  "password",
  "ec2_access_key",
  "ec2_secret_key"
]
socket
description
The socket definition scope, used to configure the Sensu client socket.
required
false
type
Hash
example
"socket": {}
keepalives
description
If Sensu should monitor keepalives for this client.
required
false
default
true
type
Boolean
example
"keepalives": false
keepalive
description
The keepalive definition scope, used to configure Sensu client keepalives behavior (e.g. keepalive thresholds, etc).
required
false
type
Hash
example
"keepalive": {}
signature
description
Unique string used to authenticate check results from the client in question.
required
false
type
String
example
"signature": "yVNxtPbRGwCYFYEr3V"
registration
description
The registration definition scope, used to configure Sensu registration event handlers.
required
false
type
Hash
example
"registration": {}
deregister
description
If a deregistration event should be created upon Sensu client process stop.
required
false
default
false
example
"deregister": true
deregistration
description
The deregistration definition scope, used to configure automated Sensu client de-registration.
required
false
type
Hash
example
"deregistration": {}
ec2
description
The ec2 definition scope, used to configure the Sensu Enterprise AWS EC2 integration (Sensu Enterprise users only).
required
false
type
Hash
example
"ec2": {}
chef
description
The chef definition scope, used to configure the Sensu Enterprise Chef integration (Sensu Enterprise users only).
required
false
type
Hash
example
"chef": {}
puppet
description
The puppet definition scope, used to configure the Sensu Enterprise Puppet integration (Sensu Enterprise users only).
required
false
type
Hash
example
"puppet": {}
servicenow
description
The servicenow definition scope, used to configure the Sensu Enterprise ServiceNow integration (Sensu Enterprise users only).
required
false
type
Hash
example
"servicenow": {}

socket attributes

The following attributes are configured within the { "client": { "socket": {} } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "socket": {
      "bind": "127.0.0.1",
      "port": 3030
    }
  }
}
ATTRIBUTES
bind
description
The address to bind the Sensu client socket to.
required
false
type
String
default
127.0.0.1
example
"bind": "0.0.0.0"
port
description
The port the Sensu client socket listens on.
required
false
type
Integer
default
3030
example
"port": 3032

http socket attributes

The following attributes are configured within the { "client": { "http_socket": {} } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "http_socket": {
      "bind": "127.0.0.1",
      "port": 3031,
      "user": "http-auth-user-name",
      "password": "use-somethign-secure-here"
    }
  }
}
ATTRIBUTES
bind
description
The address to bind the Sensu client socket to.
required
false
type
String
default
127.0.0.1
example
"bind": "0.0.0.0"
port
description
The port the HTTP Sensu client socket listens on.
required
false
type
Integer
default
3031
example
"port": 8000
user
description
The user name to enforce HTTP authentication on endpoints that require it
required
false
type
String
example
"user": "sensu"
password
description
The password to enforce HTTP authentication on endpoints that require it
required
false
type
String
example
"password": "F76639PML6c7sk5nI46N"

keepalive attributes

The following attributes are configured within the { "client": { "keepalive": {} } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "keepalive": {
      "handler": "pagerduty",
      "thresholds": {
        "warning": 40,
        "critical": 60
      }
    }
  }
}
ATTRIBUTES
handler
description
The Sensu event handler (name) to use for events created by keepalives.
required
false
type
String
example
"handler": "pagerduty"
handlers
description
An array of Sensu event handlers (names) to use for events created by keepalives. Each array item must be a string.
required
false
type
Array
example
"handlers": ["pagerduty", "chef"]
thresholds
description
A set of attributes that configure the client keepalive “staleness” thresholds, when a client is determined to be unhealthy.
required
false
type
Hash
example
"thresholds": {}

thresholds attributes (for client keepalives)

The following attributes are configured within the { "client": { "keepalive": { "thresholds": {} } } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "keepalive": {
      "...": "...",
      "thresholds": {
        "warning": 40,
        "critical": 60
      }
    }
  }
}
ATTRIBUTES
warning
description
The warning threshold (in seconds) where a Sensu client is determined to be unhealthy, not having sent a keepalive in so many seconds.

WARNING: keepalive messages are sent at an interval of 20 seconds. Setting a warning threshold of 20 seconds or fewer will result in false-positive events. Also note that due to the potential for NTP synchronization issues and/or network latency or packet loss interfering with regular delivery of client keepalive messages, we recommend a minimum warning threshold of 40 seconds.

required
false
type
Integer
default
120
example
"warning": 60
critical
description
The critical threshold (in seconds) where a Sensu client is determined to be unhealthy, not having sent a keepalive in so many seconds.

WARNING: keepalive messages are sent at an interval of 20 seconds. Setting a critical threshold of 20 seconds or fewer will result in false-positive events. Also note that due to the potential for NTP synchronization issues and/or network latency or packet loss interfering with regular delivery of client keepalive messages, we recommend a minimum critical threshold of 60 seconds.

required
false
type
Integer
default
180
example
"critical": 90

registration attributes

The following attributes are configured within the { "client": { "registration": {} } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "registration": {
      "handler": "servicenow"
    }
  }
}
ATTRIBUTES
handler
description
The registration handler that should process the client registration event.
required
false
type
String
default
registration
example
"handler": "registration_cmdb"

NOTE: client registration attributes are used to generate check result data for the registration event. Client registration attributes are merged with some default check definition attributes by the Sensu server during client registration, so any valid check definition attributes – including custom check definition attributes – may be used as registration attributes. The following attributes are provided as recommendations for controlling client registration behavior.

deregistration attributes

The following attributes are configured within the { "client": { "deregistration": {} } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "deregister": true,
    "deregistration": {
      "handler": "deregister_client"
    }
  }
}
ATTRIBUTES

NOTE: client deregistration attributes are used to generate check result data for the de-registration event. Client deregistration attributes are merged with some default check definition attributes by the Sensu server during client deregistration, so any valid check definition attributes – including custom check definition attributes – may be used as deregistration attributes, with the following exceptions (which are used to ensure the check result is valid): check name, output, status, and issued timestamp. The following attributes are provided as recommendations for controlling client deregistration behavior.

handler
description
The deregistration handler that should process the client deregistration event.
required
false
type
String
default
deregistration
example
"handler": "cmdb_deregistration"

ec2 attributes

The following attributes are configured within the { "client": { "ec2": {} } } configuration scope.

ENTERPRISE: This configuration is provided for using the built-in Sensu Enterprise AWS EC2 integration.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "ec2": {
      "instance_id": "i-424242",
      "allowed_instance_states": [
        "running",
        "rebooting"
      ]
    }
  }
}
ATTRIBUTES
instance_id
description
The AWS EC2 instance ID of the Sensu client system (if different than the client definition name attribute), used to lookup instance status information with the AWS EC2 API.
required
false
type
String
default
defaults to the value of the client definition name attribute.
example
"instance_id": "i-424242"
allowed_instance_states
description
The allowed operational states (e.g. "running") for the instance. If a client keepalive event is created and the EC2 API indicates that the instance is not in an allowed state (e.g. "terminated"), Sensu client will be removed from the client registry. This configuration can be provided to override the built-in Sensu Enterprise ec2 integration allowed_instance_states configuration for the client.
required
false
type
Array
allowed values
pending, running, rebooting, stopping, stopped, shutting-down, and terminated
default
running
example
"allowed_instance_states": [
  "pending",
  "running",
  "rebooting"
]
region
description
The AWS EC2 region to query for the EC2 instance state(s). This configuration can be provided to override the built-in Sensu Enterprise ec2 integration region configuration for the client.
required
false
type
String
allowed values :
default
us-east-1
example
"region": "us-west-1"
access_key_id
description
The AWS IAM user access key ID to use when querying the EC2 API. This configuration can be provided to override the built-in Sensu Enterprise ec2 integration access_key_id configuration for the client.
required
true
type
String
example
"access_key_id": "AlygD0X6Z4Xr2m3gl70J"
secret_access_key
description
The AWS IAM user secret access key to use when querying the EC2 API. This configuration can be provided to override the built-in Sensu Enterprise ec2 integration secret_access_key configuration for the client.
required
true
type
String
example
"secret_access_key": "y9Jt5OqNOqdy5NCFjhcUsHMb6YqSbReLAJsy4d6obSZIWySv"
timeout
description
The handler execution duration timeout in seconds (hard stop). This configuration can be provided to override the built-in Sensu Enterprise ec2 integration timeout configuration for the client.
required
false
type
Integer
default
10
example
"timeout": 30

chef attributes

The following attributes are configured within the { "client": { "chef": {} } } configuration scope.

ENTERPRISE: This configuration is provided for using the built-in Sensu Enterprise Chef integration.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "chef": {
      "node_name": "webserver01"
    }
  }
}
ATTRIBUTES
node_name
description
The Chef node name (if different than the client definition name attribute), used to lookup node data in the Chef API.
required
false
type
String
default
defaults to the value of the client definition name attribute.
example
"node_name": "webserver01"
endpoint
description
The Chef Server API endpoint (URL). This configuration can be provided to override the built-in Sensu Enterprise chef integration endpoint configuration for the client.
required
true
type
String
example
"endpoint": "https://api.chef.io/organizations/example"
flavor
description
The Chef Server flavor (is it enterprise?). This configuration can be provided to override the built-in Sensu Enterprise chef integration flavor configuration for the client.
required
false
type
String
allowed values
enterprise: for Hosted Chef and Enterprise Chef open_source: for Chef Zero and Open Source Chef Server
example
"flavor": "enterprise"
client
description
The Chef Client name to use when authenticating/querying the Chef Server API. This configuration can be provided to override the built-in Sensu Enterprise chef integration client configuration for the client.
required
true
type
String
example
"client": "sensu-server"
key
description
The Chef Client key to use when authenticating/querying the Chef Server API. This configuration can be provided to override the built-in Sensu Enterprise chef integration key configuration for the client.
required
true
type
String
example
"key": "/etc/chef/i-424242.pem"
ssl_pem_file
description
The Chef SSL pem file use when querying the Chef Server API. This configuration can be provided to override the built-in Sensu Enterprise chef integration ssl_pem_file configuration for the client.
required
false
type
String
example
"ssl_pem_file": "/etc/chef/ssl.pem"
ssl_verify
description
If the SSL certificate will be verified when querying the Chef Server API. This configuration can be provided to override the built-in Sensu Enterprise chef integration ssl_verify configuration for the client.
required
false
type
Boolean
default
true
example
"ssl_verify": false
proxy_address
description
The HTTP proxy address. This configuration can be provided to override the built-in Sensu Enterprise chef integration proxy_address configuration for the client.
required
false
type
String
example
"proxy_address": "proxy.example.com"
proxy_port
description
The HTTP proxy port (if there is a proxy). This configuration can be provided to override the built-in Sensu Enterprise chef integration proxy_port configuration for the client.
required
false
type
Integer
example
"proxy_port": 8080
proxy_username
description
The HTTP proxy username (if there is a proxy). This configuration can be provided to override the built-in Sensu Enterprise chef integration proxy_username configuration for the client.
required
false
type
String
example
"proxy_username": "chef"
proxy_password
description
The HTTP proxy user password (if there is a proxy). This configuration can be provided to override the built-in Sensu Enterprise chef integration proxy_password configuration for the client.
required
false
type
String
example
"proxy_password": "secret"
timeout
description
The handler execution duration timeout in seconds (hard stop). This configuration can be provided to override the built-in Sensu Enterprise chef integration timeout configuration for the client.
required
false
type
Integer
default
10
example
"timeout": 30

puppet attributes

The following attributes are configured within the { "client": { "puppet": {} } } configuration scope.

ENTERPRISE: This configuration is provided for using the built-in Sensu Enterprise Puppet integration.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "puppet": {
      "node_name": "webserver01"
    }
  }
}
ATTRIBUTES
node_name
description
The Puppet node name (if different than the client definition name attribute), used to lookup node data in PuppetDB.
required
false
type
String
default
defaults to the value of the client definition name attribute.
example
"node_name": "webserver01"

servicenow attributes

The following attributes are configured within the { "client": { "servicenow": {} } } configuration scope.

ENTERPRISE: this configuration is provided for using the built-in Sensu Enterprise ServiceNow integration.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "servicenow": {
      "configuration_item": {
        "name": "webserver01"
      }
    }
  }
}
ATTRIBUTES
configuration_item
description
The ServiceNow Configuration Item definition scope used to configure the ServiceNow CMDB Configuration Item for the client.
required
false
type
Hash
example
"configuration_item": {
  "name": "webserver01"
}

configuration_item attributes

The following attributes are configured within the { "client": { "servicenow": { "configuration_item": {} } } } configuration scope.

EXAMPLE
{
  "client": {
    "name": "1-424242",
    "...": "...",
    "servicenow": {
      "configuration_item": {
        "name": "webserver01",
        "os_version": "14.04"
      }
    }
  }
}

PRO TIP: ServiceNow users may provide custom Configuration Item (CI) field values via the configuration_item configuration scope. In this example, the CI field os_version is being set to 14.04.

ATTRIBUTES
name
description
The ServiceNow Configuration Item name to be used for the system.
required
false
type
String
default
defaults to the value of the client definition name attribute.
example
"name": "webserver01.example.com"

Custom attributes

Because Sensu configuration is just JSON data, it is possible to define configuration attributes that are not part of the Sensu client specification. Custom client definition attributes may be defined to provide context about the Sensu client and the services that run on its system. Custom client attributes will be included in client keepalives, and event data and can be used by Sensu filters (e.g. only alert on events in the “production” environment), and accessed via check token substitution.

EXAMPLE

The following is an example Sensu client definition that has custom attributes for the environment it is running in, a mysql attribute containing information about a local database, and a link to an operational playbook.

{
  "client": {
    "name": "i-424242",
    "address": "10.0.2.101",
    "environment": "production",
    "subscriptions": [
      "production",
      "webserver",
      "mysql"
    ],
    "mysql": {
      "host": "10.0.2.101",
      "port": 3306,
      "user": "app",
      "password": "secret"
    },
    "playbook": "https://wiki.example.com/ops/mysql-playbook"
  }
}

NOTE: Because client data is included in alerts created by Sensu, custom attributes that only exist for the purpose of providing troubleshooting information for operations teams can be extremely valuable.

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.