dt-obs-ext-monitors

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过事件导入API将第三方测试和监控结果发送至Dynatrace Grail。这是已弃用的

POST /api/v1/synthetic/ext/tests

端点的标准替代方案。

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)

发送至

/platform/ingest/custom/events/{endpoint}

的事件将存入Grail并由OpenPipeline处理，处理内容包括：

提取指标（

external.test.availability

、

external.test.duration

）用于告警和SLO

将每个唯一的
```
test.id
```
注册为
```
EXT_TEST
```
Smartscape节点——使Davis Problems可以关联到具体命名实体（如"外部测试X已中断"），而非脱离拓扑上下文的孤立事件
为步骤事件添加
```
result.status.category
```
（
```
SUCCESS
```
/
```
SKIPPED
```
/
```
FAIL
```
），以便在仪表板中进行筛选

测试结果由两种事件类型构成：

类型	用途
`external_test_run`	单次测试执行的整体通过/失败结果
`external_test_step`	该测试执行中的单个步骤（可选；支持步骤级指标）

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

支持两种令牌类型：

令牌类型	权限范围
Classic Api-Token	`openpipeline.events.custom`
Platform Token / OAuth	`openpipeline:events.custom:ingest`

常见错误猜测：

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):

text

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

前提条件： 在发送事件前，必须在OpenPipeline中创建导入端点。
external.tests
端点由默认的Dynatrace第三方监控Monaco包自动配置。有关设置详情和自定义端点创建，请参阅
references/event-ingestion.md
。

发送一个最简测试结果（将

external.tests

替换为你配置的端点名称）：

text

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"
  }]'

预期响应： HTTP 200（空响应体）。

完整事件schema、步骤事件、包含错误字段和CI元数据的扩展示例、Java DTO结构以及DQL查询，请参阅
references/event-ingestion.md

Verify in Grail

在Grail中验证

After sending, confirm the event appears:

dql

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

发送事件后，确认事件已存在：

dql

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.

请求体必须是JSON数组（
```
[{...}]
```
），而非对象包装器（
```
{"events":[...]}
```
）。
单个请求可在同一数组中混合运行事件和步骤事件。
```
timestamp
```
必须为ISO 8601 UTC格式（例如
```
"2024-01-15T10:30:00Z"
```
）。
```
test.run.availability
```
必须为整数
```
1
```
或
```
0
```
，不能是字符串。
同一运行中的所有步骤事件必须与父运行事件共享相同的
```
test.run.id
```
和
```
test.id
```
。
步骤事件除
```
test.run.id
```
外，还必须包含
```
test.step.id
```
（在运行内唯一）。
必须包含
```
event.kind: "EXTERNAL_TEST_EVENT"
```
——Grail用它进行事件分类。路由到正确流水线由
```
event.type
```
驱动，而非
```
event.kind
```
。
请勿发送
```
dt.smartscape.ext_test
```
或
```
result.status.category
```
——这些字段会在导入后由流水线写入，若自行传入会被覆盖。
```
dt.security_context
```
控制数据访问策略；建议在每个事件中设置该字段，以便在多团队租户中实现按团队访问控制和成本归因。

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.

从多个位置发送相同的

test.id

——每个位置使用不同的

test.run.location

值——以构建多位置测试。OpenPipeline会为每个

test.id

创建一个

EXT_TEST

节点，并为每个

(test.id, location)

对创建一条可用性指标时间序列。

这默认支持两个告警层级：

告警类型	触发条件
本地中断	单个位置的可用性下降（基于单位置时间序列）
全局中断	所有位置的平均可用性低于阈值（例如多数位置失败）

以3个位置的测试为例计算阈值：1个位置失败→平均0.67（0.5阈值下不告警）； 2个位置失败→平均0.33（触发告警）；3个位置全部失败→平均≈0（立即触发告警）。

在所有位置保持

test.id

稳定——修改它会创建新的Smartscape节点并中断指标历史。