dt-obs-ext-monitors

外部监控数据采集

使用事件摄取 API，将第三方测试和监控结果发送到 Dynatrace Grail。 这是已弃用的 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 问题能够关联到具名实体（“外部测试 X 已中断”），而非因缺少拓扑上下文而悬空
• 为步骤事件添加 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 中创建摄取端点。 默认 Dynatrace 3rd-party monitors Monaco 包会自动配置 external.tests 端点。 有关设置详情和自定义端点创建，请参阅 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（空响应正文）。

完整事件架构、步骤事件、包含错误字段和 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":[...]}）。
• 单个请求的数组中可以混合运行事件和步骤事件。
• 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 控制数据访问策略；建议在每个事件中设置该字段，以便在多团队租户中启用按团队访问控制和成本归属。

多地点测试

从多个地点发送相同的 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 节点，并中断指标历史记录。

相关技能

• dt-dql-essentials — 用于查询已摄取事件和构建分析查询的 DQL 语法
• dt-obs-frontends — 通过 dt.smartscape.frontend 将测试运行关联到前端实体，以便在 Smartscape 中绘制 EXT_TEST → FRONTEND 依赖边