---
title: MQTT event handler
list_title: MQTT
description: >
  The MQTT event handler allows you to send Kapacitor alert messages to an MQTT handler. This page includes configuration options and usage examples.
menu:
  kapacitor_v1:
    name: MQTT
    weight: 800
    parent: Event handlers
aliases:
  - /kapacitor/v1/event_handlers/mqtt/
---

[MQTT](http://mqtt.org/) is a lightweight messaging protocol for small sensors and mobile devices.
Kapacitor can be configured to send alert messages to an MQTT broker.

## Configuration
Configuration as well as default [option](#options) values for the MQTT
event handler are set in your `kapacitor.conf`.
Below is an example configuration:

```toml
[[mqtt]]
  enabled = true
  name = "localhost"
  default = true
  url = "tcp://localhost:1883"
  ssl-ca = "/etc/kapacitor/ca.pem"
  ssl-cert = "/etc/kapacitor/cert.pem"
  ssl-key = "/etc/kapacitor/key.pem"
  client-id = "xxxx"
  username = "xxxx"
  password = "xxxx"
```

> Multiple MQTT brokers may be configured by repeating `[[mqtt]]` sections.
> The `name` acts as a unique identifier for each configured MQTT client.

#### `enabled`
Set to `true` to enable the MQTT event handler.

#### `name`
Unique name for this broker configuration.

#### `default`
When using multiple MQTT configurations, sets the current configuration as
the default.

#### `url`
URL of the MQTT broker.
Possible protocols include:

**tcp** - Raw TCP network connection  
**ssl** - TLS protected TCP network connection  
**ws** - Websocket network connection  

#### `ssl-ca`
Absolute path to certificate authority (CA) file.
_A CA can be provided without a key/certificate pair._

#### `ssl-cert`
Absolute path to pem encoded certificate file.

#### `ssl-key`
Absolute path to pem encoded key file.

#### `client-id`
Unique ID for this MQTT client.
If empty, the value of `name` is used.

#### `username`
MQTT username.

#### `password`
MQTT password.


## Options
The following MQTT event handler options can be set in a
[handler file](/kapacitor/v1/reference/event_handlers/#create-a-topic-handler-with-a-handler-file) or when using
`.mqtt()` in a TICKscript.

| Name        | Type   | Description                                                                                                                  |
| ----        | ----   | -----------                                                                                                                  |
| broker-name | string | The name of the configured MQTT broker to use when publishing the alert. If empty defaults to the configured default broker. |
|	topic       | string | The MQTT topic to which alerts will be dispatched                                                                            |
| qos         | int64  | The [QoS](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718099) that will be used to deliver the alerts. Valid values include: <br><br><code>0</code> : At most once delivery<br><code>1</code> : At least once delivery<br><code>2</code> : Exactly once delivery |
|	retained    | bool   | Indicates whether this alert should be delivered to clients that were not connected to the broker at the time of the alert.  |

### Example: handler file
```yaml
id: handler-id
topic: topic-name
kind: mqtt
options:
  broker-name: 'name'
  topic: 'topic-name'
  qos: 1
  retained: true
```

### Example: TICKscript
```js
|alert()
  // ...
  .mqtt('topic-name')
    .brokerName('name')
    .qos(1)
    .retained(TRUE)
```

## Using the MQTT event handler
The MQTT event handler can be used in both TICKscripts and handler files to send
alerts to an MQTT broker.

The examples below use the following MQTT broker configurations defined in the
`kapacitor.conf`:

_**MQTT settings in kapacitor.conf**_
```toml
[[mqtt]]
  enabled = true
  name = "localhost"
  default = true
  url = "tcp://localhost:1883"

[[mqtt]]
  enabled = true
  name = "alerts-broker"
  default = false
  url = "ssl://123.45.67.89:1883"
  ssl-ca = "/etc/kapacitor/ca.pem"
  ssl-cert = "/etc/kapacitor/cert.pem"
  ssl-key = "/etc/kapacitor/key.pem"
  client-id = "alerts-broker"
  username = "myuser"
  password = "mysupersecretpassw0rd"
```

### Send alerts to an MQTT broker from a TICKscript

The following TICKscript uses the `.mqtt()` event handler to send alerts to the
`alerts` MQTT topic of the default MQTT broker defined in the `kapacitor.confi`
whenever idle CPU usage drops below 10%.

_**log-cpu-alert.tick**_  
```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('{{ .Time }}: CPU usage over 90%')
    .mqtt('alerts')
      .qos(2)
```

### Send alerts to an MQTT broker from a defined handler

The following setup sends an alert to the `cpu` topic.
An MQTT handler is added that subscribes to the `cpu` topic and sends messages
to `alerts` MQTT topic of the `alerts-broker` whenever a new message is published.

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**_
```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('{{ .Time }}: CPU usage over 90%')
    .topic('cpu')
```

Add and enable the TICKscript:

```bash
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 MQTT event
handler to send alerts to the `alerts-broker`.

_**log\_cpu\_handler.yaml**_
```yaml
id: log-cpu-alert
topic: cpu
kind: mqtt
options:
  broker-name: 'alerts-broker'
  topic: 'alerts'
  qos: 2
  retained: true
```

Add the handler:

```bash
kapacitor define-topic-handler log_cpu_handler.yaml
```