Skip to content

Commit

Permalink
PR fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@ymao1
ymao1 committed Mar 1, 2021
1 parent 0987b59 commit 167cc52
Showing 1 changed file with 48 additions and 92 deletions.
140 changes: 48 additions & 92 deletions docs/user/alerting/action-types/pagerduty.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,46 +7,66 @@

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

* <<pagerduty-benefits, PagerDuty and Elastic integration benefits>>
* <<pagerduty-connector-configuration, Connector configuration>>
* <<pagerduty-action-configuration, Action configuration>>

[float]
[[pagerduty-benefits]]
==== PagerDuty + Elastic integration benefits
[[pagerduty-connector-configuration]]
==== Connector configuration

By integrating PagerDuty with alerts, you can:
PagerDuty connectors have the following configuration properties.

* Route your alerts 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 alert’s context.
* Tailor the incident data to match your needs by easily passing the alerting context from Kibana to PagerDuty.
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]
[[pagerduty-how-it-works]]
===== How it works
[[Preconfigured-pagerduty-configuration]]
==== Preconfigured action type

{kib} allows you to create alerts to notify you of a significant move
in your dataset.
You can create alerts for all your Observability, Security, and Elastic Stack use cases.
Alerts will trigger a new incident on the corresponding PagerDuty service.
[source,text]
--
my-pagerduty:
name: preconfigured-pagerduty-action-type
actionTypeId: .pagerduty
config:
apiUrl: https://test.host
secrets:
routingKey: testroutingkey
--

Config defines information for the action type.

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

Secrets defines sensitive information for the action type.

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

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

In the `kibana.yml` configuration file, you must add the <<general-alert-action-settings, saved objects encryption setting>>.
This is required to encrypt parameters that must be secured, for example PagerDuty’s integration key.
PagerDuty actions have the following properties.

If you have security enabled:
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`.

* You must have
application privileges to access Metrics, APM, Uptime, or Security.
* If you are using a self-managed deployment with security, you must have
Transport Security Layer (TLS) enabled for communication <<configuring-tls-kib-es, between Elasticsearch and Kibana>>.
Alerts uses API keys to secure background alert checks and actions,
and API keys require {ref}/configuring-tls.html#tls-http[TLS on the HTTP interface].
For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters].

Although not a requirement, to harden the integrations security you might want to
review the <<action-settings, Actions settings>> that are available to you.
[float]
[[pagerduty-benefits]]
==== Configure PagerDuty

By integrating PagerDuty with alerts, you can:

* Route your alerts 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 alert’s context.
* Tailor the incident data to match your needs by easily passing the alerting context from Kibana to PagerDuty.

[float]
[[pagerduty-support]]
Expand Down Expand Up @@ -114,67 +134,3 @@ To see the available context variables, click on the *Add alert variable* icon n
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].


[float]
[[pagerduty-uninstall]]
===== How to uninstall
To remove a PagerDuty connector from an alert, simply remove it
from the *Actions* section of that alert, using the remove (x) icon.
This will disable the integration for the particular alert.

To delete the connector entirely, open the main menu, then click *Stack Management > Alerts and Actions*.
Select the *Connectors* tab, and then click on the delete icon.
This is an irreversible action and impacts all alerts that use this connector.


[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 action type

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

Config defines information for the action type.

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

Secrets defines sensitive information for the action 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].

0 comments on commit 167cc52

Please sign in to comment.