Adds the instructions for a common use case -- to send an alert when a test fails

Author: ada

synthetics/test-config/synth-alerts.rst

@@ -11,32 +11,64 @@ In Splunk Observability Cloud, detectors monitor your tests and metrics for anom
 
 To learn more about advanced alerts and detectors in Splunk Observability Cloud, see :ref:`get-started-detectoralert`. Read on to learn about creating static threshold detectors specific to Synthetics. 
 
-Use cases for detectors in Synthetics
+Types of detectors in Synthetics
 =======================================
 
-You can use detectors to alert on metrics at the test level, or at the page level or synthetic transaction level for Browser tests. The following table provides example use cases for detectors at each of these levels:
+In Synthetics, there are detectors to alert on metrics at the test level, at the page level, or at the synthetic transaction level for browser tests. The following table explains each of these detector types:
 
 .. list-table::
    :header-rows: 1
    :widths: 25 75
 
    * - :strong:`Detector type`
-     - :strong:`Use case`
+     - :strong:`Description`
 
    * - Test-level detectors
-     - | Create test-level detectors to trigger alerts on metrics that correspond to the entire test.
+     - | Test-level detectors send alerts on metrics that correspond to an entire test.
        | 
-       | For example, alert when the count of failed runs, % Uptime, or duration of the entire test exceeds a given threshold. 
+       | Examples: Send an alert when the count of failed runs, % uptime, or duration of the entire test exceeds a given threshold. 
 
    * - Page-level detectors
-     - | In Browser tests, create page-level detectors to trigger alerts on metrics corresponding to a single page within a test. For example, alert when the DOM load time, largest contentful paint (LCP), or total image size on a given page exceeds a given threshold. 
+     - | Page-level detectors send alerts on metrics that correspond to a single page within a browser test. 
+       | 
+       | Examples: Send an alert when the DOM load time, largest contentful paint (LCP), or total image size on a given page exceeds a given threshold. 
        | 
        | If you don't scope your alerts to the page level for page-level metrics, the detector monitors the average metric value across pages. See :ref:`page-level-detector` to learn more.
   
    * - Transaction-level detectors
-     - | In Browser tests, create synthetic transaction-level detectors to trigger alerts on metrics based on a synthetic transaction within a test. 
+     - | Synthetic transaction-level detectors send alerts on metrics that correspond to a synthetic transaction within a browser test. 
        | 
-       | You can alert on the three transaction-level metrics that Splunk Synthetic Monitoring captures: Duration, Requests, and Size. See :ref:`transaction-level-detector` to learn more.
+       | Examples: Send an alert on the three transaction-level metrics that Splunk Synthetic Monitoring captures (duration, requests, and size). See :ref:`transaction-level-detector` to learn more.
+
+
+Sample use case: Send an alert when a synthetic test fails
+===============================================================
+
+You can set up a detector while initially creating or editing a test, or from the results view for a particular test. A detector can track one or multiple Synthetic Monitoring tests of the same type.
+
+To set up a detector, do one of the following:
+
+* While creating or editing a test, select :guilabel:`Create detector`. The detector dialog box opens.
+* From the :guilabel:`Test results` page for a particular test, select :guilabel:`Create detector`. The detector dialog box opens.
+
+In the detector dialog box, enter the following fields:
+
+#. In the test name list, select the tests you want to include in your detector. Best practice is to select tests that have a similar run length.
+#. In the metric list, select :strong:`Uptime`. The uptime metric is 0 when the test fails.
+#. In :strong:`+ Add filters` don't add filters for :guilabel:`failed` or :guilabel:`success`. Omit these filters to ensure that the detector sees all datapoints for the test run.
+
+#. In the :guilabel:`Alert details` section, enter the following:
+
+    * :guilabel:`Trigger threshold`: The threshold to trigger the alert.
+    * :guilabel:`Orientation`: Only available for uptime metric. Specify whether the metric must fall below or exceed the threshold to trigger the alert.
+    * :guilabel:`Violates threshold`: How many times the metric must violate the threshold to trigger the alert.
+    * :guilabel:`Split by location`: Select whether to split the detector by test location. If you don't filter by location, the detector monitors the average value across all locations. 
+
+#. Use the severity selector to select the severity of the alert.
+#. Add recipients.
+#. Select :guilabel:`Activate`. 
+
+Your detector is now set up to check for failed test runs every minute and to send an alert based on your settings in :guilabel:`Alert details`.
 
 .. _synth-detector-setup: