/dt-obs-ext-monitors

name: dt-obs-ext-monitors
description: >-
  3rd-party test and monitor result ingestion into Dynatrace Grail via the platform events
  ingest API (platform/ingest/custom/events/). Use when sending external synthetic test outcomes,
  CI monitor data, or third-party check results to Dynatrace. Covers token scope, full event
  schema for external_test_run and external_test_step (including dt.security_context, ci.*,
  trace correlation, and pipeline-added fields), curl and Java DTO examples, and DQL verification.
  Triggers: "ingest test results", "send monitor results", "third party monitor",
  "external test ingestion", "send synthetic results to Grail", "external test run event schema".
  Not for Dynatrace-native Synthetic Monitoring browser/HTTP checks, or RUM (use dt-obs-frontends).
  For migrating from the deprecated POST /api/v1/synthetic/ext/tests API, load dt-upgrade instead.
license: Apache-2.0

External Monitor Ingestion

Send 3rd-party test and monitor results to Dynatrace Grail using the events ingest API. This is the canonical replacement for the deprecated `POST /api/v1/synthetic/ext/tests` endpoint.

Overview

Events posted to `/platform/ingest/custom/events/{endpoint}` land in Grail and are processed by OpenPipeline, which:

• Extracts metrics (`external.test.availability`, `external.test.duration`) for alerting and SLOs
• Registers each unique `test.id` as an `EXT_TEST` Smartscape node — enabling Davis Problems to

attach to a named entity ("External test X went down") rather than floating without topology context

• Adds `result.status.category` to step events (`SUCCESS` / `SKIPPED` / `FAIL`) for dashboard filtering

Two event types form a test result:

| Type | Purpose | |------|---------| | `external_test_run` | Overall pass/fail result for one test execution | | `external_test_step` | One step within that run (optional; enables step-level metrics) |

Authentication

Two token types are accepted:

| Token type | Scope | |------------|-------| | Classic Api-Token | `openpipeline.events.custom` | | Platform Token / OAuth | `openpipeline:events.custom:ingest` |

Common wrong guess that does NOT work: `events.ingest`.

Quick Start

> **Prerequisite:** The ingest endpoint must be created in OpenPipeline before sending events. > The `external.tests` endpoint is provisioned automatically by the > default Dynatrace 3rd-party monitors Monaco bundle. > See `references/event-ingestion.md` for setup details and custom endpoint creation.

Send one minimal test result (replace `external.tests` with your configured endpoint name):

curl -X POST "https://{env-id}.live.dynatrace.com/platform/ingest/custom/events/external.tests" \
  -H "Authorization: Api-Token {token}" \
  -H "Content-Type: application/json" \
  -d '[{
    "event.kind": "EXTERNAL_TEST_EVENT",
    "event.type": "external_test_run",
    "test.id": "my-api-health-check",
    "test.run.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "test.name": "My API Health Check",
    "test.type": "api",
    "test.run.status": "passed",
    "test.run.availability": 1,
    "test.run.duration_ms": 245,
    "test.run.location": "us-east-1",
    "dt.security_context": "team-checkout",
    "timestamp": "2024-01-15T10:30:00Z"
  }]'

**Expected response:** HTTP 200 (empty body).

> Full event schema, step events, extended examples with error fields and CI metadata, > Java DTO shapes, and DQL queries: `references/event-ingestion.md`

Verify in Grail

After sending, confirm the event appears:

fetch events, from:now()-1h
| filter event.type == "external_test_run"
| fields timestamp, test.id, test.name, test.run.status, test.run.duration_ms, test.run.location
| sort timestamp desc
| limit 20

Key Constraints

• Body **must** be a JSON array (`[{...}]`), not an object wrapper (`{"events":[...]}`).
• A single request can mix run events and step events in the same array.
• `timestamp` must be ISO 8601 UTC (e.g. `"2024-01-15T10:30:00Z"`).
• `test.run.availability` must be integer `1` or `0`, not a string.
• All step events in a run must share the same `test.run.id` and `test.id` as the parent run event.
• Step events must include `test.step.id` (unique within the run) in addition to `test.run.id`.
• `event.kind: "EXTERNAL_TEST_EVENT"` must be present — used by Grail for event classification.

Routing to the correct pipeline is driven by `event.type`, not `event.kind`.

• Do **not** send `dt.smartscape.ext_test` or `result.status.category` — these are written by

the pipeline after ingestion and will be overwritten if included.

• `dt.security_context` controls data access policies; it’s recommended to set it on every event to enable

per-team access control and cost attribution in multi-team tenants.

Multi-Location Tests

Send the same `test.id` from multiple locations — each with a different `test.run.location` value — to build a multi-location test. OpenPipeline creates one `EXT_TEST` node per `test.id` and one availability metric timeseries per `(test.id, location)` pair.

This enables two alerting tiers out of the box:

| Alert type | Fires when | |------------|-----------| | Local outage | A single location's availability drops (per-location timeseries) | | Global outage | Average across all locations drops below threshold (e.g. majority failing) |

Threshold maths for a 3-location test: 1 location failing → avg 0.67 (no alert at 0.5 threshold); 2 failing → avg 0.33 (fires); all 3 failing → avg ≈ 0 (fires immediately).

Keep `test.id` stable across all locations — changing it creates a new Smartscape node and breaks metric history.

Related Skills

• **dt-dql-essentials** — DQL syntax for querying ingested events and building analysis queries
• **dt-obs-frontends** — Link test runs to frontend entities via `dt.smartscape.frontend` to

draw EXT_TEST → FRONTEND dependency edges in Smartscape