---
title: PagerDuty v1 event handler
list_title: PagerDuty v1
description: >
  The PagerDuty v1 event handler allows you to send Kapacitor alerts to PagerDuty. This page includes configuration options and usage examples.
---

[PagerDuty](https://www.pagerduty.com/) is an incident management platform that
helps teams detect and fix infrastructure problems quickly.
Kapacitor can be configured to send alert messages to PagerDuty.

{{% warn %}}
This page is specific to PagerDuty's v1 API which has been deprecated.
PagerDuty recommends migrating to their v2 API. View the
[PagerDuty API migration guide](https://v2.developer.pagerduty.com/docs/migrating-to-api-v2)
for more information about upgrading. If using the v2 API, view the
[PagerDuty v2 event handler](/kapacitor/v1/reference/event_handlers/pagerduty/v2) documentation.
{{% /warn %}}

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

```toml
[pagerduty]
  enabled = true
  service-key = ""
  url = "https://events.pagerduty.com/generic/2010-04-15/create_event.json"
  global = false
```

#### `enabled`
Set to `true` to enable the PagerDuty v1 event handler.

#### `service-key`
Your [PagerDuty Service Key](https://support.pagerduty.com/docs/services-and-integrations).

#### `url`
The PagerDuty API v1 URL. _**This should not need to be changed.**_

#### `global`
If `true`, all alerts will be sent to PagerDuty without explicitly specifying
PagerDuty in TICKscripts.


## Options
The following PagerDuty v1 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
`.pagerDuty()` in a TICKscript.

| Name        | Type   | Description                                     |
| ----        | ----   | -----------                                     |
| service-key | string | The PagerDuty service key to use for the alert. |

### Example: handler file
```yaml
id: handler-id
topic: topic-name
kind: pagerduty
options:
  service-key: 'myservicekey'
```

### Example: TICKscript
```js
|alert()
  // ...
  .pagerDuty()
    .serviceKey('myservicekey')
```

## PagerDuty Setup
To allow Kapacitor to send alerts to PagerDuty
[enable a new "Generic API" integration](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-generic-events-api-integration).
Use the generated "Integration Key" as the `service-key` under the `[pagerduty]`
section of your `kapacitor.conf`.

##  Using the PagerDuty v1 Event Handler
With the PagerDuty v1 event handler enabled in your `kapacitor.conf`, use the
`.pagerDuty()` attribute in your TICKscripts to send alerts to a PagerDuty or
define a PagerDuty v1 handler that subscribes to a topic and sends published
alerts to PagerDuty.

The examples below use the following PagerDuty v1 configuration defined in the `kapacitor.conf`:

_**PagerDuty v1 settings in kapacitor.conf**_  
```toml
[pagerduty]
  enabled = true
  service-key = "myservicekey"
  url = "https://events.pagerduty.com/generic/2010-04-15/create_event.json"
  global = false
```

### Send alerts to PagerDuty from a TICKscript

The following TICKscript uses the `.pagerDuty()` event handler to send the
message, "Hey, check your CPU", whenever idle CPU usage drops below 10%.

_**pagerduty-cpu-alert.tick**_  
```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('Hey, check your CPU')
    .pagerDuty()
```

### Send alerts to PagerDuty from a defined handler

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

Create a TICKscript that publishes alert messages to a topic.
The TICKscript below sends an alert message to the `cpu` topic any time CPU
idle usage drops below 10% _(or CPU usage is above 90%)_.

_**cpu\_alert.tick**_
```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .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 PagerDuty
v1 event handler to send alerts to PagerDuty.

_**pagerduty\_cpu\_handler.yaml**_
```yaml
topic: cpu
id: pagerduty-cpu-alert
kind: pagerduty
options:
  service-key: 'myservicekey'
```

Add the handler:

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