Improve PagerDuty notification doc (#11147)
Co-authored-by: ilyam8 <ilya@netdata.cloud>
Joel Hans committed
Dec 22, 2021 at 11:13 UTC
21e5a546c8a164a2688aff85d99ef2d0cf2cad9c
1 file changed
+44
-27
health/notifications/pagerduty/README.md
+44
-27
@@ -1,46 +1,63 @@
1
<!--
2
-title: "PagerDuty"
2
+title: "Send alert notifications to PagerDuty"
3
+description: "Send alerts to your PagerDuty dashboard any time an anomaly or performance issue strikes a node in your infrastructure."
4
+sidebar_label: "PagerDuty"
5
custom_edit_url: https://github.com/netdata/netdata/edit/master/health/notifications/pagerduty/README.md
6
-->
7
6
-# PagerDuty
8
+# Send alert notifications to PagerDuty
9
8
-[PagerDuty](https://www.pagerduty.com/company/) is the enterprise incident resolution service that integrates with ITOps and DevOps monitoring stacks to improve operational reliability and agility. From enriching and aggregating events to correlating them into incidents, PagerDuty streamlines the incident management process by reducing alert noise and resolution times.
10
+[PagerDuty](https://www.pagerduty.com/company/) is an enterprise incident resolution service that integrates with ITOps
11
+and DevOps monitoring stacks to improve operational reliability and agility. From enriching and aggregating events to
12
+correlating them into incidents, PagerDuty streamlines the incident management process by reducing alert noise and
13
+resolution times.
14
10
-Here is an example of a PagerDuty dashboard with Netdata notifications:
15
+## What you need to get started
16
12
-
17
+- An installation of the open-source [Netdata](/docs/get-started.mdx) monitoring agent.
18
+- An installation of the [PagerDuty agent](https://www.pagerduty.com/docs/guides/agent-install-guide/) on the node
19
+ running Netdata.
20
+- A PagerDuty `Generic API` service using either the `Events API v2` or `Events API v1`.
21
14
-To have Netdata send notifications to PagerDuty, you'll first need to set up a PagerDuty `Generic API` service and install the PagerDuty agent on the host running Netdata. See the following guide for details:
22
+## Setup
23
16
-<https://www.pagerduty.com/docs/guides/agent-install-guide/>
24
+[Add a new service](https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations)
25
+to PagerDuty. Click **Use our API directly** and select either `Events API v2` or `Events API v1`. Once you finish
26
+creating the service, click on the **Integrations** tab to find your **Integration Key**.
27
18
-During the setup of the `Generic API` PagerDuty service, you'll obtain a `pagerduty service key`. Keep this **service key** handy.
19
-
20
-Once the PagerDuty agent is installed on your host and can send notifications from your host to your `Generic API` service on PagerDuty, add the **service key** to `DEFAULT_RECIPIENT_PD` in `health_alarm_notify.conf`:
28
+Navigate to the [Netdata config directory](/docs/configure/nodes.md#the-netdata-config-directory) and use
29
+[`edit-config`](/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) to open
30
+`health_alarm_notify.conf`.
31
32
+```bash
33
+cd /etc/netdata
34
+sudo ./edit-config health_alarm_notify.conf
35
```
23
-#------------------------------------------------------------------------------
24
-# pagerduty.com notification options
25
-#
26
-# pagerduty.com notifications require the pagerduty agent to be installed and
27
-# a "Generic API" pagerduty service.
28
-# https://www.pagerduty.com/docs/guides/agent-install-guide/
36
30
-# multiple recipients can be given like this:
31
-# "<pd_service_key_1> <pd_service_key_2> ..."
37
+Scroll down to the `# pagerduty.com notification options` section.
38
+
39
+Ensure `SEND_PD` is set to `YES`, then copy your Integration Key into `DEFAULT_RECIPIENT_ID`. Change `USE_PD_VERSION` to
40
+`2` if you chose `Events API v2` during service setup on PagerDuty. Minus comments, the section should look like this:
41
33
-# enable/disable sending pagerduty notifications
42
+```conf
43
SEND_PD="YES"
44
+DEFAULT_RECIPIENT_PD="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
45
+USE_PD_VERSION="2"
46
+```
47
36
-# if a role's recipients are not configured, a notification will be sent to
37
-# the "General API" pagerduty.com service that uses this service key.
38
-# (empty = do not send a notification for unconfigured roles):
39
-DEFAULT_RECIPIENT_PD="<service key>"
48
+## Testing
49
41
-# Which PD API are we going to use? For version 2 or newer, it is necessary to do a request for Pagerduty
42
-# before to set the version(https://developer.pagerduty.com/docs/events-api-v2/overview/).
43
-USE_PD_VERSION="1"
50
+To test alert notifications to PagerDuty, run the following:
51
+
52
+```bash
53
+sudo su -s /bin/bash netdata
54
+/usr/libexec/netdata/plugins.d/alarm-notify.sh test
55
```
56
46
-[](<>)
57
+## Configuration
58
+
59
+Aside from the three values set in `health_alarm_notify.conf`, there is no further configuration required to send alert
60
+notifications to PagerDuty.
61
+
62
+To configure individual alarms, read our [alert configuration](/docs/monitor/configure-alarms.md) doc or
63
+the [health entity reference](/health/REFERENCE.md) doc.