Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name

v0.0.9 · public · Published about 4 years ago

Asset Definition
Release Notes
Release Assets

Sensu Go Relay Handler

Bonsai Asset Badge Build Status

The Sensu Go Relay handler is a Sensu Event Handler that relays Events to another Sensu Go installation.

Relay Handler


The sensu-relay-handler is designed to allow users to forward events to an alternate sensu-go-backend instance. This can be used to forward events from one environment to a separate sensu-go-backend instance for event handling. The sensu-relay-handler does not relay back subscriptions and checks. As such, a sensu-go-backend is still required to manage the remote agents, subscriptions and checks.


The relay-agent is a sensu-go-agent that is local to your remote site network. It will send events to another site's sensu-go-backend. Events will be queued up as normal between an agent and backend.

Remote Site (Site 1)

The remote site should be configured as a standalone Sensu-Go installation. The agents will connect to their local sensu-backend. In order for a check's results to be forwarded to another sensu-backend it must have the sensu-relay-handler configured as one of its handlers. Agents do not require access to the relay agent, but the sensu-backend does require network access to the relay agent. The relay agent also requires a network connection to the sensu-backend you want to forward events to. This may be over a WAN connection, VPN tunnel, etc.

Local Site (Site 2)

The local sensu-backend needs to be made available to the relay agent. This may be achieved via a public internet connection, VPN or similar. No further configuration is required of the sensu-backend.


No extra configuration or checks are required to have a working relay handler and agent. However, it is recommended that you have checks in place to verify that the relay agent is available. This is especially recommended for instances where there may not be a reliable connection between the relay-agent and sensu-backend.

Relay Handler Configuration

Example Sensu Go handler definition:

api_version: core/v2
type: Handler
  namespace: default
  name: relay
  type: pipe
  - sensu-relay-handler
  command: sensu-relay-handler --api-url --disable-check-handling
  timeout: 30

Example Sensu Go check definition:


    "api_version": "core/v2",
    "type": "CheckConfig",
    "metadata": {
        "namespace": "default",
        "name": "dummy-app-healthz"
    "spec": {
        "command": "check-http -u http://localhost:8080/healthz",
        "publish": true,
        "interval": 10,
        "handlers": [


api_version: core/v2
type: CheckConfig
  namespace: default
  name: dummy-app-healthz
  command: check-http -u http://localhost:8080/healthz
  - dummy
  publish: true
  interval: 10
  - relay

Asset configuration

Asset registration

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

sensuctl asset add sensu/sensu-relay-handler

If you're using an earlier version of sensuctl, you can download the asset definition from this project's Bonsai Asset Index page.

Usage Examples

The Sensu Go handler for relaying Events to another Sensu Go installation

  sensu-relay-handler [flags]

  -a, --api-url string             The Sensu Go Agent Events API URL (default "")
  -c, --check-handlers string      The Sensu Go Event Handlers to set in relayed Check Events (replace)
  -d, --disable-check-handling     Disable Event Handling for relayed Check Events
  -D, --disable-metrics-handling   Disable Event Handling for relayed Metrics Events
  -h, --help                       help for sensu-relay-handler
  -m, --metrics-handlers string    The Sensu Go Event Handlers to set in relayed Metrics Events (replace)
  -p, --password string            The Sensu Go Events API user password
  -u, --username string            The Sensu Go Events API username

Installing from source and contributing

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 of the sensu-relay-handler from releases,
or create an executable script from this source.

From the local path of the relay-handler repository:

go build -o /usr/local/bin/sensu-relay-handler main.go

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.