dt-obs-ext-monitors

用途

该技能用于将第三方测试和监控结果发送到 Dynatrace Grail，通过平台事件摄取 API 完成数据上报。它是已弃用的 POST /api/v1/synthetic/ext/tests 端点的正式替代方案。

主要能力

事件发布到 /platform/ingest/custom/events/{endpoint} 后会落到 Grail 并由 OpenPipeline 处理：

提取指标（external.test.availability、external.test.duration）用于告警和 SLO。
将每个唯一的 test.id 注册为 EXT_TEST Smartscape 节点，使 Davis 问题能够附着到具名实体（如“External test X went down”），而不是缺少拓扑上下文地漂浮。
为步骤事件添加 result.status.category（SUCCESS / SKIPPED / FAIL），便于仪表盘筛选。

构成一次测试结果的事件类型有两种：

external_test_run：一次测试执行的总体通过/失败结果。
external_test_step：该次运行中的一个步骤（可选；启用步骤级指标）。

认证

接受两种令牌类型：

Classic Api-Token，作用域为 openpipeline.events.custom。
Platform Token / OAuth，作用域为 openpipeline:events.custom:ingest。

常见错误猜测是 events.ingest，该值无效。

使用方式

前提条件：发送事件前必须在 OpenPipeline 中创建摄取端点。external.tests 端点由默认的 Dynatrace 第三方监控 Monaco bundle 自动预置，设置细节和自定义端点创建参见 references/event-ingestion.md。

发送一条最小测试结果的示例（将 external.tests 替换为你配置的端点名）：

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（空 body）。

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

在 Grail 中验证

发送后确认事件已出现：

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

关键约束

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

多位置测试

从多个位置发送相同的 test.id，每个位置使用不同的 test.run.location 值，即可构建多位置测试。OpenPipeline 为每个 test.id 创建一个 EXT_TEST 节点，并为每个 (test.id, location) 对创建一条可用性指标时间序列。

这开箱即用地支持两级告警：

本地故障：单个位置的可用性下降时触发（按位置的时间序列）。
全局故障：所有位置的平均值低于阈值时触发（如多数失败）。

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

在所有位置间保持 test.id 稳定——更改它会创建新的 Smartscape 节点并破坏指标历史。

技能介绍

用途