Skip to content
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

Update synthetics api tests documentation with grace information #26847

Draft
wants to merge 7 commits into
base: master
Choose a base branch
from
Draft

Update synthetics api tests documentation with grace information #26847

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1b0fe2b
Update synthetics api tests documentation with grace information
AlaricCalmette Dec 19, 2024
6701e86
Update browser tests permission table
AlaricCalmette Dec 19, 2024
004adeb
Fix note
AlaricCalmette Dec 20, 2024
ffa871d
Update mobile app testing
AlaricCalmette Dec 20, 2024
31f1eae
Fix grace link
AlaricCalmette Dec 20, 2024
c42df69
Update PL documentation
AlaricCalmette Dec 20, 2024
1a74022
Update GV documentation
AlaricCalmette Dec 20, 2024
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
37 changes: 28 additions & 9 deletions content/en/synthetics/api_tests/dns_tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ If a test contains an assertion on the response body and the timeout limit is re

Select the **Locations** to run your DNS test from. DNS tests can run from both managed and [private locations][1] depending on your preference for monitoring a public or private domain.

{{% managed-locations %}}
{{% managed-locations %}}

### Specify test frequency

Expand All @@ -92,7 +92,7 @@ DNS tests can run:

{{% synthetics-alerting-monitoring %}}

{{% synthetics-variables %}}
{{% synthetics-variables %}}

### Use variables

Expand All @@ -102,7 +102,7 @@ To display your list of variables, type `{{` in your desired field.

## Test failure

A test is considered `FAILED` if it does not satisfy one or more assertions or if the request prematurely failed. In some cases, the test can fail without testing the assertions against the endpoint.
A test is considered `FAILED` if it does not satisfy one or more assertions or if the request prematurely failed. In some cases, the test can fail without testing the assertions against the endpoint.

These reasons include the following:

Expand All @@ -112,12 +112,12 @@ These reasons include the following:
`DNS`
: DNS entry not found for the test URL. Possible causes include misconfigured test URL or the wrong configuration of your DNS entries.

`INVALID_REQUEST`
`INVALID_REQUEST`
: The configuration of the test is invalid (for example, a typo in the URL).

`TIMEOUT`
: The request couldn't be completed in a reasonable time. Two types of `TIMEOUT` can happen:
- `TIMEOUT: The request couldn't be completed in a reasonable time.` indicates that the request duration hit the test defined timeout (default is set to 60s).
- `TIMEOUT: The request couldn't be completed in a reasonable time.` indicates that the request duration hit the test defined timeout (default is set to 60s).
For each request only the completed stages for the request are displayed in the network waterfall. For example, in the case of `Total response time` only being displayed, the timeout occurred during the DNS resolution.
- `TIMEOUT: Overall test execution couldn't be completed in a reasonable time.` indicates that the test duration (request + assertions) hits the maximum duration (60.5s).

Expand All @@ -129,11 +129,30 @@ If you are using the [custom role feature][11], add your user to any custom role

### Restrict access

Access restriction is available for customers using [custom roles][12] on their accounts.
{{< img src="synthetics/settings/grace_1.png" alt="Set permissions for your test" style="width:70%;" >}}

You can restrict access to a DNS test based on the roles in your organization. When creating a DNS test, choose which roles (in addition to your user) can read and write your test.
Use [granular access control][12] to limit who has access to your test based on roles, teams, or individual users.

{{< img src="synthetics/settings/restrict_access_1.png" alt="Set permissions for your test" style="width:70%;" >}}
To do so:

1. Open the permissions section of the form
2. Click on `edit access`

{{< img src="synthetics/settings/grace_2.png" alt="Set permissions for your test" style="width:70%;" >}}

3. Click on `restrict access`
4. Select teams, roles, or users
5. Click `add`
6. Select the level of access you want to associate with each of them
7. Click on done

| Access level | View test configuration | Edit test configuration | View test results | Run test |
| ------------ | ----------------------- | ----------------------- | ------------------| --------- |
| No access | | | | |
| Viewer | {{< X >}} | | {{< X >}} | |
| Editor | {{< X >}} | {{< X >}} | {{< X >}} | {{< X >}} |

<div class="alert alert-info"><strong>Note</strong>: You will be able to see results from Private Location even if you don't have Viewer access to that Private Location.</div>

## Further Reading

Expand All @@ -150,4 +169,4 @@ You can restrict access to a DNS test based on the roles in your organization. W
[9]: /synthetics/settings/#global-variables
[10]: /account_management/rbac/
[11]: /account_management/rbac#custom-roles
[12]: /account_management/rbac/#create-a-custom-role
[12]: /account_management/rbac/granular_access
49 changes: 34 additions & 15 deletions content/en/synthetics/api_tests/grpc_tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ gRPC tests allow you to proactively monitor your gRPC services and servers. You
Behavior Checks
: Send gRPC requests to your applications' API endpoints to verify responses and defined conditions, such as overall response time, header, or body content.

Health Checks
Health Checks
: gRPC health checks are a standard for reporting the health of gRPC services. Determine if your gRPC servers and services are responsive, running, and capable of handling remote procedure calls (RPCs).<br><br>By implementing gRPC health checks, you can run gRPC health checks tests without having to provide a `.proto` file to Datadog. For more information, see the [example health checks `.proto` file][1] shared by the gRPC community.

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].
Expand All @@ -45,15 +45,15 @@ After choosing to create a `gRPC` test, define your test's request.
### Define request

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.
2. Select **Behavior Check** to perform a unary call or **Health Check** to perform a health check.

{{< tabs >}}
{{% tab "Behavior Check" %}}

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

{{% /tab %}}
Expand All @@ -62,7 +62,7 @@ After choosing to create a `gRPC` test, define your test's request.
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.

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

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

Expand All @@ -71,7 +71,7 @@ After choosing to create a `gRPC` test, define your test's request.
{{< tabs >}}

{{% 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.
Expand All @@ -80,10 +80,10 @@ After choosing to create a `gRPC` test, define your test's request.

{{% tab "Authentication" %}}

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

<br/>

<br/>

You can use the `openssl` library to convert your certificates. For example, convert a `PKCS12` certificate to `PEM` formatted private keys and certificates.

```
Expand Down Expand Up @@ -150,7 +150,7 @@ If a test contains an assertion on the response body and the timeout limit is re

Select the **Locations** to run your gRPC test from. gRPC tests can run from both managed and [private locations][2] depending on your preference for running the test from outside or inside your network.

{{% managed-locations %}}
{{% managed-locations %}}

### Specify test frequency

Expand Down Expand Up @@ -205,11 +205,30 @@ If you are using the [custom role feature][13], add your user to any custom role

## Restrict access

Access restriction is available for customers using [custom roles][14] on their accounts.
{{< img src="synthetics/settings/grace_1.png" alt="Set permissions for your test" style="width:70%;" >}}

Use [granular access control][14] to limit who has access to your test based on roles, teams, or individual users.

To do so:

1. Open the permissions section of the form
2. Click on `edit access`

{{< img src="synthetics/settings/grace_2.png" alt="Set permissions for your test" style="width:70%;" >}}

3. Click on `restrict access`
4. Select teams, roles, or users
5. Click `add`
6. Select the level of access you want to associate with each of them
7. Click on done

You can restrict access to a browser test based on the roles in your organization. When creating a browser test, choose which roles (in addition to your user) can read and write your test.
| Access level | View test configuration | Edit test configuration | View test results | Run test |
| ------------ | ----------------------- | ----------------------- | ------------------| --------- |
| No access | | | | |
| Viewer | {{< X >}} | | {{< X >}} | |
| Editor | {{< X >}} | {{< X >}} | {{< X >}} | {{< X >}} |

{{< img src="synthetics/settings/restrict_access_1.png" alt="Set permissions for your test" style="width:70%;" >}}
<div class="alert alert-info"><strong>Note</strong>: You will be able to see results from Private Location even if you don't have Viewer access to that Private Location.</div>


## Further Reading
Expand All @@ -230,4 +249,4 @@ You can restrict access to a browser test based on the roles in your organizatio
[11]: /synthetics/api_tests/errors/#ssl-errors
[12]: /account_management/rbac/
[13]: /account_management/rbac#custom-roles
[14]: /account_management/rbac/#create-a-custom-role
[14]: /account_management/rbac/granular_access
56 changes: 38 additions & 18 deletions content/en/synthetics/api_tests/http_tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,19 +80,19 @@ Click **Test URL** to try out the request configuration. A response preview is d
openssl pkcs12 -in <CERT>.p12 -out <CERT_KEY>.key -nodes -nocerts
openssl pkcs12 -in <CERT>.p12 -out <CERT>.cert -nokeys
```

* **HTTP Basic Auth**: Add HTTP basic authentication credentials.
* **Digest Auth**: Add Digest authentication credentials.
* **Digest Auth**: Add Digest authentication credentials.
* **NTLM**: Add NTLM authentication credentials. Support both NTLMv2 and NTLMv1.
* **AWS Signature v4**: Enter your Access Key ID and Secret Access Key. Datadog generates the signature for your request. This option uses the basic implementation of SigV4. Specific signatures such as Amazon S3 are not supported out-of-the box.
* **AWS Signature v4**: Enter your Access Key ID and Secret Access Key. Datadog generates the signature for your request. This option uses the basic implementation of SigV4. Specific signatures such as Amazon S3 are not supported out-of-the box.
For "Single Chunk" transfer requests to Amazon S3 buckets, add `x-amz-content-sha256` containing the sha256-encoded body of the request as a header (for an empty body: `x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`).
* **OAuth 2.0**: Choose between granting client credentials or a resource owner password and enter an access token URL. Depending on your selection, enter a client ID and secret, or a username and password. From the dropdown menu, select an option to either send the API token as a basic authentication header, or send the client credentials in the body. Optionally, you can provide additional information such as the audience, resource, and scope (as well as the client ID and secret, if you selected **Resource Owner Password**).
* **OAuth 2.0**: Choose between granting client credentials or a resource owner password and enter an access token URL. Depending on your selection, enter a client ID and secret, or a username and password. From the dropdown menu, select an option to either send the API token as a basic authentication header, or send the client credentials in the body. Optionally, you can provide additional information such as the audience, resource, and scope (as well as the client ID and secret, if you selected **Resource Owner Password**).

{{% /tab %}}

{{% tab "Query Parameters" %}}

* **Encode parameters**: Add the name and value of query parameters that require encoding.
* **Encode parameters**: Add the name and value of query parameters that require encoding.

{{% /tab %}}

Expand All @@ -102,7 +102,7 @@ Click **Test URL** to try out the request configuration. A response preview is d
* **Request body**: Add the content of your HTTP request body.
* The request body is limited to a maximum size of 50 kilobytes for `application/json`, `application/x-www-form-urlencoded`, `text/html`, `text/plain`, `text/xml`, `GraphQL`.
* The request body is limited to one file of 3 megabytes for `application/octet-stream`.
* The request body is limited to three files of 3 megabytes each for `multipart/form-data`.
* The request body is limited to three files of 3 megabytes each for `multipart/form-data`.
{{% /tab %}}

{{% tab "Proxy" %}}
Expand Down Expand Up @@ -147,17 +147,17 @@ You can create up to 20 assertions per API test by clicking **New Assertion** or

{{< img src="synthetics/api_tests/assertions_http.png" alt="Define assertions for your HTTP test to succeed or fail on" style="width:90%;" >}}

To perform `OR` logic in an assertion, use the `matches regex` comparator to define a regex with multiple expected values like `(200|302)`. For example, you may want your HTTP test to succeed when a server must respond with a `200` or `302` status code. The `status code` assertion succeeds if the status code is 200 or 302. You can also add `OR` logic on a `body` or `header` assertion.
To perform `OR` logic in an assertion, use the `matches regex` comparator to define a regex with multiple expected values like `(200|302)`. For example, you may want your HTTP test to succeed when a server must respond with a `200` or `302` status code. The `status code` assertion succeeds if the status code is 200 or 302. You can also add `OR` logic on a `body` or `header` assertion.

If a test does not contain an assertion on the response body, the body payload drops and returns an associated response time for the request within the timeout limit set by the Synthetics Worker.

If a test contains an assertion on the response body and the timeout limit is reached, an `Assertions on the body/response cannot be run beyond this limit` error appears.

### Select locations

Select the **Locations** to run your HTTP test from. HTTP tests can run from both managed and [private locations][1] depending on your preference for running the test from outside or inside your network.
Select the **Locations** to run your HTTP test from. HTTP tests can run from both managed and [private locations][1] depending on your preference for running the test from outside or inside your network.

{{% managed-locations %}}
{{% managed-locations %}}

### Specify test frequency

Expand All @@ -177,7 +177,7 @@ Use existing Datadog data sources such as APM traces, API Catalog endpoints disc
Start typing in the API test **URL** input to get endpoint suggestions or similar tests in Synthetic Monitoring:

{{< img src="synthetics/api_tests/api-one-click.png" alt="HTTP API Test showing a GET search for an existing API test" style="width:90%;" >}}

Then, select a suggestion to prefill your test configuration (request options and headers, authentication, and variables):

{{< img src="synthetics/api_tests/api-test-monitor-search.png" alt="Select" style="width:90%;" >}}
Expand All @@ -194,7 +194,7 @@ To display your list of variables, type `{{` in your desired field:

## Test failure

A test is considered `FAILED` if it does not satisfy one or more assertions or if the request prematurely failed. In some cases, the test can fail without testing the assertions against the endpoint.
A test is considered `FAILED` if it does not satisfy one or more assertions or if the request prematurely failed. In some cases, the test can fail without testing the assertions against the endpoint.

The most common errors include the following:

Expand All @@ -213,19 +213,19 @@ The most common errors include the following:
`Error performing HTTP/2 request`
: The request could not be performed. See the dedicated [error][16] page for more information.

`INVALID_REQUEST`
`INVALID_REQUEST`
: The configuration of the test is invalid (for example, a typo in the URL).

`SSL`
: The SSL connection couldn't be performed. [See the dedicated error page for more information][12].

`TIMEOUT`
: The request couldn't be completed in a reasonable time. Two types of `TIMEOUT` can happen:
- `TIMEOUT: The request couldn't be completed in a reasonable time.` indicates that the request duration hit the test defined timeout (default is set to 60s).
- `TIMEOUT: The request couldn't be completed in a reasonable time.` indicates that the request duration hit the test defined timeout (default is set to 60s).
For each request only the completed stages for the request are displayed in the network waterfall. For example, in the case of `Total response time` only being displayed, the timeout occurred during the DNS resolution.
- `TIMEOUT: Overall test execution couldn't be completed in a reasonable time.` indicates that the test duration (request + assertions) hits the maximum duration (60.5s).

`MALFORMED_RESPONSE`
`MALFORMED_RESPONSE`
: The remote server responded with a payload that does not comply with HTTP specifications.

## Permissions
Expand All @@ -236,11 +236,30 @@ If you are using the [custom role feature][14], add your user to any custom role

### Restrict access

Access restriction is available for customers using [custom roles][15] on their accounts.
{{< img src="synthetics/settings/grace_1.png" alt="Set permissions for your test" style="width:70%;" >}}

Use [granular access control][18] to limit who has access to your test based on roles, teams, or individual users.

To do so:

1. Open the permissions section of the form
2. Click on `edit access`

{{< img src="synthetics/settings/grace_2.png" alt="Set permissions for your test" style="width:70%;" >}}

3. Click on `restrict access`
4. Select teams, roles, or users
5. Click `add`
6. Select the level of access you want to associate with each of them
7. Click on done

You can restrict access to an HTTP test based on the roles in your organization. When creating an HTTP test, choose which roles (in addition to your user) can read and write your test.
| Access level | View test configuration | Edit test configuration | View test results | Run test |
| ------------ | ----------------------- | ----------------------- | ------------------| --------- |
| No access | | | | |
| Viewer | {{< X >}} | | {{< X >}} | |
| Editor | {{< X >}} | {{< X >}} | {{< X >}} | {{< X >}} |

{{< img src="synthetics/settings/restrict_access_1.png" alt="Set permissions for your test" style="width:70%;" >}}
<div class="alert alert-info"><strong>Note</strong>: You will be able to see results from Private Location even if you don't have Viewer access to that Private Location.</div>

## Further Reading

Expand All @@ -263,3 +282,4 @@ You can restrict access to an HTTP test based on the roles in your organization.
[15]: /account_management/rbac/#create-a-custom-role
[16]: /synthetics/api_tests/errors/#http-errors
[17]: /api_catalog
[18]: /account_management/rbac/granular_access
Loading
Loading