Skip to content

Commit

Permalink
[DOCS-9465] adding Synthetics templates (#26462)
Browse files Browse the repository at this point in the history 
* adding Synthetics templates

* removing mobile app testing

* updates to Synthetics templates

* adding steps for api tests getting started

* formatting

* wording

* formatting

* restructuring layout

* dns/http/ssl/api

* resetting go files

* uploading video and all API Tests configs

* finalizing API tests based on review

* updating Browser tests

* adding mobile app tests

* updating Browser

* updates to Templates PR from editorial review and adding mobile app video

* Apply suggestions from code review

Co-authored-by: Rosa Trieu <[email protected]>

---------

Co-authored-by: Rosa Trieu <[email protected]>
  • Loading branch information
@aliciascott @rtrieu
aliciascott and rtrieu authored Dec 23, 2024
1 parent 89aa284 commit cfd1f41
Show file tree
Hide file tree
Showing 27 changed files with 300 additions and 181 deletions.
45 changes: 28 additions & 17 deletions content/en/getting_started/synthetics/api_test.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,32 +36,43 @@ API tests **proactively monitor** that your **most important services** are avai

HTTP tests monitor your API endpoints and alert you when response latency is high or fail to meet any conditions you define, such as expected HTTP status code, response headers, or response body content.

{{< img src="getting_started/synthetics/api-test.png" alt="Overview of a Synthetics HTTP Test" style="width:100%;" >}}

The example below demonstrates how to create an [HTTP test][3], a subtype of [single API tests][1].

### Define request
The examples below demonstrate how to create an [HTTP test][3], a subtype of [single API tests][1].

1. In the Datadog site, hover over **Digital Experience** and select **[Tests][4]** (under **Synthetic Monitoring & Testing**).

2. Click **New Test** > **[New API test][5]**.
3. Select the `HTTP` request type.
4. Define your request:

- Add the URL of the endpoint you want to monitor. If you don't know what to start with, you can use `https://www.shopist.io/`, a test e-commerce web application. Defining the endpoint to test automatically populates the name of your test to `Test on www.shopist.io`.
- You can select **Advanced Options** to set custom request options, certificates, authentication credentials, and more.

**Note:** You can create secure [global variables][6] to store credentials and create [local variables][7] to generate dynamic timestamps to use in your request payload. After creating these variables, type `{{` in any relevant field and select the variable to inject its value in your test options.

In this example, no specific advanced option is needed.
- You can set tags such as `env:prod` and `app:shopist` on your test. Tags allow you to keep your test suite organized and quickly find tests you're interested in on the homepage.
3. You may create a test using one of the following options:

- **Create a test from a template**:

1. Hover over one of the pre-populated templates and click **View Template**. This opens a side panel displaying pre-populated configuration information, including: Test Details, Request Details, Assertions, Alert Conditions, and Monitor Settings.
2. Click **+Create Test** to open the **Define Request** page, where you can review and edit the pre-populated configuration options. The fields presented are identical to those available when creating a test from scratch.
3. Click **Save Details** to submit your API test.<br /><br>

{{< img src="getting_started/synthetics/synthetics_templates_api_video.mp4" alt="Video of Synthetics API test landing page with templates" video="true" >}}

- **Build a test from scratch**:

1. To build a test from scratch, click the **+ Start from scratch** template, then select the `HTTP` request type.

2. Add the URL of the endpoint you want to monitor. If you don't know what to start with, you can use `https://www.shopist.io/`, a test e-commerce web application. If you use the test Shopist URL, the name of your test is automatically populated as `Test on shopist.io`.

3. Optionally, select **Advanced Options** to set custom request options, add certificates and authentication credentials, and create secure [global variables][6] or [local variables][7] for dynamic inputs.

**Note**: Type `{{` in any relevant field to select a variable and inject its value into your test options.

4. Optionally, set tags such as `env:prod` and `app:shopist` on your test. Tags allow you to keep your test suite organized and quickly find tests you're interested in on the homepage.

5. Click **Send** to trigger a sample test run.

5. Click **Test URL** to trigger a sample test run.
{{< img src="getting_started/synthetics/api-test-config-4.png" alt="API test configuration" style="width:90%;">}}

{{< img src="getting_started/synthetics/api-test-config-3.png" alt="API test configuration" style="width:100%;">}}
6. Click **Create Test** to submit your API test.

### Define assertions

Clicking **Test URL** automatically populates basic assertions about your endpoint's response. Assertions define what a successful test run is.
Clicking **Send** automatically populates basic assertions about your endpoint's response. Assertions define what a successful test run is.

In this example, three default assertions populate after triggering the sample test run:

Expand Down
39 changes: 23 additions & 16 deletions content/en/getting_started/synthetics/browser_test.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,44 +24,51 @@ further_reading:

## Overview

[Browser tests][1] are scenarios that Datadog executes on your web applications. You can configure periodic intervals to run tests from multiple locations, devices, and browsers as well as execute them from your CI/CD pipelines.

{{< img src="getting_started/synthetics/browser-test-overview.png" alt="Overview of a Synthetics Browser Test" style="width:100%;" >}}

These tests verify that your users can perform **key business transactions** on your applications and that they are not negatively impacted by recent code changes.
[Browser tests][1] are scenarios that Datadog executes on your web applications. You can configure periodic intervals to run tests from multiple locations, devices, and browsers as well as execute them from your CI/CD pipelines. These tests verify that your users can perform **key business transactions** on your applications and that they are not negatively impacted by recent code changes.

## Create a browser test

The example below demonstrates the creation of a browser test that maps a user's journey from adding an item to a cart to successfully checking out.

{{< img src="getting_started/synthetics/browser-test-1.png" alt="Browser test mapping out a user journey" style="width:100%;" >}}
### Configure your test details

1. In the Datadog site, hover over **Digital Experience** in the left hand menu and select **[Tests][2]** (under **Synthetic Monitoring & Testing**).
2. In the top right corner, click **New Test** > **[Browser Test][3]**.
3. Define your browser test:

- Add the URL of the website you want to monitor. If you don't know what to start with, you can use `https://www.shopist.io`, a test e-commerce web application.
- Select **Advanced Options** to set custom request options, certificates, authentication credentials, and more.
In this example, no specific advanced option is needed.
- Name your test and set tags to it such as `env:prod` and `app:shopist`. Tags allow you to keep your test suite organized and quickly find tests you're interested in on the homepage.
- Choose the browsers and devices you want to test with.
You may create a test using one of the following options:

- **Create a test from a template**:

1. Hover over one of the pre-populated templates and click **View Template**. This opens a side panel displaying pre-populated configuration information, including: Test Details, Alert Conditions, Steps, and optionally Variables.
2. Click **+Create Test** to open the configuration page, where you can review and edit the pre-populated configuration options. The fields presented are identical to those available when creating a test from scratch.
3. Click **Save & Quit** in the upper right hand corner to submit your Browser Test.<br /><br>

{{< img src="/synthetics/browser_tests/synthetics_templates_browser.mp4" alt="Video of Synthetics Browser Test landing page with templates" video="true" >}}

- **Build a test from scratch**:

1. Click the **+** template to start a new Browser Test from scratch.
1. Add the URL of the website you want to monitor. If you don't know what to start with, you can use `https://www.shopist.io`, a test e-commerce web application.
2. Select **Advanced Options** to set custom request options, certificates, authentication credentials, and more.
3. Name your test and set tags to it such as `env:prod` and `app:shopist`. Tags allow you to keep your test suite organized and quickly find tests you're interested in on the homepage.
4. Choose the browsers and devices you want to test with.
5. Click **Save & Edit Recording** to submit your Browser Test.

### Select locations
### Select locations

Select one or more **Managed Locations** or **Private Locations** to run your test from.

Managed locations allow you to test public-facing websites and endpoints. To test internal applications or simulate user behavior in discrete geographic regions, use [private locations][4] instead.

The Shopist application is publicly available at `https://www.shopist.io/`, so you can pick any managed locations to execute your test from.

### Specify test frequency
### Specify test frequency

Select the frequency at which you want your test to execute. You can leave the default frequency of 1 hour.

In addition to running your Synthetic test on a schedule, you can trigger them manually or directly from your [CI/CD pipelines][5].

### Define alert conditions
### Define alert conditions

You can define alert conditions to ensure your test does not trigger for things like a sporadic network blip, so that you only get alerted in case of real issues with your application.

Expand All @@ -77,7 +84,7 @@ You can also configure your test to only trigger a notification when your applic
An alert is triggered if your test fails for 3 minutes from any 2 of 13 locations
```

### Configure the test monitor
### Configure the test monitor

Design your alert message and add an email address you want your test to send alerts to.

Expand Down
38 changes: 24 additions & 14 deletions content/en/synthetics/api_tests/dns_tests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,20 +35,30 @@ DNS tests can run from both [managed](#select-locations) and [private locations]

## Configuration

After choosing to create a `DNS` test, define your test's request.

### Define request

1. Specify the **Domain** you want your test to query. For example, `www.example.com`.
2. Specify the **DNS Server** to use (optional), it can be a domain name or an IP address. If not specified, your DNS test performs resolution using `8.8.8.8`, with a fallback on `1.1.1.1` and an internal AWS DNS server.
3. Specify your DNS Server **Port** (optional). If not specified, the DNS Server port defaults to 53.
4. Specify the amount of time in seconds before the test times out (optional).
5. **Name** your DNS test.
6. Add `env` **Tags** as well as any other tag to your DNS test. You can then use these tags to filter through your Synthetic tests on the [Synthetic Monitoring & Continuous Testing page][3].

{{< img src="synthetics/api_tests/dns_test_config_new.png" alt="Define DNS query" style="width:90%;" >}}

Click **Test URL** to try out the request configuration. A response preview is displayed on the right side of your screen.
You may create a test using one of the following options:

- **Create a test from a template**:

1. Hover over one of the pre-populated templates and click **View Template**. This opens a side panel displaying pre-populated configuration information, including: Test Details, Request Details, Assertions, Alert Conditions, and Monitor Settings.
2. Click **+Create Test** to open the **Define Request** page, where you can review and edit the pre-populated configuration options. The fields presented are identical to those available when creating a test from scratch.
3. Click **Save Details** to submit your API test.<br /><br>

{{< img src="getting_started/synthetics/synthetics_templates_api_video.mp4" alt="Video of Synthetics API test landing page with templates" video="true" >}}

- **Build a test from scratch**:

1. To build a test from scratch, click the **+ Start from scratch** template, then select the DNS request type.
1. Specify the **Domain** you want your test to query. For example, `www.example.com`.
1. Specify the **DNS Server** to use (optional), it can be a domain name or an IP address. If not specified, your DNS test performs resolution using `8.8.8.8`, with a fallback on `1.1.1.1` and an internal AWS DNS server.
1. Specify your DNS Server **Port** (optional). If not specified, the DNS Server port defaults to 53.
1. Specify the amount of time in seconds before the test times out (optional).
1. **Name** your DNS test.
1. Add Environment **Tags** as well as any other tag to your DNS test. You can then use these tags to filter through your Synthetic tests on the [Synthetic Monitoring & Continuous Testing page][3].
1. Click **Test Domain** to try out the request configuration. A response preview is displayed on the right side of your screen.<br /><br>

{{< img src="synthetics/api_tests/synthetics_dns_test_domain.png" alt="Define DNS query" style="width:90%;" >}}

1. Click **Create Test** to submit your API test.

### Snippets

Expand Down
91 changes: 49 additions & 42 deletions content/en/synthetics/api_tests/grpc_tests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,68 +38,75 @@ Health Checks

gRPC tests can run from both [managed](#select-locations) and [private locations][2] depending on your preference for running the test from outside or inside your network. gRPC tests can run on a schedule, on-demand, or directly within your [CI/CD pipelines][3].

## Configuration
## Configuration

After choosing to create a `gRPC` test, define your test's request.
You may create a test using one of the following options:

### Define request
- **Create a test from a template**:

1. Specify the **Host** and **Port** to run your test on. The default gRPC port is `50051`.
2. Select **Behavior Check** to perform a unary call or **Health Check** to perform a health check.

{{< tabs >}}
{{% tab "Behavior Check" %}}
1. Hover over one of the pre-populated templates and click **View Template**. This opens a side panel displaying pre-populated configuration information, including: Test Details, Request Details, Assertions, Alert Conditions, and Monitor Settings.
2. Click **+Create Test** to open the **Define Request** page, where you can review and edit the pre-populated configuration options. The fields presented are identical to those available when creating a test from scratch.
3. Click **Save Details** to submit your API test.<br /><br>
{{< img src="getting_started/synthetics/synthetics_templates_api_video.mp4" alt="Video of Synthetics API test landing page with templates" video="true" >}}

For a behavior check, specify the **Server Reflection** or [upload a **Proto File**][101] that defines your gRPC server. Select a method and include a request message. Datadog does not support streaming methods.

{{< img src="synthetics/api_tests/grpc_behavior_check_test.png" alt="Define gRPC request" style="width:90%;" >}}

[101]: https://grpc.io/docs/what-is-grpc/introduction/#working-with-protocol-buffers
- **Build a test from scratch**:

{{% /tab %}}
{{% tab "Health Check" %}}
1. To build a test from scratch, click the **+ Start from scratch** template, then select the `gRPC` request type.
2. Specify the **Host** and **Port** to run your test on. The default gRPC port is `50051`.
3. Select **Behavior Check** to perform a unary call or **Health Check** to perform a health check.<br /><br>

For a health check, enter the name of the service. Leave this field blank if you want to send a health check on the gRPC server.
{{< tabs >}}
{{% tab "Behavior Check" %}}

{{< img src="synthetics/api_tests/grpc_health_check_test.png" alt="Define gRPC request" style="width:90%;" >}}

{{% /tab %}}
{{< /tabs >}}
For a behavior check, specify the **Server Reflection** or [upload a **Proto File**][101] that defines your gRPC server. Select a method and include a request message. Datadog does not support streaming methods.<br /><br>

3. Add **Advanced Options** (optional) to your test:
{{< img src="synthetics/api_tests/grpc_behavior_check_test_2.png" alt="Define gRPC request" style="width:90%;" >}}

{{< tabs >}}
[101]: https://grpc.io/docs/what-is-grpc/introduction/#working-with-protocol-buffers

{{% tab "Request Options" %}}

* **Timeout**: Specify the amount of time in seconds before the test times out.
* **Ignore server certificate error**: Select to have your gRPC test go on with connection even if there are errors when validating the SSL certificate.
* **gRPC metadata**: Add and define metadata to your gRPC request to pass metadata between services.
{{% /tab %}}
{{% tab "Health Check" %}}

{{% /tab %}}
For a health check, enter the name of the service. Leave this field blank if you want to send a health check on the gRPC server.<br /><br>

{{% tab "Authentication" %}}
{{< img src="synthetics/api_tests/grpc_health_check_test_2.png" alt="Define gRPC request" style="width:90%;" >}}

* **Client certificate**: Authenticate through mTLS by uploading your client certificate (`.crt`) and the associated private key (`.key`) in `PEM` format.
{{% /tab %}}
{{< /tabs >}}

<br/>

You can use the `openssl` library to convert your certificates. For example, convert a `PKCS12` certificate to `PEM` formatted private keys and certificates.
4. Add **Advanced Options** (optional) to your test:

```
openssl pkcs12 -in <CERT>.p12 -out <CERT_KEY>.key -nodes -nocerts
openssl pkcs12 -in <CERT>.p12 -out <CERT>.cert -nokeys
```
{{< tabs >}}
{{% tab "Request Options" %}}

{{% /tab %}}
- **Time out**: Specify the amount of time in seconds before the test times out.
- **Ignore server certificate error**: Select to have your gRPC test go on with connection even if there are errors when validating the SSL certificate.
- **gRPC metadata**: Add and define metadata to your gRPC request to pass metadata between services.

{{< /tabs >}}
{{% /tab %}}
{{% tab "Authentication" %}}

3. **Name** your gRPC test.
- **Client certificate**: Authenticate through mTLS by uploading your client certificate (`.crt`) and the associated private key (`.key`) in `PEM` format.

4. Add `env` **Tags** as well as any other tag to your gRPC test. You can then use these tags to filter through your Synthetic tests on the [Synthetic Monitoring & Continuous Testing page][4].
<br/>

Click **Send** to try out the request configuration. A response preview is displayed on the right side of your screen.
You can use the `openssl` library to convert your certificates. For example, convert a `PKCS12` certificate to `PEM` formatted private keys and certificates.

```bash
openssl pkcs12 -in <CERT>.p12 -out <CERT_KEY>.key -nodes -nocerts
openssl pkcs12 -in <CERT>.p12 -out <CERT>.cert -nokeys
```

{{% /tab %}}
{{< /tabs >}}

5. **Name** your gRPC test.

6. Add Environment **Tags** as well as any other tags to your gRPC test. You can then use these tags to filter through your Synthetic tests on the [Synthetic Monitoring & Continuous Testing page][4].

7. Click **Invoke** to try out the request configuration. A response preview is displayed on the right side of your screen.

8. Click **Create Test** to submit your API test.

### Snippets

Expand Down
Loading

0 comments on commit cfd1f41

Please sign in to comment.