On-demand synthetic monitor executions for CI/CD

There is a mandatory gap per user of 60 seconds between consecutive on-demand executions of a monitor from the same location (whether triggered via the web UI or API).

When triggering multiple on-demand executions via the API, there is a limit of 100 executions per batch.

There's also a limit of 5000 on-demand executions per minute for a Dynatrace environment.

You can define up to 64 key-value pairs of metadata per batch, where keys and values can each be up to 1024 characters.

When specifying repeated on-demand executions per location, the maximum execution count is 10.

The ability to execute multiple monitors on demand (batch execution) by specifying monitor IDs, and, optionally, location IDs. If you don't specify locations, a monitor is executed from all assigned locations. This ability is only available via API.

The ability to execute monitors from any location. In the POST request for triggering on-demand executions, each specified monitor is executed from the specified locations (or all assigned locations if none are specified).

ActiveGate version 1.259+ The ability to specify an execution count for repeated executions per location, which is helpful for quality gates and load tests. This ability is only available via API. The executionCount parameter allows you to specify the number of executions per location for each monitor; the maximum value is 10; if there is no value, the monitor is executed once per location. Executions can be triggered sequentially (repeatMode is SEQUENTIAL) or in parallel (repeatMode is PARALLEL). The default mode is sequential.

In sequential mode, each execution automatically references the following execution, if any, with the nextExecutionId parameter. When you trigger multiple sequential executions on a location, the first execution is in the Triggered stage while the others are marked Waiting. Executions on each location are independent of each other.

ActiveGate version 1.259+ The ability to partially override the monitor script and provide custom parameter values specifically for on-demand execution, which simplifies the reconfiguration and testing of synthetic monitors. This ability is only available via API. The customizedScript parameter allows you to list requests (HTTP monitors) or events (browser monitors) with customizations per request or event. For HTTP monitors, you see which parameters had custom values when you Analyze execution details.

You can optionally specify a sequenceId for the order of the request or event in the monitor script. For example, use "sequenceId": "3" to specify changes to the third event in a browser monitor. If you don't specify a sequenceId, the modifications apply to the first request or event that hasn't been referenced by a sequence ID in the API request. See examples below.

{
  "monitors": [
    {
      "monitorId": "HTTP_CHECK-C608F75BF82E5B22",
      "customizedScript": {
        "requests": [
          {
            "url": "https://www.yourdomain.com"
          }
        ]
      }
    }
  ]
}

{
  "monitors": [
    {
      "monitorId": "HTTP_CHECK-6349B98E1CD87352",
      "customizedScript": {
        "requests": [
          {
            "url": "https://www.somepage.org",
            "preProcessingScript": "if (response.getResponseBody().includes(\"error\")) {api.fail(\"HTTP failing monitor.\");}"
          },
          {
            "sequenceId": "3",
            "validation": {
              "rules": [
                {
                  "value": "=201",
                  "passIfFound": "true"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

{
  "takeScreenshotsOnSuccess": true,
  "monitors": [
    {
      "monitorId": "SYNTHETIC_TEST-114F1C18CF07CD1D",
      "customizedScript": {
        "events": [
          {
            "type": "navigate",
            "url": "www.yourdomain.com"
          }
        ]
      }
    }
  ]
}

The ability to execute a group of monitors on demand by specifying common tags and/or IDs of related services or applications. Note that all specified conditions must match for a monitor to be executed on demand. This ability is only available via API.

If you specify three monitors by ID and one tag in your POST request, each of the three monitors plus all monitors matching the tag will be executed.

Automatic assignment of a batch ID for all executions of the POST method, whether for a single monitor or multiple monitors. This enables the retrieval of results by batch ID as well.

The ability to define custom key-value pairs, for example, to identify application versions, as part of batch metadata. This ability is only available via API. You can define up to 64 pairs per batch, where keys and values can each be up to 1024 characters. Key-value metadata is available in individual as well as batch execution results retrieved via the API and is displayed in the web UI.

The capture of screenshots upon success for browser monitors from public or private locations by setting "takeScreenshotsOnSuccess": true in the POST request (the default is false). Screenshots upon success are captured from the first location specified for each monitor ID. If no location is specified (for example, when you use tags to define a list of monitors), screenshots are captured from any of the locations assigned to a monitor.

Note that screenshots are automatically captured upon failure. But if a monitor fails because of a performance threshold violation, it's still considered available, and no screenshots are captured; however, you can enable takeScreenshotsOnSuccess.

The ability to fail an on-demand HTTP monitor execution if the SSL certificate is missing, expired, or expiring (failOnSslWarning parameter.)

The ability to stop triggering all executions in a batch if there is a problem with triggering any execution (stopOnProblem parameter), for example, if the monitor ID is incorrect/missing or the monitor is deleted. This ability is only available via API.

Retrieval of the list of on-demand executions (triggered via the web UI or API by all users in your environment) in the preceding six hours. The list includes execution IDs for each execution. You can filter this list by:

Retrieval of the basic as well as more detailed results of an execution (for which you provide an execution ID).

Basic results are best suited for CI/CD purposes and include the number of requests/events executed, success/failure result, and some key metrics. For example, basic results for HTTP monitors report total request size (for all requests taken together), time to first byte, TLS handshake time, TCP connect time, DNS lookup time, and the final HTTP status code.

Detailed results are more suitable for troubleshooting. For HTTP monitors, this is the entire set of results visible in the web UI when you opt to Analyze execution details.

Batch retrieval of results when you provide a batch ID.

Batch results include information on executions that were triggered and those that resulted in an outcome.

Note that the executedCount is the number of executions that resulted in success or failure. failedToExecuteCount is the number of executions that were triggered but for which results are not available for technical reasons (such as a problem with the ActiveGate or Synthetic engine or results that could not be sent to the Dynatrace Cluster). executedCount + failedToExecuteCount = triggeredCount.

Granular permissions for triggering and retrieving data for on-demand executions.

To trigger executions (POST), you need rights to create monitors (ExternalSyntheticIntegration token scope) or the syntheticExecutions.write token scope, which enables you to trigger executions but not create new monitors.

To retrieve data (GET), you need any of the ExternalSyntheticIntegration, ReadSyntheticData, or syntheticExecutions.read token scopes.