Sensu agent

The Sensu agent is a lightweight client that runs on the infrastructure components you want to monitor. Agents register with the Sensu backend as monitoring entities with type: "agent". Agent entities are responsible for creating check and metrics events to send to the backend event pipeline. The Sensu agent is available for Linux, macOS, and Windows. See the installation guide to install the agent.

Communication between 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. By default this communication is via clear text. The backend and agent can be configured for WebSocket Secure (wss) encrypted communication by following our Securing Sensu guide.

Creating monitoring events using service checks

Sensu’s use of the publish/subscribe pattern of communication allows for automated registration and deregistration of ephemeral systems. At the core of this model are Sensu agent subscriptions.

Each Sensu agent has a defined set of subscriptions, a list of roles and responsibilities assigned to the system (for example: a webserver or database). These subscriptions determine which monitoring checks are executed by the agent. 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 order for an agent to execute a service check, you must specify the same subscription in the agent configuration and the check definition.

After receiving a check request from the Sensu backend, the agent:

  1. Applies any tokens matching attribute values in the check definition.
  2. Fetches assets and stores them in its local cache. By default, agents cache asset data at /var/cache/sensu/sensu-agent (C:\ProgramData\sensu\cache\sensu-agent on Windows systems) or as specified by the the cache-dir flag.
  3. Executes the check command.
  4. Executes any hooks specified by the check based on the exit status.
  5. Creates an event containing information about the applicable entity, check, and metric.

Subscription configuration

To configure subscriptions for an agent, set the subscriptions flag. To configure subscriptions for a check, set the check definition attribute subscriptions.

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

Proxy entities

Sensu proxy entities allow Sensu to monitor external resources on systems or devices where a Sensu agent cannot be installed (such a network switch). Unlike agent entities, proxy entity definitions are stored by the Sensu backend. When the backend requests a check that includes a proxy_entity_name, the agent includes the provided entity information in the event data in place of the agent entity data. See the entity reference and the guide to monitoring external resources for more information about monitoring proxy entities.

Creating monitoring events using the agent API

The Sensu agent API allows external sources to send monitoring data to Sensu without needing to know anything about Sensu’s internal implementation. The agent API listens on the address and port specified by the API configuration flags; only unsecured HTTP (no HTTPS) is supported at this time. Any requests for unknown endpoints result in a 404 Not Found response.

/events (POST)

The /events API provides HTTP POST access to publish monitoring events to the Sensu backend pipeline via the agent API. The agent places events created via the /events POST endpoint into a queue stored on disk. In the event of a loss of connection with the backend or agent shutdown, queued event data is preserved, and the agent sends queued events to the backend once a connection is reestablished.

The /events API uses a configurable burst limit and rate limit for relaying events to the backend. See the API configuration flags to configure the events-burst-limit and events-rate-limit flags.

Example

In the following example, an HTTP POST is submitted to the /events API, creating an event for a check named check-mysql-status with the output could not connect to mysql and a status of 1 (warning). The agent responds with a 202 (Accepted) response code to indicate that the event has been added to the queue to be sent to the backend.

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "check": {
    "metadata": {
      "name": "check-mysql-status"
    },
    "status": 1,
    "output": "could not connect to mysql"
  }
}' \
http://127.0.0.1:3031/events

HTTP/1.1 202 Accepted

PRO TIP: You can use the agent API /events endpoint to create proxy entities by including a proxy_entity_name attribute within the check scope.

Detecting silent failures

You can use the Sensu agent API in combination with the check time-to-live attribute (TTL) to detect silent failures, creating what’s commonly referred to as a “dead man’s switch” (source: Wikipedia). By using check TTLs, Sensu is able to set an expectation that a Sensu agent will publish additional events for a check within the period of time specified by the TTL attribute. If a Sensu agent fails to publish an event before the check TTL expires, the Sensu backend creates an event with a status of 1 (warning) to indicate the expected event was not received. For more information on check TTLs, see the the check reference.

A great use case for the Sensu agent API is to enable tasks which run outside of Sensu’s check scheduling to emit events. Using the check TTL attribute, these events create a dead man’s switch, ensuring that if the task fails for any reason, the lack of an “all clear” event from the task notifies operators of a silent failure which might otherwise be missed. If an external source sends a Sensu event with a check TTL to the Sensu agent API, Sensu expects another event from the same external source before the TTL expires.

The following is an example of external event input via the Sensu agent API using a check TTL to create a dead man’s switch for MySQL backups. If we assume that a MySQL backup script runs periodically and that we expect the job to take a little less than 7 hours to complete, in the case where the job completes successfully, we’d like a record of it but don’t need to be alerted. If the job fails for some reason, or continues running past the expected 7 hours, we’d like to be alerted. In the following example, the script sends an event which tells the Sensu backend to expect an additional event with the same name within 7 hours of the first event.

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "check": {
    "metadata": {
      "name": "mysql-backup-job"
    },
    "status": 0,
    "output": "mysql backup initiated",
    "ttl": 25200
  }
}' \
http://127.0.0.1:3031/events

With this initial event submitted to the agent API, we have recorded in the Sensu backend that our script started, and we’ve configured the dead man’s switch so that we’ll be alerted if the job fails or runs too long. Although it is possible for our script to handle errors gracefully and emit additional monitoring events, this approach allows us to worry less about handling every possible error case, as the lack of additional events before the 7 hour period elapses results in an alert.

If our backup script runs successfully, we can send an additional event without the TTL attribute, which removes the dead man’s switch:

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "check": {
    "metadata": {
      "name": "mysql-backup-job"
    },
    "status": 0,
    "output": "mysql backup ran successfully!"
  }
}' \
http://127.0.0.1:3031/events

By omitting the TTL attribute from this event, the dead man’s switch being monitored by the Sensu backend is also removed, effectively sounding the “all clear” for this iteration of the task.

API specification

/events (POST)
description Accepts JSON event data and passes the event to the Sensu backend event pipeline for processing
example url http://hostname:3031/events
payload example
{
  "check": {
    "metadata": {
      "name": "check-mysql-status"
    },
    "status": 1,
    "output": "could not connect to mysql"
  }
}
payload attributes
  • check (required): All check data must be within the check scope.
  • metadata (required): The check scope must contain a metadata scope.
  • name (required): The metadata scope must contain the name attribute with a string representing the name of the monitoring check.
  • Any other attributes supported by the Sensu check specification (optional)
response codes
  • Success: 202 (Accepted)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

/healthz (GET)

The /healthz API provides HTTP GET access to the status of the Sensu agent via the agent API.

Example

In the following example, an HTTP GET is submitted to the /healthz API:

curl http://127.0.0.1:3031/healthz

Resulting in a healthy response:

ok

API specification

/healthz (GET)
description Returns ok if the agent is active and connected to a Sensu backend; returns sensu backend unavailable if the agent is unable to connect to a backend.
example url http://hostname:3031/healthz

Creating monitoring events using the StatsD listener

Sensu agents include a listener to send StatsD metrics to the event pipeline. By default, Sensu agents listen on UDP socket 8125 (TCP on Windows systems) for messages that follow the StatsD line protocol and send metric events for handling by the Sensu backend.

For example, you can use the Netcat utility to send metrics to the StatsD listener:

echo 'abc.def.g:10|c' | nc -w1 -u localhost 8125

Metrics received through the StatsD listener are not stored by Sensu, so it’s important to configure event handlers.

StatsD line protocol

The Sensu StatsD listener accepts messages formatted according to the StatsD line protocol:

<metricname>:<value>|<type>

For more information, see the StatsD documentation.

Configuring the StatsD listener

To configure the StatsD listener, specify the statsd-event-handlers configuration flag in the agent configuration, and start the agent.

# Start an agent that sends StatsD metrics to InfluxDB
sensu-agent --statsd-event-handlers influx-db

You can use the StatsD configuration flags to change the default settings for the StatsD listener address, port, and flush interval.

# Start an agent with a customized address and flush interval
sensu-agent --statsd-event-handlers influx-db --statsd-flush-interval 1 --statsd-metrics-host 123.4.5.11 --statsd-metrics-port 8125

Creating monitoring events using the agent TCP and UDP sockets

NOTE: The agent TCP and UDP sockets are deprecated in favor of the agent API.

Sensu agents listen for external monitoring data using TCP and UDP sockets. The agent sockets accept JSON event data and pass the event to the Sensu backend event pipeline for processing. The TCP and UDP sockets listen on the address and port specified by the socket configuration flags.

Using the TCP socket

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

echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' > /dev/tcp/localhost/3030

You can also use the Netcat utility to send monitoring data to the agent socket:

echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' | nc localhost 3030

Using the UDP socket

The following is an example demonstrating external monitoring data input via the Sensu agent UDP socket. The example uses Bash’s built-in /dev/udp file to communicate with the Sensu agent socket.

echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' > /dev/udp/127.0.0.1/3030

You can also use the Netcat utility to send monitoring data to the agent socket:

echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' | nc -u -v 127.0.0.1 3030

Socket event format

The agent TCP and UDP sockets use a special event data format designed for backwards compatibility with Sensu 1.x check results. Attributes specified in socket events appear in the resulting event data passed to the Sensu backend.

Example socket input: Minimum required attributes

{
  "name": "check-mysql-status",
  "status": 1,
  "output": "error!"
}

Example socket input: All attributes

{
  "name": "check-http",
  "status": 1,
  "output": "404",
  "source": "sensu-docs-site",
  "executed": 1550013435,
  "duration": 1.903135228,
  "handlers": ["slack", "influxdb"]
}

Socket event specification

The Sensu agent socket ignores any attributes not included in this specification.

name
description The check name
required true
type String
example
"name": "check-mysql-status"
status
description The check execution exit status code. An exit status code of 0 (zero) indicates OK, 1 indicates WARNING, and 2 indicates CRITICAL; exit status codes other than 0, 1, or 2 indicate an UNKNOWN or custom status.
required true
type Integer
example
"status": 0
output
description The output produced by the check command.
required true
type String
example
"output": "CheckHttp OK: 200, 78572 bytes"
source
description The name of the Sensu entity associated with the event. Use this attribute to tie the event to a proxy entity. If no matching entity exists, Sensu creates a proxy entity with the name provided by the source attribute.
required false
default The agent entity receiving the event data
type String
example
"source": "sensu-docs-site"
client
description NOTE: The client attribute is deprecated in favor of the source attribute (see above). The name of the Sensu entity associated with the event. Use this attribute to tie the event to a proxy entity. If no matching entity exists, Sensu creates a proxy entity with the name provided by the client attribute.
required false
default The agent entity receiving the event data
type String
example
"client": "sensu-docs-site"
executed
description The time the check was executed, in seconds since the Unix epoch.
required false
default The time the event was received by the agent
type Integer
example
"executed": 1458934742
duration
description The amount of time (in seconds) it took to execute the check.
required false
type Float
example
"duration": 1.903135228
command
description The command executed to produce the event. You can use this attribute to add context to the event data; Sensu does not execute the command included in this attribute.
required false
type String
example
"command": "check-http.rb -u https://sensuapp.org"
interval
description The interval used to produce the event. You can use this attribute to add context to the event data; Sensu does not act on the value provided in this attribute.
required false
default 1
type Integer
example
"interval": 60
handlers
description An array of Sensu handler names to use for handling the event. Each handler name in the array must be a string.
required false
type Array
example
"handlers": ["slack", "influxdb"]

Keepalive monitoring

Sensu keepalives are the heartbeat mechanism used to ensure that all registered agents are operational and able to reach the Sensu backend. Sensu agents publish keepalive events containing entity configuration data to the Sensu backend according to the interval specified by the keepalive-interval flag. If a Sensu agent fails to send keepalive events over the period specified by the keepalive-timeout flag, the Sensu backend creates a keepalive alert in the Sensu dashboard. You can use keepalives to identify unhealthy systems and network partitions, send notifications, trigger auto-remediation, and other useful actions.

NOTE: Keepalive monitoring is not supported for proxy entities, as they are inherently unable to run a Sensu agent.

Handling keepalive events

You can connect keepalive events to your monitoring workflows using a keepalive handler. Sensu looks for an event handler named keepalive and automatically uses it to process keepalive events.

Let’s say you want to receive Slack notifications for keepalive alerts, and you already have a Slack handler set up to process events. To process keepalive events using the Slack pipeline, create a handler set named keepalive and add the slack handler to the handlers array. The resulting keepalive handler set configuration looks like this:

type: Handler
api_version: core/v2
metadata:
  name: keepalive
  namespace: default
spec:
  handlers:
  - slack
  type: set
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata" : {
    "name": "keepalive",
    "namespace": "default"
  },
  "spec": {
    "type": "set",
    "handlers": [
      "slack"
    ]
  }
}

Operation

Starting the service

Use the sensu-agent tool to start the agent and apply configuration flags.

Linux

To start the agent with configuration flags:

sensu-agent start --subscriptions disk-checks --log-level debug

To see available configuration flags and defaults:

sensu-agent start --help

To start the agent using a service manager:

sudo service sensu-agent start

If no configuration flags are provided, the agent loads configuration from the location specified by the config-file attribute (default: /etc/sensu/agent.yml).

Windows

Run the following command as an admin to install and start the agent.

sensu-agent service install

By default, the agent loads configuration from %ALLUSERSPROFILE%\sensu\config\agent.yml (for example: C:\ProgramData\sensu\config\agent.yml) and stores service logs to %ALLUSERSPROFILE%\sensu\log\sensu-agent.log (for example: C:\ProgramData\sensu\log\sensu-agent.log).

You can configure the configuration file and log file locations using the config-file and log-file flags.

sensu-agent service install --config-file 'C:\\monitoring\\sensu\\config\\agent.yml' --log-file 'C:\\monitoring\\sensu\\log\\sensu-agent.log'

Stopping the service

To stop the agent service using a service manager:

Linux

sudo service sensu-agent stop

Windows

sc.exe stop SensuAgent

Restarting the service

You must restart the agent to implement any configuration updates.

To restart the agent using a service manager:

Linux

sudo service sensu-agent restart

Windows

sc.exe stop SensuAgent
sc.exe start SensuAgent

Enabling on boot

To enable the agent to start on system boot:

Linux

sudo systemctl enable sensu-agent

To disable the agent from starting on system boot:

sudo systemctl disable sensu-agent

NOTE: On older distributions of Linux, use sudo chkconfig sensu-server on to enable the agent and sudo chkconfig sensu-server off to disable.

Windows

The service is configured to start automatically on boot by default.

Getting service status

To see the status of the agent service using a service manager:

Linux

service sensu-agent status

Windows

sc.exe query SensuAgent

Getting service version

To get the current agent version using the sensu-agent tool:

sensu-agent version

Uninstalling the service

Windows

sensu-agent service uninstall

Getting help

The sensu-agent tool provides general and command-specific help flags:

# Show sensu-agent commands
sensu-agent help

# Show options for the sensu-agent start subcommand
sensu-agent start --help

Clustering

Agents can connect to a Sensu cluster by specifying any Sensu backend URL in the cluster in the backend-url configuration flag. For more information about clustering, see Sensu backend datastore configuration flags and the guide to running a Sensu cluster.

Time synchronization

System clocks between agents and the backend should be synchronized to a central NTP server. Out of sync system time may cause issues with keepalive, metric, and check alerts.

Registration

In practice, agent registration happens when a Sensu backend processes an agent keepalive event for an agent that is not already registered in the Sensu agent registry (based on the configured agent name). This agent registry is stored in the Sensu backend, and is accessible via sensuctl entity list.

All Sensu agent data provided in keepalive events gets stored in the agent registry and used to add context to Sensu events and detect Sensu agents in an unhealthy state.

Registration events

If a Sensu event handler named registration is configured, the Sensu backend creates and process an event for agent registration, applying any configured filters and mutators before executing the configured handler.

PRO TIP: Use a handler set to execute multiple handlers in response to registration events.

Registration events are useful for executing one-time handlers for new Sensu agents. For example, registration event handlers can be used to update external configuration management databases (CMDBs) such as ServiceNow.

To configure a registration event handler, please refer to the Sensu event handler documentation for instructions on creating a handler named registration.

WARNING: Registration events are not stored in the event registry, so they are not accessible via the Sensu API; however, all registration events are logged in the Sensu backend log.

Deregistration events

Similarly to registration events, the Sensu backend can create and process a deregistration event when the Sensu agent process stops. You can use deregistration events to trigger a handler that updates external CMDBs or performs an action to update ephemeral infrastructures. To enable deregistration events, use the deregister flag and specify the event handler using the deregistration-handler flag. You can specify a deregistration handler per agent using the deregistration-handler agent flag or by setting a default for all agents using the deregistration-handler backend configuration flag.

Configuration

The agent loads configuration upon startup, so you must restart the agent for any configuration updates to take effect.

Linux

You can specify the agent configuration using a .yml file or using sensu-agent start command-line flags. Configuration provided via command-line flags overrides attributes specified in a configuration file. See the example config file for flags and defaults.

Configuration summary

$ sensu-agent start --help
start the sensu agent

Usage:
  sensu-agent start [flags]

Flags:
      --allow-list string               path to agent execution allow list configuration file
      --annotations stringToString      entity annotations map (default [])
      --api-host string                 address to bind the Sensu client HTTP API to (default "127.0.0.1")
      --api-port int                    port the Sensu client HTTP API listens on (default 3031)
      --backend-url strings             ws/wss URL of Sensu backend server (to specify multiple backends use this flag multiple times) (default [ws://127.0.0.1:8081])
      --cache-dir string                path to store cached data (default "/var/cache/sensu/sensu-agent")
  -c, --config-file string              path to sensu-agent config file
      --deregister                      ephemeral agent
      --deregistration-handler string   deregistration handler that should process the entity deregistration event.
      --disable-assets                  disable check assets on this agent
      --disable-api                     disable the Agent HTTP API
      --disable-sockets                 disable the Agent TCP and UDP event sockets
      --events-burst-limit              /events api burst limit
      --events-rate-limit               maximum number of events transmitted to the backend through the /events api
  -h, --help                            help for start
      --insecure-skip-tls-verify        skip ssl verification
      --keepalive-interval int          number of seconds to send between keepalive events (default 20)
      --keepalive-timeout uint32        number of seconds until agent is considered dead by backend (default 120)
      --labels stringToString           entity labels map (default [])
      --log-level string                logging level [panic, fatal, error, warn, info, debug] (default "warn")
      --name string                     agent name (defaults to hostname) (default "sensu-go-sandbox")
      --namespace string                agent namespace (default "default")
      --password string                 agent password (default "P@ssw0rd!")
      --redact string                   comma-delimited customized list of fields to redact
      --socket-host string              address to bind the Sensu client socket to (default "127.0.0.1")
      --socket-port int                 port the Sensu client socket listens on (default 3030)
      --statsd-disable                  disables the statsd listener and metrics server
      --statsd-event-handlers strings   comma-delimited list of event handlers for statsd metrics
      --statsd-flush-interval int       number of seconds between statsd flush (default 10)
      --statsd-metrics-host string      address used for the statsd metrics server (default "127.0.0.1")
      --statsd-metrics-port int         port used for the statsd metrics server (default 8125)
      --subscriptions string            comma-delimited list of agent subscriptions
      --trusted-ca-file string          tls certificate authority
      --user string                     agent user (default "agent")

Windows

You can specify the agent configuration using a .yml file. See the example config file provided with Sensu packages at %ALLUSERSPROFILE%\sensu\config\agent.yml.example (default: C:\ProgramData\sensu\config\agent.yml.example) or available here.

General configuration flags

annotations
description Non-identifying metadata to include with event data, which can be accessed using filters and tokens. You can use annotations to add data that’s meaningful to people or external tools interacting with Sensu.

In contrast to labels, annotations cannot be used in API filtering or sensuctl filtering and do not impact Sensu’s internal performance.
required false
type Map of key-value pairs. Keys and values can be any valid UTF-8 string.
default null
example
# Command line examples
sensu-agent start --annotations sensu.io/plugins/slack/config/webhook-url=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
sensu-agent start --annotations example-key="example value" --annotations example-key2="example value"

# /etc/sensu/agent.yml example
annotations:
  sensu.io/plugins/slack/config/webhook-url: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
backend-url
description ws or wss URL of the Sensu backend server. To specify multiple backends using sensu-agent start, use this flag multiple times.
type List
default ws://127.0.0.1:8081
example
# Command line examples
sensu-agent start --backend-url ws://0.0.0.0:8081
sensu-agent start --backend-url ws://0.0.0.0:8081 --backend-url ws://0.0.0.0:8082

# /etc/sensu/agent.yml example
backend-url:
  - "ws://0.0.0.0:8081"
  - "ws://0.0.0.0:8082"
  

cache-dir
description Path to store cached data
type String
default
  • Linux: /var/cache/sensu/sensu-agent
  • Windows: C:\ProgramData\sensu\cache\sensu-agent
example
# Command line example
sensu-agent start --cache-dir /cache/sensu-agent

# /etc/sensu/agent.yml example
cache-dir: "/cache/sensu-agent"
config-file
description Path to Sensu agent config file
type String
default
  • Linux: /etc/sensu/agent.yml
  • FreeBSD: /usr/local/etc/sensu/agent.yml
  • Windows: C:\ProgramData\sensu\config\agent.yml
example
# Command line example
sensu-agent start --config-file /sensu/agent.yml
sensu-agent start -c /sensu/agent.yml

# /etc/sensu/agent.yml example
config-file: "/sensu/agent.yml"

disable-assets
description When set to true, disables assets for the agent. In the event that an agent attempts to execute a check that requires an asset, the agent will respond with a status of 3, and a message indicating that the agent could not execute the check because assets are disabled.
type Boolean
default false
example
# Command line example
sensu-agent start --disable-assets

# /etc/sensu/agent.yml example
disable-assets: true

allow-list
description Path to yaml or json file containing allowlist of check or hook commands the agent can execute. See the example configuration file and the configuration spec for details on building a configuration file.
type String
default ""
example
# Command line example
sensu-agent start --allow-list /etc/sensu/check-allow-list.yaml

# /etc/sensu/agent.yml example
allow-list: /etc/sensu/check-allow-list.yaml
labels
description Custom attributes to include with event data, which can be accessed using filters and tokens.

In contrast to annotations, you can use labels to create meaningful collections that can be selected with API filtering and sensuctl filtering. Overusing labels can impact Sensu’s internal performance, so we recommend moving complex, non-identifying metadata to annotations.
required false
type Map of key-value pairs. Keys can contain only letters, numbers, and underscores, but must start with a letter. Values can be any valid UTF-8 string.
default null
example
# Command line examples
sensu-agent start --labels proxy_type=website
sensu-agent start --labels example_key1="example value" example_key2="example value"

# /etc/sensu/agent.yml example
labels:
  proxy_type: "website"

name
description Entity name assigned to the agent entity
type String
default Defaults to hostname, for example: sensu-centos
example
# Command line example
sensu-agent start --name agent-01

# /etc/sensu/agent.yml example
name: "agent-01" 
log-level
description Logging level: panic, fatal, error, warn, info, or debug
type String
default warn
example
# Command line example
sensu-agent start --log-level debug

# /etc/sensu/agent.yml example
log-level: "debug"

subscriptions
description An array of agent subscriptions which determine which monitoring checks are executed by the agent. The subscriptions array items must be strings.
type List
example
# Command line examples
sensu-agent start --subscriptions disk-checks,process-checks
sensu-agent start --subscriptions disk-checks --subscriptions process-checks

# /etc/sensu/agent.yml example
subscriptions:
  - disk-checks
  - process-checks

API configuration flags

api-host
description Bind address for the Sensu agent HTTP API
type String
default 127.0.0.1
example
# Command line example
sensu-agent start --api-host 0.0.0.0

# /etc/sensu/agent.yml example
api-host: "0.0.0.0"
api-port
description Listening port for the Sensu agent HTTP API
type Integer
default 3031
example
# Command line example
sensu-agent start --api-port 4041

# /etc/sensu/agent.yml example
api-port: 4041
disable-api
description Disable the agent HTTP API
type Boolean
default false
example
# Command line example
sensu-agent start --disable-api

# /etc/sensu/agent.yml example
disable-api: true
events-burst-limit
description The maximum amount of burst allowed in a rate interval for the agent events API.
type Integer
default 10
example
# Command line example
sensu-agent start --events-burst-limit 20

# /etc/sensu/agent.yml example
events-burst-limit: 20
events-rate-limit
description The maximum number of events per second that can be transmitted to the backend using the agent events API
type Float
default 10.0
example
# Command line example
sensu-agent start --events-rate-limit 20.0

# /etc/sensu/agent.yml example
events-rate-limit: 20.0

Ephemeral agent configuration flags

deregister
description Indicates whether a deregistration event should be created upon Sensu agent process stop
type Boolean
default false
example
# Command line example
sensu-agent start --deregister

# /etc/sensu/agent.yml example
deregister: true
deregistration-handler
description The name of a deregistration handler that processes agent deregistration events. This flag overrides any handlers applied by the deregistration-handler backend configuration flag.
type String
example
# Command line example
sensu-agent start --deregistration-handler deregister

# /etc/sensu/agent.yml example
deregistration-handler: "deregister"

Keepalive configuration flags

keepalive-interval
description Number of seconds between keepalive events
type Integer
default 20
example
# Command line example
sensu-agent start --keepalive-interval 30

# /etc/sensu/agent.yml example
keepalive-interval: 30
keepalive-timeout
description Number of seconds after a missing keepalive event until the agent is considered unresponsive by the Sensu backend
type Integer
default 120
example
# Command line example
sensu-agent start --keepalive-timeout 300

# /etc/sensu/agent.yml example
keepalive-timeout: 300

Security configuration flags

namespace
description Agent namespace NOTE: Agents are represented in the backend as a class of entity. Entities can only belong to a single namespace.
type String
default default
example
# Command line example
sensu-agent start --namespace ops

# /etc/sensu/agent.yml example
namespace: "ops"
user
description Sensu RBAC username used by the agent. Agents require get, list, create, update, and delete permissions for events across all namespaces.
type String
default agent
example
# Command line example
sensu-agent start --user agent-01

# /etc/sensu/agent.yml example
user: "agent-01"
password
description Sensu RBAC password used by the agent
type String
default P@ssw0rd!
example
# Command line example
sensu-agent start --password secure-password

# /etc/sensu/agent.yml example
password: "secure-password"
redact
description List of fields to redact when displaying the entity NOTE: Redacted secrets are sent via the websocket connection and are stored in etcd. They are not logged nor displayed via the Sensu API.
type List
default By default, Sensu redacts the following fields: password, passwd, pass, api_key, api_token, access_key, secret_key, private_key, secret
example
# Command line example
sensu-agent start --redact secret,ec2_access_key

# /etc/sensu/agent.yml example
redact:
  - secret
  - ec2_access_key
trusted-ca-file
description SSL/TLS certificate authority
type String
default ""
example
# Command line example
sensu-agent start --trusted-ca-file /path/to/trusted-certificate-authorities.pem

# /etc/sensu/agent.yml example
trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"
insecure-skip-tls-verify
description Skip SSL verification. WARNING: This configuration flag is intended for use in development systems only. Do not use this flag in production.
type Boolean
default false
example
# Command line example
sensu-agent start --insecure-skip-tls-verify

# /etc/sensu/agent.yml example
insecure-skip-tls-verify: true

Socket configuration flags

socket-host
description Address to bind the Sensu agent socket to
type String
default 127.0.0.1
example
# Command line example
sensu-agent start --socket-host 0.0.0.0

# /etc/sensu/agent.yml example
socket-host: "0.0.0.0"
socket-port
description Port the Sensu agent socket listens on
type Integer
default 3030
example
# Command line example
sensu-agent start --socket-port 4030

# /etc/sensu/agent.yml example
socket-port: 4030
disable-sockets
description Disable the agent TCP and UDP event sockets
type Boolean
default false
example
# Command line example
sensu-agent start --disable-sockets

# /etc/sensu/agent.yml example
disable-sockets: true

StatsD configuration flags

statsd-disable
description Disables the StatsD listener and metrics server
type Boolean
default false
example
# Command line example
sensu-agent start --statsd-disable

# /etc/sensu/agent.yml example
statsd-disable: true
statsd-event-handlers
description List of event handlers for StatsD metrics
type List
example
# Command line examples
sensu-agent start --statsd-event-handlers influxdb,opentsdb
sensu-agent start --statsd-event-handlers influxdb --statsd-event-handlers opentsdb

# /etc/sensu/agent.yml example
statsd-event-handlers:
  - influxdb
  - opentsdb
statsd-flush-interval
description Number of seconds between StatsD flush
type Integer
default 10
example
# Command line example
sensu-agent start --statsd-flush-interval 30

# /etc/sensu/agent.yml example
statsd-flush-interval: 30
statsd-metrics-host
description Address used for the StatsD metrics server
type String
default 127.0.0.1
example
# Command line example
sensu-agent start --statsd-metrics-host 0.0.0.0

# /etc/sensu/agent.yml example
statsd-metrics-host: "0.0.0.0"
statsd-metrics-port
description Port used for the StatsD metrics server
type Integer
default 8125
example
# Command line example
sensu-agent start --statsd-metrics-port 6125

# /etc/sensu/agent.yml example
statsd-metrics-port: 6125

Allow list configuration

exec
description The command to allow the Sensu agent to run as a check or a hook.
required true
type String
example
"exec": "/usr/local/bin/check_memory.sh"
sha512
description The checksum of the check or hook executable.
required false
type String
example
"sha512": "4f926bf4328..."
args
description Arguments for the exec command.
required true
type Array
example
"args": ["foo"]
enable_env
description Enable environment variables.
required false
type Boolean
example
"enable_env": true

Example allow list configuration file

- exec: /usr/local/bin/check_memory.sh
  args:
  - ""
  sha512: 736ac120323772543fd3a08ee54afdd54d214e58c280707b63ce652424313ef9084ca5b247d226aa09be8f831034ff4991bfb95553291c8b3dc32cad034b4706
  enable_env: true
  foo: bar
- exec: /usr/local/bin/show_process_table.sh
  args:
  - ""
  sha512: 28d61f303136b16d20742268a896bde194cc99342e02cdffc1c2186f81c5adc53f8550635156bebeed7d87a0c19a7d4b7a690f1a337cc4737e240b62b827f78a
- exec: echo-asset.sh
  args:
  - "foo"
  sha512: cce3d16e5881ba829f271df778f9014f7c3659917f7acfd7a60a91bfcabb472eea72f9781194d310388ba046c21790364ad0308a5a897cde50022195ba90924b
[
  {
    "exec": "/usr/local/bin/check_memory.sh",
    "args": [
      ""
    ],
    "sha512": "736ac120323772543fd3a08ee54afdd54d214e58c280707b63ce652424313ef9084ca5b247d226aa09be8f831034ff4991bfb95553291c8b3dc32cad034b4706",
    "enable_env": true,
    "foo": "bar"
  },
  {
    "exec": "/usr/local/bin/show_process_table.sh",
    "args": [
      ""
    ],
    "sha512": "28d61f303136b16d20742268a896bde194cc99342e02cdffc1c2186f81c5adc53f8550635156bebeed7d87a0c19a7d4b7a690f1a337cc4737e240b62b827f78a"
  },
  {
    "exec": "echo-asset.sh",
    "args": [
      "foo"
    ],
    "sha512": "cce3d16e5881ba829f271df778f9014f7c3659917f7acfd7a60a91bfcabb472eea72f9781194d310388ba046c21790364ad0308a5a897cde50022195ba90924b"
  }
]