[APM] docs: Add alerting examples for APM

docs/apm/apm-alerts.asciidoc

@@ -0,0 +1,97 @@
+[role="xpack"]
+[[apm-alerts]]
+=== Create an alert
+
+beta::[]
+
+The APM app is integrated with Kibana's {kibana-ref}/alerting-getting-started.html[alerting and actions] feature.
+It provides a set of built-in **actions** and APM specific threshold **alerts** for you to use,
+and allows all alerts to be centrally managed from <<management,Kibana Management>>.
+
+[role="screenshot"]
+image::apm/images/apm-alert.png[Create an alert in the APM app]
+
+There are two different types of threshold alerts: transaction duration, and error rate.
+Below, we'll create one of each.
+
+[float]
+[[apm-create-transaction-alert]]
+=== Create a transaction duration alert
+
+This guide creates an alert for the `opbeans-java` service based on the following criteria:
+
+* Transaction type: `transaction.type:request`
+* Average request is above `1500ms` for the last 5 minutes
+* Check every 10 minutes, and repeat the alert every 30 minutes
+* Send the alert via Slack
+
+From the APM app, navigate to the `opbeans-java` service and select
+**Alerts** > **Create threshold alert** > **Transaction duration**.
+
+The name of your alert will automatically be set as `Transaction duration | opbeans-java`,
+and the alert will be tagged with `apm` and `service.name:opbeans-java`.
+Feel free to edit either of these defaults.
+
+Based on the alert criteria, define the following alert details:
+
+* **Check every** - `10 minutes`
+* **Notify every** - `30 minutes`
+* **TYPE** - `request`
+* **WHEN** - `avg`
+* **IS ABOVE** - `1500ms`
+* **FOR THE LAST** - `5 minutes`
+
+Select an action type.
+Multiple action types can be selected, but in this example we want to post to a slack channel.
+Select **Slack** > **Create a connector**.
+Enter a name for the connector,
+and paste the webhook URL.
+See Slack's webhook documentation if you need to create one.
+
+Select **Save**. The alert has been created and is now active!
+
+[float]
+[[apm-create-error-alert]]
+=== Create an error rate alert
+
+This guide creates an alert for the `opbeans-python` service based on the following criteria:
+
+* Error rate is above 25 for the last minute
+* Check every 1 minute, and repeat the alert every 10 minutes
+* Send the alert via email to the `opbeans-python` team
+
+From the APM app, navigate to the `opbeans-python` service and select
+**Alerts** > **Create threshold alert** > **Error rate**.
+
+The name of your alert will automatically be set as `Error rate | opbeans-python`,
+and the alert will be tagged with `apm` and `service.name:opbeans-python`.
+Feel free to edit either of these defaults.
+
+Based on the alert criteria, define the following alert details:
+
+* **Check every** - `1 minute`
+* **Notify every** - `10 minutes`
+* **IS ABOVE** - `25 errors`
+* **FOR THE LAST** - `1 minute`
+
+Select the **Email** action type and click **Create a connector**.
+Fill out the required details: sender, host, port, etc., and click **save**.
+
+Select **Save**. The alert has been created and is now active!
+
+[float]
+[[apm-alert-manage]]
+=== Manage alerts and actions
+
+From the APM app, select **Alerts** > **View active alerts** to be taken to the Kibana alerts and actions management page.
+From this page, you can create, edit, disable, mute, and delete alerts, and create, edit, and disable connectors.
+
+[float]
+[[apm-alert-more-info]]
+=== More information
+
+See {kibana-ref}/alerting-getting-started.html[alerting and actions] for more information.
+
+NOTE: If you are using an **on-premise** Elastic Stack deployment with security,
+TLS must be configured for communication between Elasticsearch and Kibana.
+More information is in the alerting {kibana-ref}/alerting-getting-started.html#alerting-setup-prerequisites[prerequisites].

docs/apm/using-the-apm-ui.asciidoc

@@ -15,6 +15,7 @@ APM is available via the navigation sidebar in {Kib}.
 * <<spans>>
 * <<errors>>
 * <<metrics>>
+* <<apm-alerts>>
 * <<machine-learning-integration>>
 * <<agent-configuration>>
 * <<advanced-queries>>
@@ -35,6 +36,8 @@ include::errors.asciidoc[]
 
 include::metrics.asciidoc[]
 
+include::apm-alerts.asciidoc[]
+
 include::agent-configuration.asciidoc[]
 
 include::custom-links.asciidoc[]