[DOCS] Alerting PagerDuty benefits

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

@@ -4,19 +4,152 @@
 
 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 and Elastic integration benefits
+
+By integrating PagerDuty with Elastic Alerts, you can:
+
+* Route your Elastic 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-how-it-works]]
+=== How it works
+
+{kib} allows you to create threshold alerts of a generic type that you can use for all your indices.
+You can also create specific alerts for Observability and SIEM.
+Create an alert to be notified of a significant move in your datasets. Elastic Alerts will generate PagerDuty incidents.
+
+. To connect your {kib} alerts to PagerDuty incidents, create a PagerDuty Connector in Kibana.  You can:
++
+* Create a connector as part of creating an alert by selecting PagerDuty in the *Actions*
+section of the alert configuration and selecting *Add new*.
+* Alternatively, create a connector by navigating to Management from the {kib} navbar and selecting
+*Alerts and Actions*. Then select the *Connectors* tab, click on the *Create connector* button, and select the PagerDuty option.
+
+. Enter a name for the connector, the API URL, and the Routing Key.
++
+* See <<pagerduty-integration-walkthrough, Integration walkthrough>> for how to obtain
+the endpoint and key information from PagerDuty.
+* See <<pagerduty-connector-configuration, Connector configuration>> for additional details.
+
+. Save the Connector and reuse it in your alerts, as needed in the alerts’ *Actions* section.
+
+. Finalize your alert definition by selecting the PagerDuty Connector that you have created
+and by determining the value of the incident parameters according to your needs.
+Kibana is very flexible on how you can do this and allows you to determine these
+values dynamically through alert context parameters.
+See <<pagerduty-connector-configuration, Action configuration>> for more details.
+
+[float]
+=== Requirements
+
+* In the kibana.yml configuration file, add the saved objects encryption setting.
+This is required to encrypt parameters the must be secured, for example, PagerDuty’s integration key.
+
+* If you have security enabled:
+** To access the Elastic Alerting functionality, you need
+application privileges to access Metrics, APM, Uptime, or SIEM.
+** If you are using a self-managed deployment with security, you need
+Transport Security Layer (TLS) enabled for communication between Elasticsearch and Kibana.
+Elastic Alerts uses API keys to secure background alert checks and actions,
+and API keys require TLS on the HTTP interface.
+
+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-support]]
+=== Support
+If you need help with this integration, get in touch with the Kibana team:
+* Visit https://support.elastic.co[support.elastic.co] or use
+the *Ask Elastic* option in the Kibana Help menu.
+* Select the Kibana option at https://discuss.elastic.co/[discuss.elastic.co].
+
+[float]
+[[pagerduty-integration-walkthrough]]
+=== Integration with PagerDuty walkthrough
+
+[float]
+[[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 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 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.
+
+[float]
+[[pagerduty-in-elastic]]
+===== In Elastic
+
+. Create a PagerDuty Connector as described in <<pagerduty-how-it-works, How it works>>.
+
+. Configure the connector by giving it a name and entering the API URL and Routing Key.
++
+*See <<pagerduty-in-pagerduty, In PagerDuty>> for how to obtain the endpoint and key information from PagerDuty and
+<<pagerduty-connector-configuration, Connector configuration>> for additional details.
+
+. 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.
+Depending on your custom needs, assign them variables from the alerting context.
+To see the available context variables, click on the *Add alert 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].
+
+[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, go to the Management menu, select *Alerts and Actions*,
+select the *Connectors* tab, and click on the delete icon.
+This is an irreversible action and impacts all alerts that use this connector.
+
+
 [float]
 [[pagerduty-connector-configuration]]
-==== 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.whitelistedHosts`>> setting, make sure the hostname is whitelisted. 
+API URL::   An optional PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure the hostname is whitelisted.
 Routing Key::   A 32 character PagerDuty Integration Key for an integration on a service or on a global ruleset.
 
 [float]
 [[pagerduty-action-configuration]]
-==== Action configuration
+=== Action configuration
 
 PagerDuty actions have the following properties:
 
@@ -26,8 +159,8 @@ Dedup Key::     All actions sharing this key will be associated with the same Pa
 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. 
+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].
+For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters].