Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name

v0.2.0 · public · Published over 3 years ago

Asset Definition
Release Notes
Release Assets

Sensu Bonsai Asset

Sensu AWS Timestream Handler

Table of Contents


The Sensu AWS Timestream Handler is a Sensu Handler that sends metrics to
the AWS Timestream time series database service.

Enterprise plugin

The Sensu AWS Timestream Handler is a Sensu plugin that requires a valid Sensu
license to run. Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE
environment variable to the handler execution. To run the plugin independently
of Sensu (e.g. test/dev), you must set the environment variable:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)


Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not
using an asset, please consider doing so! If you're using sensuctl 5.13 with
Sensu Backend 5.13 or later, you can use the following command to add the asset:

sensuctl asset add nixwiz/sensu-aws-timestream-handler

If you're using an earlier version of sensuctl, you can find the asset on the
Bonsai Asset Index.

Handler definition

type: Handler
api_version: core/v2
  name: sensu-aws-timestream-handler
  namespace: default
  command: sensu-aws-timestream-handler --database sensu --table sensu_metrics
  type: pipe
  - nixwiz/sensu-aws-timestream-handler
  - has_metrics

Proxy Support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is

AWS credentials

This plugin makes use of the AWS SDK for Go. The SDK uses the
default credential provider chain to find AWS credentials. The SDK uses
the first provider in the chain that returns credentials without an error.
The default provider chain looks for credentials in the following order:

  1. Environment variables (AWS_SECRET_ACCESS_KEY, AWS_ACCESS_KEY_ID, and AWS_REGION).

  2. Shared credentials file (typically ~/.aws/credentials).

  3. If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2.

  4. If your application uses an ECS task definition or RunTask API operation, IAM role for tasks.

The SDK detects and uses the built-in providers automatically, without
requiring manual configurations. For example, if you use IAM roles for Amazon
EC2 instances, your applications automatically use the instance’s credentials.
You don’t need to manually configure credentials in your application.

Source: Configuring the AWS SDK for Go

This plugin also supports assuming a new role upon authentication using the --aws-assume-role-arn

If you go the route of using environment variables, it is highly suggested you
use them via the Env secrets provider.

Usage examples


Sensu AWS Timestream Handler

  sensu-aws-timestream-handler [flags]
  sensu-aws-timestream-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

  -d, --database string          Timestream Database to use
  -t, --table string             Timestream Database Table to use
  -r, --region string            AWS Region for Timestream Database (default "us-east-1")
  -c, --check-labels             Include check labels in Timestream dimensions
  -m, --max-write-records int    The maximum number of records in a WriteRecords API request (default 100)
  -a, --assume-role-arn string   The IAM role to assume upon successful authentication
  -D, --debug                    Enable debug output
  -h, --help                     help for sensu-aws-timestream-handler

Use "sensu-aws-timestream-handler [command] --help" for more information about a command.

Environment variables

Most arguments for this handler are available to be set via environment
variables. However, any arguments specified directly on the command line
override the corresponding environment variable.

Argument Environment Variable
--region AWS_REGION


All arguments for this handler are tunable on a per entity or check basis based
on annotations. The annotations keyspace for this handler is


To change the table argument for a particular check, for that checks's
metadata add the following:

type: CheckConfig
api_version: core/v2
  annotations: "sensu_check_table"

AWS limits

AWS limits the number of records per WriteRecords API request. The
default limit is 100
. If you have requested an increase to this limit
you can provide your new limit as an argument to the --max-write-records


Dimensions for each metrics point are created from the following:

  • Each tag defined for the metrics point.
  • Check labels, depending on the --check-labels argument. The default
    is to not include check labels.

If no dimensions are defined from the above, a default dimension named
entity_name is created using the entity name.


  1. Dimension names are limited to alphanumeric (a-z, A-Z, 0-9) and the
    underscore (_) characters. Any metrics point tag or label names, if included,
    that contain characters outside of that scope will not be used a dimensions
    and will be silently dropped (unless debugging output is enabled with --debug).
    Dimension values have no such restriction.
  2. To use entity labels, reference them via the output_metric_tags
    attribute in the check.

Installation from source

The preferred way of installing and deploying this plugin is to use it as an
Asset. If you would like to compile and install the plugin from source or
contribute to it, download the latest version or create an executable from this

From the local path of the sensu-aws-timestream-handler repository:

go build


For more information about contributing to this plugin, see Contributing.

Are you sure you want to report this asset?

Please describe the reason for reporting this asset. Our moderators will be notified and will disable the asset if it is found to be inappropriate.


You must be signed in to report this asset.

Sign In with Github



This asset is enterprise only and requires an enterprise license. By clicking download, you agree to the Sensu terms and conditions and license agreement.

Scanning your asset...