Populate metrics in InfluxDB with handlers

A Sensu event handler is an action the Sensu backend executes when a specific event occurs. In this guide, you’ll use a handler to populate the time series database InfluxDB. If you’re not familiar with handlers, consider reading the handlers reference before continuing through this guide.

The example in this guide explains how to populate Sensu metrics into the time series database InfluxDB. Metrics can be collected from check output or the Sensu StatsD Server.

Register the asset

Assets are shareable, reusable packages that make it easier to deploy Sensu plugins. This example uses the Sensu InfluxDB Handler asset to power an influx-db handler.

Use sensuctl asset add to register the Sensu InfluxDB Handler asset:

sensuctl asset add sensu/sensu-influxdb-handler:3.1.2 -r influxdb-handler

This example uses the -r (rename) flag to specify a shorter name for the asset: influxdb-handler.

You can also download the latest asset definition for your platform from Bonsai and register the asset with sensuctl create --file filename.yml or sensuctl create --file filename.json.

Run sensuctl asset list --format yaml or sensuctl asset list --format json to confirm that the asset is ready to use.

NOTE: Sensu does not download and install asset builds onto the system until they are needed for command execution. Read the asset reference for more information about builds.

Create the handler

Now that you have registered the asset, you’ll use sensuctl to create a handler called influx-db that pipes event data to InfluxDB with the sensu-influxdb-handler asset. Edit the command below to include your database name, address, username, and password. For more information about the Sensu InfluxDB handler, see the asset page in Bonsai.

sensuctl handler create influx-db \
--type pipe \
--command "sensu-influxdb-handler -d sensu" \
--env-vars "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086, INFLUXDB_USER=sensu, INFLUXDB_PASS=password" \
--runtime-assets influxdb-handler

You should see a confirmation message from sensuctl:


You can also create the handler definition in your monitoring-as-code repository:

type: Handler
api_version: core/v2
  created_by: admin
  name: influx-db
  namespace: default
  command: sensu-influxdb-handler -d sensu
  - INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086
  - INFLUXDB_PASS=password
  filters: null
  handlers: null
  - influxdb-handler
  secrets: null
  timeout: 0
  type: pipe
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "created_by": "admin",
    "name": "influx-db",
    "namespace": "default"
  "spec": {
    "command": "sensu-influxdb-handler -d sensu",
    "env_vars": [
    "filters": null,
    "handlers": null,
    "runtime_assets": [
    "secrets": null,
    "timeout": 0,
    "type": "pipe"

Assign the handler to an event

With the influx-db handler created, you can assign it to a check for check output metric extraction. For example, suppose you followed Collect service metrics with Sensu checks to create the check named collect-metrics.

Update the output metric format and output metric handlers to use the check with InfluxDB:

sensuctl check set-output-metric-format collect-metrics influxdb_line
sensuctl check set-output-metric-handlers collect-metrics influx-db

You can also assign the handler to the Sensu StatsD listener at agent startup to pass all StatsD metrics into InfluxDB:

sensu-agent start --statsd-event-handlers influx-db

Next steps

Now that you know how to apply a handler to metrics and take action on events, here are a few other recommended resources: