Skip to content

[DOCS-12977] cleanup of Synthetics Notifications #33695

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
git-thuerk-done merged 7 commits into from
Jan 7, 2026
Merged

[DOCS-12977] cleanup of Synthetics Notifications #33695

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0220656
update examples
git-thuerk-done Jan 6, 2026
3381e69
Merge branch 'master' into aliciathuerk/update-api-failure
git-thuerk-done Jan 6, 2026
f00475d
adding paragraph tags to fix links
git-thuerk-done Jan 6, 2026
9e8922c
adding more reference links to conditional page
git-thuerk-done Jan 7, 2026
85a54f5
clean up/formatting
git-thuerk-done Jan 7, 2026
9685ada
convert sentence to callout
git-thuerk-done Jan 7, 2026
0fa15b8
Apply suggestions from code review
git-thuerk-done Jan 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 40 additions & 14 deletions content/en/synthetics/notifications/conditional_alerting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@ To ensure notifications are delivered properly, always include a notification ha

For more detailed information, see the <a href="https://docs.datadoghq.com/monitors/notify/variables/?tab=is_alert#examples">Monitor documentation.</a></div>

### Examples
## Examples

**Send alerts based on status code:**
### Send alerts based on status code

```handlebars
```shell
{{!
If a test triggers an alert for an API test and returns a 500 statuscode, notify the backend team.
}}
Expand All @@ -37,13 +37,37 @@ If a test triggers an alert for an API test and returns a 500 statuscode, notify
{{/is_alert}}
```

**Send alerts to a specific Slack channel based on failed step:**
### Send alerts based on an error code

```handlebars
```shell
{{!
Use multiple is_exact_match conditions to display specific failure codes in your notification.
This example checks for DNS and INCORRECT_ASSERTION failure codes
}}

{{#if synthetics.attributes.result.failure}}

{{#is_exact_match "synthetics.attributes.result.failure.code" "DNS"}}
print out failure code: The failure code is DNS
{{/is_exact_match}}

{{#is_exact_match "synthetics.attributes.result.failure.code" "INCORRECT_ASSERTION"}}
print out failure code: The failure code is an INCORRECT ASSERTION
{{/is_exact_match}}

{{/if}}
```

<div class="alert alert-info">For a complete list of API test error codes, see <a href="/synthetics/api_tests/errors/">API Testing Errors</a>.</div>

### Send alerts to a specific Slack channel based on failed step

```shell
{{!
If a test triggers an alert for browser or mobile tests, loop through each step and find the failed step.
If the failed step's description field matches Checkout, notify the recipient
}}

{{#is_alert}}
{{#each synthetics.attributes.result.steps}}
{{#is_match "status" "failed"}}
Expand All @@ -53,26 +77,28 @@ If the failed step's description field matches Checkout, notify the recipient
{{/is_alert}}
```

**Send alerts to a specific Slack channel based on failed step using a variable shortcut:**
### Send alerts to a specific Slack channel based on failed step using a variable shortcut

```handlebars
```shell
{{!
This alert uses the `{{synthetics.failed_step}}` object which is a variable shortcut that points to the relevant step data contained in `{{synthetics.attributes.result.steps}}`.
This alert uses the {{synthetics.failed_step}} object which is a variable shortcut that points to the relevant step data contained in {{synthetics.attributes.result.steps}}.
If the test triggers an alert for browser or mobile tests, and if the failed step's description field matches Checkout, notify the recipient.
}}

{{#is_alert}}
{{#is_match "synthetics.failed_step.description" "Checkout"}}@notify-slack-payments{{/is_match}}
{{/is_alert}}
```

**Set different alert priorities:**
### Set different alert priorities

```handlebars
```shell
{{!
If a test triggers an alert for a multistep API test, loop through each step and find the failed step.
If the step's name matches the staging domain, set the priority to P2. Otherwise, set it to P4.
}}
{{#is_alert}}send a message to thang @thang.nguyen@datadoghq.com

{{#is_alert}}send a message to <name> @example@email.com
{{#each synthetics.attributes.result.steps}}
{{#is_match "status" "failed"}}
{{#is_match "name" "stagedomain"}}Stage domain failed. Overriding priority to P2.
Expand All @@ -84,11 +110,11 @@ If the step's name matches the staging domain, set the priority to P2. Otherwise
{{/is_alert}}
```

**Set different alert priorities using variable shortcut:**
### Set different alert priorities using variable shortcut

```handlebars
```shell
{{!
This alert uses the `{{synthetics.failed_step}}` object which is a variable shortcut that points to the relevant step data contained in `{{synthetics.attributes.result.steps}}`.
This alert uses the {{synthetics.failed_step}} object which is a variable shortcut that points to the relevant step data contained in `{{synthetics.attributes.result.steps}}`.
If the test triggers an alert for multistep API test and if the failed step's name field matches the domain, override the priority.
}}
{{#is_alert}}
Expand Down
42 changes: 37 additions & 5 deletions content/en/synthetics/notifications/template_variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,8 @@ Use these variables to access common test execution data such as failure message
: The URL of the failed step (for example, `https://www.datadoghq.com/blog/`).

`{{synthetics.attributes.result.response.statusCode}}`
: The HTTP status code (for example, `403`).
: The HTTP status code (for example, `403`). </br>
<strong>Tip:</strong> Review the <a href="/synthetics/notifications/conditional_alerting#send-alerts-based-on-status-code">conditional alerting</a> page for an example of how to use this variable in a notification.

`{{synthetics.result.step_count}}`
: Number of steps (for example, `4`).
Expand Down Expand Up @@ -141,14 +142,16 @@ Applies to Browser and Mobile tests.
: Epoch timestamps in milliseconds

`{{synthetics.attributes.result.failure}}`
: The `failure` object contains information about why the test failed
: The `failure` object contains information about why the test failed

`{{synthetics.attributes.result.failure.message}}`
: The failure message

`{{synthetics.attributes.result.failure.code}}`
: The failure code

<p>For a complete list of API test error codes, see <a href="/synthetics/api_tests/errors/">API Testing Errors</a>. Review the <a href="/synthetics/notifications/conditional_alerting#send-alerts-based-on-an-error-code">conditional alerting</a> page for an example of how to use the <code>synthetics.attributes.result.failure</code> variable in a notification.</p>

{{% /tab %}}
{{% tab "Count" %}}

Expand All @@ -175,9 +178,31 @@ Applies to Multistep, Browser, and Mobile tests.
Applies to Multistep, Browser, and Mobile tests.

`{{synthetics.failed_step}}`
: The `failed_step` object provides a shortcut to the step that caused the test to fail, eliminating the need to reference `{{synthetics.attributes.result.steps.<step-index>}}` directly.

For example, `{{synthetics.failed_step.name}}` maps to `{{synthetics.attributes.result.steps.<step-index>.name}}` for Multistep API tests, and to `{{synthetics.attributes.result.steps.<step-index>.description}}` for Browser and Mobile tests.
: The `failed_step` object provides a shortcut to the step that caused the test to fail, eliminating the need to reference `{{synthetics.attributes.result.steps.<step-index>}}` directly. </br>

<table>
<thead>
<tr>
<th style="min-width: 240px;">Shortcut</th>
<th>Test Type</th>
<th>Maps To</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>{{synthetics.failed_step.name}}</code></td>
<td>Multistep API</td>
<td><code>{{synthetics.attributes.result.steps.&lt;step-index&gt;.name}}</code></td>
</tr>
<tr>
<td><code>{{synthetics.failed_step.description}}</code></td>
<td>Browser, Mobile</td>
<td><code>{{synthetics.attributes.result.steps.&lt;step-index&gt;.description}}</code></td>
</tr>
</tbody>
</table>

<div class="alert alert-tip">Review the <a href="/synthetics/notifications/conditional_alerting/#send-alerts-to-a-specific-slack-channel-based-on-failed-step-using-a-variable-shortcut">conditional alerting</a> page for an example of how to use the <code>synthetics.failed_step.description</code> shortcut variable in a Browser Test notification.</div>

{{% /tab %}}
{{< /tabs >}}
Expand Down Expand Up @@ -623,6 +648,8 @@ Use the step's unique identifier:

`.steps.abc-def-ghi`

<div class="alert alert-tip">Review the <a href="/synthetics/notifications/conditional_alerting#send-alerts-to-a-specific-slack-channel-based-on-failed-step">conditional alerting</a> page for an example of how to use the <code>synthetics.attributes.result.step</code> variable in a Slack notification based on a failed step.</div>

#### Accessing step properties

Combine any reference method with a property:
Expand All @@ -637,3 +664,8 @@ Combine any reference method with a property:

[1]: /synthetics/explore/results_explorer
[2]: /synthetics/notifications/template_variables/?tab=apitests#step-execution-details
[3]: /synthetics/notifications/conditional_alerting#send-alerts-based-on-an-error-code
[4]: /synthetics/api_tests/errors/
[5]: /synthetics/notifications/conditional_alerting#send-alerts-based-on-status-code
[6]: /synthetics/notifications/conditional_alerting#send-alerts-to-a-specific-slack-channel-based-on-failed-step

Loading