* Renaming alerts to rules * Updating formatted messages * Updating i18n labels * Completed renaming in UI * Updating client routes including redirect * wip docs update * Reverting title changes for now * Fixing types check * Fixing unit tests * Fixing functional test * Fixing functional test * docs wip * wip docs update * Finished first run through docs * docs docs docs * Fixing bad merge * Fixing functional test * Docs cleanup * Cleaning up i18n labels * Fixing functional test * Updating screenshots * Updating screenshots * Updating screenshots * Updating terminology in alerting examples * Updating terminology in alerting examples Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
136 lines
7.1 KiB
Plaintext
136 lines
7.1 KiB
Plaintext
[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].
|