---
title: Zenoss event handler
description: The Zenoss event handler sends Kapacitor alerts to Zenoss. This page includes configuration options and usage examples.
url: https://docs.influxdata.com/kapacitor/v1/reference/event_handlers/zenoss/
estimated_tokens: 5845
product: Kapacitor
version: v1
---

# Zenoss event handler

[Zenoss](https://www.zenoss.com/) is a hybrid IT monitoring service for monitoring virtual and physical IT environments. Configure Kapacitor to send events to Zenoss.

## Configuration

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

```toml
[zenoss]
  enabled = true
  url = "https://tenant.zenoss.io:8080/zport/dmd/evconsole_router"
  username = ""
  password = ""
  action = "EventsRouter"
  method = "add_event"
  type = "rpc"
  tid = 1
  collector = "Kapacitor"
  severity-map = {OK = "Clear", Info = "Info", Warning = "Warning", Critical = "Critical"}
  global = false
  state-changes-only = false
```

#### enabled

Set to `true` to enable the Zenoss event handler.

#### url

Zenoss [router endpoint URL](https://help.zenoss.com/zsd/RM/configuring-resource-manager/enabling-access-to-browser-interfaces/creating-and-changing-public-endpoints). For example: `https://tenant.zenoss.io:8080/zport/dmd/evconsole_router`.

#### username

Zenoss username to use for HTTP BASIC authentication. For no authentication, set as an empty string (`""`).

#### password

Zenoss password to use for HTTP BASIC authentication. For no authentication, set as an empty string (`""`).

#### action

Zenoss [router name](https://help.zenoss.com/dev/collection-zone-and-resource-manager-apis/anatomy-of-an-api-request#AnatomyofanAPIrequest-RouterURL). For example: `"EventsRouter"`.

#### method

[EventsRouter method](https://help.zenoss.com/dev/collection-zone-and-resource-manager-apis/codebase/routers/router-reference/eventsrouter). For example: `"add_event"`.

#### type

Event type. For example: `"rpc"`.

#### tid

Temporary request transaction ID. For example: `1`.

#### collector

Zenoss [collector](https://help.zenoss.com/zsd/RM/administering-resource-manager/event-management/event-fields) name. For example: `"Kapacitor"`.

#### severity-map

Map Kapacitor alert levels to [Zenoss event severity levels](https://help.zenoss.com/zsd/RM/administering-resource-manager/event-management/event-severity-levels).

```toml
severity-map = { OK = "Clear", Info = "Info", Warning = "Warning", Critical = "Critical" }
```

#### global

If `true`, all alerts are sent to Zenoss without explicitly specifying Zenoss in the TICKscript.

#### state-changes-only

Set all alerts in state-changes-only mode, meaning alerts will only be sent if the alert state changes. *Only applies if `global` is `true`.*

## Options

The following Zenoss 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 `.zenoss()` in a TICKscript.

| Name | Type | Description |
| --- | --- | --- |
| action | string | Zenoss router name |
| method | string | Zenoss router method |
| type | string | Zenoss event type |
| tid | integer | Temporary request transaction ID |
| summary | string | Event summary |
| device | string | Device related to the event |
| component | string | Component related to the event |
| evclasskey | string | Zenoss event class key |
| evclass | string | Zenoss event class |
| collector | string | Zenoss collector |
| message | string | Event message |
| customField | map | Custom fields to append to event |

### Example: handler file

```yaml
id: handler-id
topic: topic-name
kind: zenoss
options:
  action: EventsRouter
  method: add_event
  type: rpc
  tid: 1
  summary: Example event summary.
  device: example-device
  component: example-component
  evclasskey: example-event-class-key
  evclass: example-event-class
  collector: Kapacitor
  message: Example event message.
  customField: 
    customField1: customValue1
    customField2: customValue2
```

### Example: TICKscript

```js
|alert()
  // ...
  .zenoss()
    .action('EventsRouter')
    .method('add_event')
    .type('rpc')
    .tid(1)
    .summary('Example event summary.')
    .device('example-device')
    .component('example-component')
    .evclasskey('example-event-class-key')
    .evclass('example-event-class')
    .collector('Kapacitor')
    .message('Example event message.')
    .customField('customField1', 'customValue1')
    .customField('customField2', 'customValue2')
```

To avoid posting a message every alert interval, use [AlertNode.StateChangesOnly](/kapacitor/v1/reference/nodes/alert_node/#statechangesonly) so only events where the alert changed state are sent to Zenoss.

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

##### Zenoss settings in kapacitor.conf

```toml
[zenoss]
  enabled = true
  url = "https://tenant.zenoss.io:8080/zport/dmd/evconsole_router"
  username = ""
  password = ""
  action = "EventsRouter"
  method = "add_event"
  type = "rpc"
  tid = 1
  collector = "Kapacitor"
  severity-map = {OK = "Clear", Info = "Info", Warning = "Warning", Critical = "Critical"}
  global = false
  state-changes-only = false
```

### Send alerts to Zenoss from a TICKscript

The following TICKscript uses the `.zenoss()` event handler to send the message, “Hey, check your CPU”, to the `#alerts` Zenoss channel whenever idle CPU usage drops below 20%.

##### zenoss-cpu-alert.tick

```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .warn(lambda: "usage_idle" < 20)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .zenoss()
```

### Send alerts to Zenoss from a defined handler

The following setup sends an alert to the `cpu` topic with the message, “Hey, check your CPU”. A Zenoss handler is added that subscribes to the `cpu` topic and publishes all alert messages to Zenoss.

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

##### cpu\_alert.tick

```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 5)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .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 Zenoss event handler to send alerts to Zenoss.

##### zenoss\_cpu\_handler.yaml

```yaml
id: zenoss-cpu-alert
topic: cpu
kind: zenoss
options:
  summary: High CPU usage
  device: example-device
  component: example-component
  evclasskey: example-event-class-key
  evclass: example-event-class
```

Add the handler:

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