Documentation

Alerta event handler

Alerta is a monitoring tool used to consolidate and deduplicate alerts from multiple sources for quick ‘at-a-glance’ visualization. Kapacitor can be configured to send alert messages to Alerta.

Configuration

Configuration as well as default option values for the Alerta event handler are set in your kapacitor.conf. Below is an example configuration:

[alerta]
  enabled = true
  url = "http://127.0.0.1"
  token = "mysupersecretauthtoken"
  environment = "production"
  origin = "kapacitor"

enabled

Set to true to enable the Alerta event handler.

url

The Alerta URL.

token

Default Alerta authentication token.

token-prefix

Default token prefix. If you receive invalid token errors, you may need to change this to “Key”.

environment

Default Alerta environment.

origin

Default origin of alert.

correlate

When an alert with the same resource is received with an event in the correlate list of related events, the alert is correlated. For more information, see Alerta documentation.

Options

The following Alerta event handler options can be set in a handler file or when using .alerta() in a TICKscript.

* Required

NameTypeDescription
tokenstringAlerta authentication token. If empty uses the token from the configuration.
token-prefixstringAlerta authentication token prefix. If empty, uses “Bearer”.
resource*stringAlerta resource. Can be a template and has access to the same data as the AlertNode.Details property. Default: {{ .Name }}
event*stringAlerta event. Can be a template and has access to the same data as the idInfo property. Default: {{ .ID }}.
environmentstringAlerta environment. Can be a template and has access to the same data as the AlertNode.Details property. Default is set from the configuration.
groupstringAlerta group. Can be a template and has access to the same data as the AlertNode.Details property. Default: {{ .Group }}.
valuestringAlerta value. Can be a template and has access to the same data as the AlertNode.Details property. Default is an empty string.
originstringAlerta origin. If empty uses the origin from the configuration.
correlatelist of stringsList of related events, for example, event1, event2.
servicelist of stringsList of effected Services.
timeoutduration stringAlerta timeout. Default is 24 hours.
attributesmap of key value pairsAlerta alert attributes.

Note: The resource and event properties are required. Alerta cannot be configured globally because of these required properties.

Example: handler file

topic: topic-name
id: handler-id
kind: alerta
options:
  token: 'mysupersecretauthtoken'
  token-prefix: 'Bearer'
  resource: '{{ .Name }}'
  event: '{{ .ID }}'
  environment: 'Production'
  group: '{{ .Group }}'
  value: 'some-value'
  origin: 'kapacitor'
  correlate: 'event1', 'event2'
  service: ['service1', 'service2']
  correlate: ['service1', 'service2']
  timeout: 24h
  attributes:
    key1: value1
    key2: 8
    booleanAttribute: TRUE

Example: TICKscript

|alert()
  // ...
  .stateChangesOnly()
  .alerta()
    .token('mysupersecretauthtoken')
    .tokenPrefix('Bearer')
    .resource('{{ .Name }}')
    .event('{{ .ID }}')
    .environment('Production')
    .group('{{ .Group }}')
    .value('some-value')
    .origin('kapacitor')
    .correlate('event1', 'event2')
    .service('service1', 'service2')
    .correlated('service1', 'service2')
    .timeout(24h)
    .attribute('booleanAttribute', TRUE)
    .attribute('key1', 'value1')

Using the Alerta event handler

With the Alerta event handler enabled and configured in your kapacitor.conf, use the .alerta() attribute in your TICKscripts to send alerts to Alerta or define an Alerta handler that subscribes to a topic and sends published alerts to Alerta.

To avoid posting a message every alert interval, use AlertNode.StateChangesOnly so only events where the alert changed state are sent to Alerta.

The examples below use the following Alerta configuration defined in the kapacitor.conf:

Alerta settings in kapacitor.conf

[alerta]
  enabled = true
  url = "http://127.0.0.1"
  token = "mysupersecretauthtoken"
  environment = "production"
  origin = "kapacitor"

Send alerts to an Alerta room from a TICKscript

The following TICKscript sends the message, “Hey, check your CPU”, to Alerta whenever idle CPU usage drops below 10% using the .alerta() event handler and default Alerta settings defined in the kapacitor.conf.

alerta-cpu-alert.tick

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .alerta()
      .resource('{{ .Name }}')
      .event('{{ .ID }}')
      .correlated('{{ .Name }}')

Send alerts to an Alerta room from a defined handler

The following setup sends an alert to the cpu topic with the message, “Hey, check your CPU”. An Alerta handler is added that subscribes to the cpu topic and publishes all alert messages to Alerta using default settings defined in the kapacitor.conf.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an alert message to the cpu topic any time idle CPU usage drops below 10%.

cpu_alert.tick

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .topic('cpu')

Add and enable the TICKscript:

kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert

Create a handler file that subscribes to the cpu topic and uses the Alerta event handler to send alerts to the alerts channel in Alerta.

alerta_cpu_handler.yaml

id: alerta-cpu-alert
topic: cpu
kind: alerta
options:
  resource: '{{ .Name }}'
  event: '{{ .ID }}'
  origin: 'kapacitor'
  correlate: ['service1', 'service2']

Add the handler:

kapacitor define-topic-handler alerta_cpu_handler.yaml

Was this page helpful?

Thank you for your feedback!


Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

State of the InfluxDB Cloud Serverless documentation

InfluxDB Cloud Serverless documentation is a work in progress.

The new documentation for InfluxDB Cloud Serverless is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.