kibana/docs/user/alerting/action-types/pagerduty.asciidoc

[role="xpack"]
[[pagerduty-action-type]]
=== PagerDuty connector and action
++++
<titleabbrev>PagerDuty</titleabbrev>
++++

The PagerDuty connector uses the https://v2.developer.pagerduty.com/docs/events-api-v2[v2 Events API] to trigger, acknowledge, and resolve PagerDuty alerts.

[float]
[[pagerduty-connector-configuration]]
==== Connector configuration

PagerDuty connectors have the following configuration properties.

Name::      The name of the connector. The name is used to identify a  connector in the management UI connector listing, or in the connector list when configuring an action.
API URL::   An optional PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
Integration Key::   A 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key.

[float]
[[Preconfigured-pagerduty-configuration]]
==== Preconfigured connector type

[source,text]
--
 my-pagerduty:
   name: preconfigured-pagerduty-connector-type
   actionTypeId: .pagerduty
   config:
     apiUrl: https://test.host
   secrets:
     routingKey: testroutingkey
--

Config defines information for the connector type.

`apiURL`:: A URL string that corresponds to *API URL*.

Secrets defines sensitive information for the connector type.

`routingKey`:: A string that corresponds to *Integration Key*.

[float]
[[pagerduty-action-configuration]]
==== Action configuration

PagerDuty actions have the following properties.

Severity::      The perceived severity of on the affected system. This can be one of `Critical`, `Error`, `Warning` or `Info`(default).
Event action::  One of `Trigger` (default), `Resolve`, or `Acknowledge`. See https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[event action] for more details.
Dedup Key::     All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. This value is *optional*, and if not set, defaults to `<alert ID>:<alert instance ID>`. The maximum length is *255* characters. See https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication[alert deduplication] for details. 
Timestamp::     An *optional* https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format date-time], indicating the time the event was detected or generated.
Component::     An *optional* value indicating the component of the source machine that is responsible for the event, for example `mysql` or `eth0`.
Group::         An *optional* value indicating the logical grouping of components of a service, for example `app-stack`.
Source::        An *optional* value indicating the affected system, preferably a hostname or fully qualified domain name. Defaults to the {kib} saved object id of the action.
Summary::       An *optional* text summary of the event, defaults to `No summary provided`. The maximum length is 1024 characters.
Class::         An *optional* value indicating the class/type of the event, for example `ping failure` or `cpu load`.

For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters].

[float]
[[pagerduty-benefits]]
==== Configure PagerDuty

By integrating PagerDuty with rules, you can:

* Route your rules to the right PagerDuty responder within your team, based on your structure, escalation policies, and workflows.
* Automatically generate incidents of different types and severity based on each rule’s context.
* Tailor the incident data to match your needs by easily passing the rule context from Kibana to PagerDuty.

[float]
[[pagerduty-support]]
===== Support
If you need help with this integration, get in touch with the {kib} team by visiting
https://support.elastic.co[support.elastic.co] or by using the *Ask Elastic* option in the {kib} Help menu.
You can also select the {kib} category at https://discuss.elastic.co/[discuss.elastic.co].

[float]
[[pagerduty-integration-walkthrough]]
===== Integration with PagerDuty walkthrough

[[pagerduty-in-pagerduty]]
*In PagerDuty*

. From the *Configuration* menu, select *Services*.
. Add an integration to a service:
+
* If you are adding your integration to an existing service,
click the name of the service you want to add the integration to.
Then, select the *Integrations* tab and click the *New Integration* button.
* If you are creating a new service for your integration,
go to
https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations[Configuring Services and Integrations]
and follow the steps outlined in the *Create a New Service* section, selecting *Elastic Alerts* as the *Integration Type* in step 4.
Continue with the <<pagerduty-in-elastic, In Elastic>> section once you have finished these steps.

. Enter an *Integration Name* in the format Elastic-service-name (for example, Elastic-Alerting or Kibana-APM-Alerting)
and select *Elastic Alerts* from the *Integration Type* menu.
. Click *Add Integration* to save your new integration.
+
You will be redirected to the *Integrations* tab for your service. An Integration Key is generated on this screen.
+
[role="screenshot"]
image::user/alerting/images/pagerduty-integration.png[PagerDuty Integrations tab]

. Save this key, as you will use it when you configure the integration with Elastic in the next section.

[[pagerduty-in-elastic]]
*In Elastic*

. Create a PagerDuty Connector in Kibana.  You can:
+
* Create a connector as part of creating an rule by selecting PagerDuty in the *Actions*
section of the rule configuration and selecting *Add new*.
* Alternatively, create a connector. To create a connector, open the main menu, click *Stack Management > Rules and Connectors*, select *Connectors*, click *Create connector*, then select the PagerDuty option.

. Configure the connector by giving it a name and entering the Integration Key, optionally entering a custom API URL.
+
See <<pagerduty-in-pagerduty, In PagerDuty>> for how to obtain the endpoint and key information from PagerDuty and
<<pagerduty-connector-configuration, Connector configuration>> for more details.

. Save the Connector.

. To create a rule, open the main menu, then click *Stack Management > Rules and Connectors* or the application of your choice.

. Set up an action using your PagerDuty connector, by determining:
+
* The action’s type: Trigger, Resolve, or Acknowledge.
* The event’s severity: Info, warning, error, or critical.
* An array of different fields, including the timestamp, group, class, component, and your dedup key. By default, the dedup is configured to create a new PagerDuty incident for each alert and reuse the incident when a recovered alert reactivates.
Depending on your custom needs, assign them variables from the rule context.
To see the available context variables, click on the *Add variable* icon next
to each corresponding field. For more details on these parameters, see the
<<pagerduty-action-configuration, Actions Configuration>> and the PagerDuty
https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[API v2 documentation].