Post event handler

The post event handler posts JSON encoded data to an HTTP endpoint.

Configuration

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

Post Settings in kapacitor.conf

[[httppost]]
  endpoint = "example"
  url = "http://example.com"
  headers = { Example = "your-key" }
  basic-auth = { username = "my-user", password = "my-pass" }
  alert-template = "{{.Message}}:{{range .Data.Series}}{{.Tags}},{{range .Values}}{{.}}{{end}}{{end}}"
  alert-template-file = "/path/to/template/file"
  row-template = "{{.Name}} host={{index .Tags \"host\"}}{{range .Values}} {{index . "time"}} {{index . "value"}}{{end}}"
  row-template-file = "/path/to/template/file"

endpoint

Name of a configured httppost endpoint. Can not be specified in the URL.

url

The URL to which the alert data will be posted.

headers

Set of extra header values to set on the POST request.

basic-auth

Set of authentication credentials to set on the POST request.

alert-template

Alert template for constructing a custom HTTP body. Alert templates are only used with post alert handlers as they consume alert data. Skip to alert templating.

alert-template-file

Absolute path to an alert template file. Skip to alert templating.

row-template

Row template for constructing a custom HTTP body. Row templates are only used with httpPost pipeline nodes as they consume a row at a time. Skip to row templating.

row-template-file

Absolute path to a row template file. Skip to row templating.

Defining configuration options with environment variables

The endpoint, url, and headers configuration options can be defined with environment variables:

KAPACITOR_HTTPPOST_0_ENDPOINT = "example"
KAPACITOR_HTTPPOST_0_URL = "http://example.com"
KAPACITOR_HTTPPOST_0_HEADERS_Example1 = "header1"
KAPACITOR_HTTPPOST_0_HEADERS_Example2 = "header2"

Options

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

Name Type Description
url string The URL to which the alert data will be posted.
endpoint string Name of a configured httppost endpoint to use, cannot be specified in the URL.
headers map of string to string Set of extra header values to set on the POST request.
capture-response bool If the HTTP status code is not an 2xx code, read and log the the HTTP response
timeout duration Timeout for the HTTP POST.

Example: handler file

id: handler-id
topic: topic-name
kind: post
options:
  url: http://example.com
  endpoint: example
  headers:
    'Example1': 'example1'
    'Example2': 'example2'
  capture-response: true
  timeout: 10s

Example: TICKscript

|alert()
  // ...
  .post()
    .url('http://example.com')
    .endpoint('example')
    .header('Example1', 'example1')
    .header('Example2', 'example2')
    .captureResponse()
    .timeout(10s)

Using the Post event handler

The post event handler can be used in both TICKscripts and handler files to post alert and httpPost data to an HTTP endpoint. The examples below deal with alerts and use the same httppost configuration defined in the kapacitor.conf:

httppost settings in kapacitor.conf

[[httppost]]
  endpoint = "api/alert"
  url = "http://mydomain.com"
  headers = { From = "alerts@mydomain.com" }
  alert-template = "{{.Message}}:{{range .Data.Series}}{{.Tags}},{{range .Values}}{{.}}{{end}}{{end}}"

Post alerts from a TICKscript

The following TICKscript uses the .post() event handler to post the message, “Hey, check your CPU”, whenever idle CPU usage drops below 10%.

post-cpu-alert.tick

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('Hey, check your CPU')
    .post()
      .url('http://mydomain.com')
      .endpoint('api/alerts')

Post alerts from a defined handler

The following setup sends an alert to the cpu topic with the message, “Hey, check your CPU”. A post handler is added that subscribes to the cpu topic and posts all alert messages to the url and endpoint 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)
    .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 post event handler to post alerts to an HTTP endpoint.

post_cpu_handler.yaml

id: post-cpu-alert
topic: cpu
kind: post
options:
  headers:
    'From': 'alert@mydomain.com'

Add the handler:

kapacitor define-topic-handler post_cpu_handler.yaml

Post templating

The post event handler allows you to customize the content and structure of POSTs with alert and row templates.

Alert templates

Alert templates are used to construct a custom HTTP body. They are only used with post alert handlers as they consume alert data. Templates are defined either inline in the kapacitor.conf using the alert-template configuration or in a separate file and referenced using the alert-template-file config.

Alert templates use Golang Template and have access to the following fields:

Field Description
.ID The unique ID for the alert.
.Message The message of the alert.
.Details The details of the alert.
.Time The time the alert event occurred.
.Duration The duration of the alert event.
.Level The level of the alert, i.e INFO, WARN, or CRITICAL.
.Data The data that triggered the alert.
.Recoverable Indicates whether or not the alert is auto-recoverable.

Inline alert template

kapacitor.conf

[httppost]]
  endpoint = "example"
  url = "http://example.com"
  alert-template = "{{.Message}}:{{range .Data.Series}}{{.Tags}},{{range .Values}}{{.}}{{end}}{{end}}"

Alert template file

kapacitor.conf

[httppost]]
  endpoint = "example"
  url = "http://example.com"
  alert-template-file = "/etc/templates/alert.html"

/etc/templates/alert.html

{{.Message}}:{{range .Data.Series}}{{.Tags}},{{range .Values}}{{.}}{{end}}{{end}}

Row templates

Row templates are used to construct a custom HTTP body. They are only used with post httpPost handlers as they consume a row at a time. Templates are defined either inline in the kapacitor.conf using the row-template configuration or in a separate file and referenced using the row-template-file config.

Row templates use Golang Template and have access to the following fields:

Field Description
.Name The measurement name of the data stream
.Tags A map of tags on the data.
.Values A list of values; each a map containing a “time” key for the time of the point and keys for all other fields on the point.

Inline row template

kapacitor.conf

[[httppost]]
  endpoint = "example"
  url = "http://example.com"
  row-template = '{{.Name}} host={{index .Tags "host"}}{{range .Values}} {{index . "time"}} {{index . "value"}}{{end}}'

Row template file

kapacitor.conf

[[httppost]]
  endpoint = "example"
  url = "http://example.com"
  row-template-file = "/etc/templates/row.html"

/etc/templates/row.html

{{.Name}} host={{index .Tags \"host\"}}{{range .Values}} {{index . "time"}} {{index . "value"}}{{end}}

This documentation is open source. See a typo? Please, open an issue.


Need help getting up and running? Get Support