APM API

NOW=$(date +%s)000000
curl --get 'http://localhost:5080/api/v1/apm/overview' \
  --header "Authorization: Bearer $MS_JWT" \
  --data-urlencode "from=$((NOW-86400000000))" \
  --data-urlencode "to=$NOW" \
  --data-urlencode 'environment=production' \
  --data-urlencode 'resolution=auto'

{
  "meta": { "resolution": "minute", "data_quality": { "partial": false } },
  "items": [
    {
      "service": { "namespace": "shop", "name": "payments", "environment": "production" },
      "first_seen_at": 1790000000000000,
      "last_seen_at": 1790003600000000,
      "instrumentation": {
        "runtime_language": null,
        "telemetry_sdk_name": null,
        "telemetry_sdk_version": null,
        "recent_instance_count": 0
      },
      "versions": [],
      "red": {
        "request_count": 2,
        "error_count": 2,
        "error_rate": 1.0,
        "duration_sum_micros": 230000,
        "duration_average_micros": 115000,
        "p50_micros": 128000,
        "p95_micros": 256000,
        "p99_micros": 256000,
        "latency_partial": false,
        "exemplars": [
          {
            "trace_id": "0af7651916cd43dd8448eb211c80319c",
            "span_id": "53995c3f42cd8ad8",
            "event_time": 1790000000000000,
            "duration_micros": 140000,
            "trace_available": true
          }
        ]
      },
      "health": "critical",
      "traces": {
        "namespace": "shop",
        "service": "payments",
        "environment": "production",
        "version": null,
        "transaction": null,
        "dependency": null,
        "error_fingerprint": null,
        "from": 1789996400000000,
        "to": 1790003600000000
      }
    }
  ],
  "next_cursor": null,
  "previous_cursor": null,
  "has_more": false,
  "sort": "p95"
}

NOW=$(date +%s)000000
curl --get 'http://localhost:5080/api/v1/apm/overview' \
  --header "Authorization: Bearer $MS_JWT" \
  --data-urlencode "from=$((NOW-86400000000))" \
  --data-urlencode "to=$NOW" \
  --data-urlencode 'environment=production' \
  --data-urlencode 'resolution=auto'

{
  "meta": { "resolution": "minute", "data_quality": { "partial": false } },
  "items": [
    {
      "service": { "namespace": "shop", "name": "payments", "environment": "production" },
      "first_seen_at": 1790000000000000,
      "last_seen_at": 1790003600000000,
      "instrumentation": {
        "runtime_language": null,
        "telemetry_sdk_name": null,
        "telemetry_sdk_version": null,
        "recent_instance_count": 0
      },
      "versions": [],
      "red": {
        "request_count": 2,
        "error_count": 2,
        "error_rate": 1.0,
        "duration_sum_micros": 230000,
        "duration_average_micros": 115000,
        "p50_micros": 128000,
        "p95_micros": 256000,
        "p99_micros": 256000,
        "latency_partial": false,
        "exemplars": [
          {
            "trace_id": "0af7651916cd43dd8448eb211c80319c",
            "span_id": "53995c3f42cd8ad8",
            "event_time": 1790000000000000,
            "duration_micros": 140000,
            "trace_available": true
          }
        ]
      },
      "health": "critical",
      "traces": {
        "namespace": "shop",
        "service": "payments",
        "environment": "production",
        "version": null,
        "transaction": null,
        "dependency": null,
        "error_fingerprint": null,
        "from": 1789996400000000,
        "to": 1790003600000000
      }
    }
  ],
  "next_cursor": null,
  "previous_cursor": null,
  "has_more": false,
  "sort": "p95"
}

APM API 提供从 trace span 派生的组织范围聚合。所有端点都使用 /api/v1/apm 前缀，并要求 Bearer Token。

Authorization: Bearer <token>

组织工作区需要 streams.query。平台调用方在受保护的 _sys 范围可以使用 sys.telemetry.read。写入服务定义、错误状态、服务等级目标和 APM 设置需要 apm.manage。上报发布需要 apm.deploy。

端点

方法与路径	响应内容
`GET /api/v1/apm/overview`	所有服务的 RED 汇总与趋势、服务健康及其趋势、排行、部署、环境、埋点缺失，以及 Top 事务、依赖和错误。
`GET /api/v1/apm/insights`	和上一时段、上周同时段相比有变化的指标，比上一个版本差的版本，可以省下时间的地方，以及每条发现附近的变更。
`GET /api/v1/apm/services`	分页服务目录，包括埋点信息、版本、健康、RED 指标与链路过滤条件。
`GET /api/v1/apm/services/{service}`	服务汇总、趋势、事务、依赖、错误与版本。
`GET /api/v1/apm/services/{service}/instances`	某个环境中服务的实例，含版本、资源属性和每个实例处理的请求情况。
`GET /api/v1/apm/services/{service}/coverage`	在 `to` 之前的一天内，服务的日志、指标、Profiles 和浏览器会话是否接入了 MoleSignal。
`GET /api/v1/apm/transactions`	分页事务 RED 指标与总耗时排名。
`GET /api/v1/apm/transactions/{transaction}`	事务趋势、相关错误、版本与链路过滤条件。
`GET /api/v1/apm/dependencies`	分页调用方/依赖 RED 指标与总耗时排名。
`GET /api/v1/apm/map`	一个环境和命名空间的服务地图：服务、它们调用的对象、Topic，以及相互之间的调用。
`GET /api/v1/apm/map/edge`	地图上的一条调用：它的趋势、沿它访问的内容，以及被调服务的错误。
`GET /api/v1/apm/blast-radius`	服务沿地图影响到的范围：调用它的和它调用的，逐层列出。
`GET /api/v1/apm/errors`	分页且已脱敏的后端错误组，以及所列分组发生的分布。
`GET /api/v1/apm/errors/{fingerprint}`	错误趋势、相关事务与版本、分组发生的分布、代表性栈和有界样本。
`GET /api/v1/apm/versions/compare`	基线和候选 RED 指标、差异、数据充足状态与回退项。
`GET /api/v1/apm/health`	租户投影状态、运行健康、边界与缺口。
`GET /api/v1/apm/service-definitions`	组织的全部服务定义。
`PUT /api/v1/apm/service-definitions/{service}?namespace=`	创建或替换服务定义。需要 `apm.manage`。
`DELETE /api/v1/apm/service-definitions/{service}?namespace=`	删除服务定义。需要 `apm.manage`。
`POST /api/v1/apm/service-definitions/{service}/key-transactions?namespace=`	把端点标为服务的关键事务，或取消标记。需要 `apm.manage`。
`PUT /api/v1/apm/errors/{fingerprint}/issue`	设置错误分组的状态、团队和处理人。需要 `apm.manage`。
`GET /api/v1/apm/error-rules`	组织的错误聚合规则，按匹配顺序排列。
`POST /api/v1/apm/error-rules`	新建聚合规则，排在已有规则之后。需要 `apm.manage`。
`PUT /api/v1/apm/error-rules/{id}`	替换一条聚合规则。需要 `apm.manage`。
`DELETE /api/v1/apm/error-rules/{id}`	删除一条聚合规则。需要 `apm.manage`。
`PUT /api/v1/apm/error-rules/order`	设置规则的匹配顺序。需要 `apm.manage`。
`GET /api/v1/apm/slos`	所有服务等级目标及其状态、达成率、剩余错误预算和燃烧率。
`GET /api/v1/apm/slos/{id}`	单个服务等级目标的状态，以及窗口内每天的情况。
`POST /api/v1/apm/slos`	创建服务等级目标。需要 `apm.manage`。
`PUT /api/v1/apm/slos/{id}`	替换服务等级目标。需要 `apm.manage`。
`DELETE /api/v1/apm/slos/{id}`	删除服务等级目标。需要 `apm.manage`。
`POST /api/v1/apm/deployments`	上报一次发布。需要 `apm.deploy`。
`GET /api/v1/apm/deployments`	流水线上报的发布，按时间从新到旧。
`GET /api/v1/apm/settings`	组织的 APM 设置，未保存过时返回默认值。
`PUT /api/v1/apm/settings`	替换组织的 APM 设置。需要 `apm.manage`。

路径参数必须经过 URL 编码。请使用列表响应返回的准确 transaction 名称或错误 fingerprint。

通用查询参数

参数	类型	行为
`from`	integer	Unix 纪元以来的微秒级开始时间。默认是 `to` 之前 24 小时。
`to`	integer	Unix 纪元以来的微秒级结束时间。默认为当前时间。
`namespace`	string	精确匹配服务命名空间。
`service`	string	精确匹配服务名。服务详情路径中的值会覆盖该参数。
`environment`	string	精确匹配部署环境。
`version`	string	精确匹配服务版本。
`resolution`	enum	`auto`、`minute` 或 `hour`。`auto` 会按范围选择可用分辨率。
`sort`	string	端点支持的排序字段。
`direction`	enum	`asc` 或 `desc`，默认为 `desc`。
`limit`	integer	1 到 200 的每页条数，默认为 50。
`cursor`	string	上一个列表响应返回的不透明游标。
`status`	enum	仅 `/errors`：`all`（默认）、`unresolved`（待处理、调查中，以及已解决后再次出现的分组）、`investigating`、`resolved` 或 `ignored`。

过滤值不能为空，且不能超过 192 字节。查询范围不能超过配置的最大值，默认是 30 天（[apm].max_query_range_days）。

排序字段

端点	支持的 `sort` 值	默认值
`/services`	`request_count`、`error_rate`、`p95`、`name`	`request_count`
`/transactions`	`request_count`、`error_rate`、`p95`、`total_time`	`request_count`
`/dependencies`	`request_count`、`error_rate`、`p95`、`total_time`	`total_time`
`/errors`	`occurrence_count`、`error_rate`、`last_seen`	`occurrence_count`

/overview 接受相同过滤条件与分辨率，但不分页。详情、版本对比和健康端点也不返回分页列表。

查询概览

NOW=$(date +%s)000000
curl --get 'http://localhost:5080/api/v1/apm/overview' \
  --header "Authorization: Bearer $MS_JWT" \
  --data-urlencode "from=$((NOW-86400000000))" \
  --data-urlencode "to=$NOW" \
  --data-urlencode 'environment=production' \
  --data-urlencode 'resolution=auto'

响应包含 red、trend、service_health、services、top_transactions、top_dependencies、top_errors 和 recent_versions，以及通用 meta 对象，另外还有：

字段	说明
`service_count`、`active_service_count`	时间范围内出现过的服务数，以及其中有请求的服务数。
`health_trend`	每个时间段里各状态的服务数：时间范围最多分成 48 段，每段不短于一个时间桶。某段内没有请求的服务在该段计为 `no_traffic`。
`rankings`	`slowest`（按 p95）、`most_errors`（按错误率）和 `busiest`（按请求数），各 5 个服务。前两项只列请求数不少于 20 的服务。
`deployments`	时间范围内首次出现的版本，最新的在前，最多 20 个。每个版本带有 `red` 和 `verdict`，含义同服务的版本。
`environments`、`available_environments`	当前视图内每个环境的服务数和请求数，以及不受 `environment` 过滤影响的全部环境。
`instrumentation`	按语言和 SDK 统计的服务数，以及没有上报 `deployment.environment`、`service.version` 或 `service.instance.id` 的服务数。

读取洞察

GET /api/v1/apm/insights 接收通用的时间范围和过滤参数，返回 meta 以及：

字段	说明
`now`、`previous`、`last_week`	当前视图内的服务在时间范围内、之前同样长的一段时间内，以及上周同时段内的数据：`request_count`、`throughput`（每秒请求数）、`error_rate`、`p95_micros` 和 `apdex`。没有请求的时间段省略。
`insights`	最多 30 条发现，最需要关注的在前。

每条发现包含：

字段	说明
`kind`	`anomaly`、`regression`、`slow_dependency`、`repeated_call`、`slow_query` 或 `hot_endpoint`。
`severity`	`critical`、`warning`，建议为 `info`。
`service`	`namespace`、`name` 和 `environment`。
`transaction`、`dependency`	热点端点的端点；瓶颈、重复调用或慢语句对应的依赖。
`metric`	变化或变差的指标：`error_rate`、`p95` 或 `throughput`。
`value`	现在的值：错误率为比值，P95 单位为微秒，吞吐为每秒请求数。瓶颈和热点端点为耗时占比，重复调用为每个请求的调用次数，慢语句为以微秒计的 P95。
`previous`、`last_week`	同一指标在上一时段和上周同时段的值；版本变差时为上一个版本的值。
`since`	突变开始的时间，或变差的版本首次出现的时间。
`version`、`previous_version`	变差的版本和它之前的版本。
`calls`、`p95_micros`	建议所依据的调用数或请求数，以及它们的 P95。
`changes`	`since` 附近的变更，最近的在前：`kind`、`source`（`reported` 或 `observed`）、`service`、`version`、`status`、`at`、`downstream`（变更属于突变服务调用的服务时为 `true`）、`commit` 和 `description`。

判断条件见洞察与调查。

列出服务并分页

curl --get 'http://localhost:5080/api/v1/apm/services' \
  --header "Authorization: Bearer $MS_JWT" \
  --data-urlencode 'namespace=shop' \
  --data-urlencode 'environment=production' \
  --data-urlencode 'sort=p95' \
  --data-urlencode 'direction=desc' \
  --data-urlencode 'limit=50'

分页响应的结构如下，items 中每个服务对应一个条目：

{
  "meta": { "resolution": "minute", "data_quality": { "partial": false } },
  "items": [
    {
      "service": { "namespace": "shop", "name": "payments", "environment": "production" },
      "first_seen_at": 1790000000000000,
      "last_seen_at": 1790003600000000,
      "instrumentation": {
        "runtime_language": null,
        "telemetry_sdk_name": null,
        "telemetry_sdk_version": null,
        "recent_instance_count": 0
      },
      "versions": [],
      "red": {
        "request_count": 2,
        "error_count": 2,
        "error_rate": 1.0,
        "duration_sum_micros": 230000,
        "duration_average_micros": 115000,
        "p50_micros": 128000,
        "p95_micros": 256000,
        "p99_micros": 256000,
        "latency_partial": false,
        "exemplars": [
          {
            "trace_id": "0af7651916cd43dd8448eb211c80319c",
            "span_id": "53995c3f42cd8ad8",
            "event_time": 1790000000000000,
            "duration_micros": 140000,
            "trace_available": true
          }
        ]
      },
      "health": "critical",
      "traces": {
        "namespace": "shop",
        "service": "payments",
        "environment": "production",
        "version": null,
        "transaction": null,
        "dependency": null,
        "error_fingerprint": null,
        "from": 1789996400000000,
        "to": 1790003600000000
      }
    }
  ],
  "next_cursor": null,
  "previous_cursor": null,
  "has_more": false,
  "sort": "p95"
}

请把 next_cursor 或 previous_cursor 原样传回同一个端点，并保持过滤条件、时间范围、排序字段和方向不变。游标带签名并绑定原始请求上下文，不要解码或修改。条目中的 traces 对象重述了该条目的服务、版本、事务、依赖和错误过滤条件以及时间范围，客户端可据此打开对应的链路。

读取 RED 指标

每个汇总都带有 red 对象，包含范围内的请求、错误和耗时数据。

字段	说明
`request_count`、`error_count`、`error_rate`	请求数、失败请求数，以及两者的比值（0 到 1）。
`duration_sum_micros`、`duration_average_micros`	总耗时与平均耗时，单位为微秒。没有请求时平均值为 `null`。
`p50_micros`、`p90_micros`、`p95_micros`、`p99_micros`	延迟百分位，单位为微秒，在名次所在的直方图桶内插值读出。默认分桶下与精确耗时的误差约 ±4%。没有请求时为 `null`。
`apdex`	不超过阈值 T 的请求加上不超过 4T 的请求的一半，除以全部请求，取值 0 到 1。T 取服务的 `apdex_threshold_micros`，未设置时为 500 ms；概览中所有服务合在一起的指标按 500 ms 计算。出错的请求一律不算满意。没有请求时为 `null`。
`latency_partial`	部分时间桶使用了无法识别的延迟分桶时为 `true`。早期分桶（`[apm.histogram].schema_version`）写入的时间桶会被换算后计入。百分位会排除无法读取的时间桶，而计数、总和与平均值仍然包含它们。
`timeout_count`、`retry_count`	超时的请求（错误类型为超时、gRPC `DEADLINE_EXCEEDED`、HTTP 408 或 504）和重发的请求（`http.request.resend_count` 大于 0）。为 0 时省略。
`status_codes`	按状态码统计的响应，键为 `http:<状态码>`（100 到 599）或 `grpc:<状态码>`（0 到 16）。每个分桶最多记录 24 个状态码，更多的计入 `http:other` 或 `grpc:other`。没有统计到状态码时省略，例如开始统计之前写入的聚合。
`exemplars`	范围内最多 8 个示例 Span，耗时最长的在前。Span 在尾部采样对其链路做出决定之前就已投影，所以 `trace_available` 通常为 `false`；要知道链路是否保留，请查询该链路。聚合结果仍然有效。

服务摘要和事务摘要带有 apdex_threshold_micros，即计算 Apdex 时使用的 T。服务摘要还带有 health 和 health_reasons：每项超过阈值的指标，含 metric（error_rate 或 p95）、level、value 和 threshold。服务摘要还带有 sparkline（每个时间桶的请求数、错误数和 p95），以及 current_version 和 current_version_since（最近出现的版本及其首次出现时间）。服务或事务详情带有 latency_distribution：包含请求的直方图桶，每个为 lower_micros、upper_micros 和 count，并收窄到最快和最慢的请求。

维护服务定义

服务定义记录服务归谁负责、有多重要。它按 namespace 和服务名保存，在所有环境中都适用，并且可以在服务上报之前存在。

PUT /api/v1/apm/service-definitions/checkout?namespace=shop
Content-Type: application/json

{"description": "处理下单与支付。", "team_id": "<team id>", "owner_id": "<user id>", "tier": "p0", "lifecycle": "production", "repository_url": "https://github.com/acme/checkout", "tags": {"domain": "orders", "pci": ""}, "apdex_threshold_micros": 300000, "archived": false}

字段	说明
`description`	最多 2,000 个字符。
`team_id`	组织内的团队，或 `null`。删除团队后会被清空。
`owner_id`	组织成员，或 `null`。
`tier`	`p0`（最重要）到 `p5`，或 `null`。
`lifecycle`	`production`、`staging`、`experimental`、`deprecated` 或 `null`。
`repository_url`	不含空格的 `http`、`https`、`ssh`、`git` 或 `git+ssh` 地址，或 `user@host:path` 形式的地址，最多 2,048 个字符，或 `null`。密码保存为 `**`，http(s) 地址中的用户部分也保存为 `**`。服务没有上报仓库时显示。
`tags`	最多 32 个标签，形如 `{ "key": "value" }`。key 为 1 到 64 个小写字母、数字和 `_ . - /`；value 最多 128 个字符，两端不能有空格，只有 key 时为空字符串。
`apdex_threshold_micros`	服务的 Apdex 阈值 T，大于 0 且不超过 60,000,000（一分钟），或 `null` 表示 500 ms。
`archived`	为 `true` 时服务不出现在服务目录的默认视图中。省略时，已保存的定义保持原状态。

保存不会改动定义的 key_transactions，关键事务每次只增减一个。响应是保存后的定义，含 namespace、name、key_transactions、updated_by 和 updated_at。DELETE 返回 204；服务没有定义时返回 404。

标记关键事务

POST /api/v1/apm/service-definitions/checkout/key-transactions?namespace=shop
Content-Type: application/json

{"transaction": {"name": "POST /orders", "kind": "http"}, "key": true}

key: true 把端点加入 key_transactions，false 将其移除；状态已经如此时不做任何改动。服务还没有定义时会自动创建。每个服务最多 50 个关键事务，溢出行 __other__ 不能标为关键事务。响应是改动后的定义。

读取服务的数据覆盖

GET /api/v1/apm/services/{service}/coverage 需要 namespace 和 environment，可选 to（当前时间范围的终点，单位微秒，默认为当前时间）。它查看 to 之前的一天，每个结果保留五分钟。

{
  "from": 1792230096695000,
  "to": 1792316496695000,
  "logs": { "state": "reported", "found": ["default"] },
  "metrics": { "state": "missing" },
  "profiles": { "state": "reported", "found": ["cpu", "alloc_space"] },
  "rum": { "state": "unknown" }
}

信号	为 `reported` 的条件	`found`
`logs`	某个含 `service.name`、`service_name` 或 `service` 字段的日志数据流中有这个服务的日志。最多查看八个数据流，`default` 优先。	这些数据流。
`metrics`	在 `to` 时刻，`count(last_over_time({"service.name"="<service>"}[1h]))` 大于零。	序列数。
`profiles`	Profile 数据流中有这个服务的 Profile。	Profile 类型。
`rum`	服务最近的五条样本调用链中，有一条被浏览器动作带上。	会话。

missing 表示没有找到。unknown 表示查看失败或超过三秒。rum 不会是 missing：样本调用链只能说明有会话到达服务，不能说明没有。

读取服务的运行情况

GET /api/v1/apm/services 和 GET /api/v1/apm/services/{service} 返回的每个服务摘要带有 profile，取自时间范围内上报过的实例；设置了 version 参数时只统计该版本的实例。每个列表按共享该值的实例数排序，最多 5 项，格式为 { "value": "1.8.2", "instances": 4 }。

字段	说明
`instance_count`、`host_count`	实例数和不同 `host.name` 的数量。
`versions`	实例运行的版本。灰度发布时会有两个。
`languages`、`runtimes`、`frameworks`	`telemetry.sdk.language`；`process.runtime.name` 及其版本；由入口 Span 插桩库识别出的框架。
`regions`、`clusters`、`k8s_namespaces`、`workloads`	`cloud.region`、`k8s.cluster.name`、`k8s.namespace.name`，以及 `k8s.deployment.name` 或 `k8s.statefulset.name`。
`repositories`、`commits`	`vcs.repository.url.full` 或 `git.repository_url`（去掉凭据后保存）；`vcs.ref.head.revision` 或 `git.commit.sha`。
`entry_kinds`	`http`、`rpc`、`messaging`、`span`：服务承接的入口类型。

GET /api/v1/apm/services/{service}/instances 逐个列出实例，最近上报的在前，最多 500 个。参数为 namespace、environment，以及可选的 version、from、to；缺少服务或环境时返回 400。每项包含 instance_id（依次取 service.instance.id、k8s.pod.name、host.name）、version、first_seen_at、last_seen_at、attributes（实例最后一次上报的属性），以及它在时间范围内处理的请求：red（与摘要相同，Apdex 按服务的阈值计算）和 sparkline。超过实例上限的实例合并为一项，其 instance_id 为 __other__。在保存实例信息之前就处理过请求的实例，attributes 为空。

设置错误分组的状态

PUT /api/v1/apm/errors/<fingerprint>/issue
Content-Type: application/json

{"status": "investigating", "assignee_id": "<user id>", "team_id": "<team id>", "last_seen_at": 1792316496695000}

status 为 open、investigating、resolved 或 ignored。assignee_id 为组织成员或 null，team_id 为组织中的团队或 null。last_seen_at 可选，表示调用方最后看到该分组的时间，单位为微秒。设为 resolved 时会把当前时间记为 resolved_at。错误摘要以 issue 携带状态，从未设置时为 null。已解决的分组在 resolved_at 之后再次出现时，issue.regressed 为 true，unresolved 筛选会保留这些分组。为投影不认识的指纹设置状态会返回 404。

维护服务等级目标

服务等级目标（SLO）承诺某个环境中的一个服务或其某个端点，在滚动窗口内达标请求所占的比例。各项指标的含义见服务等级目标。

POST /api/v1/apm/slos
Content-Type: application/json

{"name": "Checkout availability", "namespace": "shop", "service": "checkout", "environment": "production", "transaction": null, "kind": "availability", "objective": 0.999, "window_days": 30}

字段	说明
`name`	必填，最多 255 字节。
`description`	可选，最多 2,000 字节。
`namespace`、`service`、`environment`	必填，即 APM 中的服务名称。没有 `service.namespace` 的服务属于命名空间 `default`。
`transaction`	某个端点 `{ "name": "POST /orders", "kind": "http" }`，或用 `null` 表示整个服务。
`kind`	`availability`：请求没有失败即为达标。`latency`：请求没有失败且耗时不超过 `latency_threshold_micros` 即为达标。
`latency_threshold_micros`	`latency` 必填且为正数；`availability` 必须为 `null` 或省略。
`objective`	达标请求的比例，大于 0 且小于 1，例如 `0.999`。
`window_days`	`7`、`28` 或 `30`。

POST 和 PUT 返回保存后的 SLO，含 id、created_by、created_at、updated_by 和 updated_at。GET /api/v1/apm/slos 以状态的形式返回组织的所有 SLO；同时传入 namespace、service 和 environment 可只保留一个服务的 SLO。窗口截至调用时刻，因此不适用通用的时间范围参数。

状态字段	说明
`slo`	保存的 SLO。
`state`	`healthy`、`at_risk`、`breached` 或 `no_data`。
`sli`	窗口内达标请求数除以全部请求数；没有请求时为 `null`。
`good_requests`、`total_requests`	`sli` 背后的计数。延迟 SLO 的 `good_requests` 由延迟直方图估算，可能带小数。
`budget_remaining`	`1 - (1 - sli) / (1 - objective)`，目标被打破后低于零；没有请求时为 `null`。
`burn_rates`	`one_hour`、`six_hours` 和 `one_day`：最近 1 小时、6 小时和 24 小时的 `(1 - sli) / (1 - objective)`；没有请求时为 `null`。

GET /api/v1/apm/slos/{id} 返回 status 和 history。history 按时间从早到晚，为窗口内每个有请求的 UTC 自然日给出一项，含微秒单位的 day_start、sli、good_requests 和 total_requests。 DELETE 返回 204。仍有告警规则监控该 SLO（例如它的燃烧率告警）时返回 409，需先删除这些规则。监控 SLO 的告警规则是指标为 slo_burn_rate 的 APM 规则，见创建规则。

区分同名事务

不同事务种类可能使用相同名称。请传入可选的 kind 参数指定目标：

GET /api/v1/apm/transactions/POST%20%2Fcheckout?kind=http&service=checkout

支持的 kind 为 http、rpc、messaging、span 和 other。名称被多个服务或种类共用时，返回 400，消息为 APM transaction identity is ambiguous; provide service, namespace, environment, and kind。

比较版本

请提供两个不同的 baseline 和 candidate，并添加 service 过滤条件以比较单个服务。

curl --get 'http://localhost:5080/api/v1/apm/versions/compare' \
  --header "Authorization: Bearer $MS_JWT" \
  --data-urlencode 'service=checkout' \
  --data-urlencode 'environment=production' \
  --data-urlencode 'baseline=2.3.1' \
  --data-urlencode 'candidate=2.4.0'

响应包含 baseline 与 candidate 两侧（各有 version、sample_count 和 red），以及 delta、status、regressed_transactions 和 regressed_errors。每个回退列表最多 20 项。

字段	说明
`sufficient_data`	只有两个版本都达到配置的样本阈值时才为 `true`，默认阈值是每个版本 1,000 个请求（`[apm.version_comparison].min_requests_per_version`）。
`status`	`insufficient_data`、`regressed`、`improved` 或 `neutral`。候选版本的错误率至少上升 1 个百分点且达到基线的 1.5 倍，或 p95 至少变慢五分之一且至少 50 毫秒时为 `regressed`；其中一项下降同样幅度且没有一项变差时为 `improved`；`sufficient_data` 为 `false` 时为 `insufficient_data`。
`delta`	`request_count_absolute` 与 `request_count_relative`、`error_rate_absolute` 与 `error_rate_relative`、`p95_absolute_micros` 与 `p95_relative`。基线为零或缺失时，相对值为 `null`。

缺少 candidate 或 baseline，或者两个版本相同，都会返回 400。

读取服务的版本

GET /api/v1/apm/services/{service} 返回 versions，即时间范围内出现过的版本。每个版本带有 red（它在时间范围内的表现）和 verdict（与同一服务中在它之前首次出现的版本相比的结论），判定方式与版本对比相同：

字段	说明
`previous`	对比的版本。
`status`	`regressed`、`improved`、`neutral` 或 `insufficient_data`。
`worse`	`status` 为 `regressed` 时变差的项：`error_rate`、`latency` 或两者。
`delta`	与版本对比相同，以较早的版本为基线。

最早出现的版本没有 verdict。请求中的版本筛选不会缩小这些数据：每个版本都从整个服务读取。

读取错误发生的分布

GET /api/v1/apm/errors 在分页结果旁返回 breakdown，统计 status 筛选保留的全部分组（不只是当前页），GET /api/v1/apm/errors/{fingerprint} 返回该分组的 breakdown。它包含 versions、environments 和 languages，每项是 value 与 count（出现次数）的列表，次数多的在前。span 没有上报的值为空字符串；前七个值之后的其余值合计为 __other__。语言取自服务的 telemetry.sdk.language。

维护错误聚合规则

规则在错误出现时按类型、抛出位置和端点之外的方式分组。规则按 position 顺序匹配，第一条匹配的规则生效。

POST /api/v1/apm/error-rules
Content-Type: application/json

{"name": "Upstream timeouts", "service_namespace": "shop", "service_name": "checkout",
 "error_type": "*Timeout*", "message": "", "frame": "", "endpoint": "", "action": "merge", "enabled": true}

字段	说明
`name`	最多 128 个字符。合并后的分组以此命名。
`service_namespace`、`service_name`	规则适用的服务。`service_name` 为空表示全部服务；指定命名空间时必须同时指定服务名。
`error_type`、`message`、`frame`、`endpoint`	错误类型、异常消息、第一个应用栈帧和端点的匹配模式，每个最多 256 个字符。模式匹配整段文字，不区分大小写，`*` 代表任意文字。空模式不限；至少要设置一个。
`action`	`merge`：一个服务中匹配到的错误合并为一个分组。`ignore`：匹配到的错误不形成分组，它们的请求仍计为失败。
`enabled`	停用的规则会保留，但不参与匹配。默认为 `true`。

响应为带有 id、position、updated_by 和 updated_at 的规则。一个组织最多保留 100 条规则。PUT /api/v1/apm/error-rules/order 接收 {"ids": [...]}，把这些规则按给定顺序排在最前，其余规则排在其后，并按新顺序返回规则。修改在保存它的节点上立即生效，在其他节点上 30 秒内生效，作用于此后出现的错误；已有的分组保持不变。

读取服务地图

GET /api/v1/apm/map 接收通用的时间范围、environment 和 namespace 参数，返回 nodes、edges、namespaces（该环境中服务的命名空间）、environments（全部环境）和 truncated（只保留了最繁忙的 400 个节点时为 true）。

字段	说明
`nodes[].id`	`service:<名称>`、`topic:<名称>`，被调用的对象为 `<类别>:<目标>`。
`nodes[].kind`	`service`、`external` 或 `topic`。外部节点带有 `category`。
`nodes[].red`	`request_count`、`error_count`、`error_rate` 和 `p95_micros`：服务处理的请求，或外部节点、Topic 收到的请求。服务节点还带有 `health`、`namespace` 和 `environments`。
`edges[].kind`	`call`、`publish`（发布到 Topic）或 `consume`（从 Topic 消费）。
`change`	边或节点与之前同样长的一段时间相比：之前没有为 `new`，现在没有为 `gone`。之前没有任何数据时省略。

服务之间的调用取自服务图，P95 取其最慢一分钟的值；其余取自 APM 分桶。GET /api/v1/apm/map/edge 在相同参数之外接收 source 和 target 两个节点 id，返回 kind、red、trend、operations（name、kind、red）、every_caller（操作是被调服务所有调用方的端点时为 true）和 errors（被调服务的错误分组）。

读取服务的影响范围

GET /api/v1/apm/blast-radius 必须带 service，另外接收通用的时间范围和 environment 参数。它读取该环境的整张地图，不受 Namespace 限制，返回 meta、service（服务自己的节点，时间范围内地图上没有该服务时省略）、upstream（调用它的，最多三层）和 downstream（它调用或发布到的，最多两层）。每一侧最多 30 个节点，不健康的在前；和上一时段相比已经消失的调用不计入。

字段	说明
`id`、`kind`、`name`、`namespace`、`category`	节点，含义同服务地图。
`hops`	节点和服务之间相隔的调用层数：直接调用方或被调用方为 `1`。
`via`	通过哪个节点到达它，即离服务近一层的节点。
`health`	服务自身的健康状态。被调用的对象按调用失败的情况给出。
`red`、`call`	它处理或收到的请求，以及它和 `via` 之间的调用。

上报与列出发布

POST /api/v1/apm/deployments 接收 JSON 格式的发布，返回 201 和这次发布，并补上 id、created_by 和 created_at。字段、限制和 CI 示例见部署。服务名和环境按组织的命名规则、环境映射和别名处理。仓库地址保存时会遮盖其中的密码。配置变更和功能开关把 kind 设为 configuration 或 feature_flag，不需要 version。 GET /api/v1/apm/deployments 接收 service、namespace、environment、from 和 to（微秒时间范围），按时间从新到旧最多返回 200 次发布。没有 Namespace 或环境的发布会出现在所有 Namespace 或环境的列表中。

维护 APM 设置

GET /api/v1/apm/settings 返回组织的设置；PUT 整体替换设置，并返回保存后的内容：

{
  "health": {
    "error_rate_warning": 0.02,
    "error_rate_critical": 0.1,
    "p95_warning_micros": 500000,
    "p95_critical_micros": 2000000
  },
  "apdex_threshold_micros": 500000,
  "long_task_micros": 1000000,
  "naming_rules": [{ "pattern": "^(checkout)-[a-z0-9]{5}$", "replacement": "$1" }],
  "environment_map": [{ "from": "Production", "to": "production" }],
  "aliases": [{ "alias_namespace": "shop", "alias": "checkout-v1", "namespace": "shop", "service": "checkout" }],
  "metadata_rules": { "team_from_tier": "p1", "owner_from_tier": "p0", "repository_from_tier": null }
}

省略的字段取默认值。名称会去掉首尾空白，别名的 Namespace 留空时为 default。各项限制和作用见 APM 设置。保存后在保存它的节点上立即生效，在其他节点上 30 秒内生效。平台的基数上限通过 GET 和 PUT /api/v1/settings/apm_limits 读取和替换，需要 sys.settings.manage。请求体包含 services_per_org_hour、transactions_per_service_hour、dependencies_per_service_hour、operations_per_dependency_hour、error_groups_per_service_hour、versions_per_service_hour 和 instances_per_service_hour，每项范围 1 到 100000。

检查投影健康状态

GET /api/v1/apm/health 报告投影是否在运行，以及是否健康。

{
  "meta": { "resolution": "minute", "data_quality": { "partial": false } },
  "enabled": true,
  "degraded": false,
  "runtime": {
    "enabled": true,
    "candidate_owner": true,
    "projector": {
      "accepting": true,
      "queue_depth": 0,
      "queue_capacity": 65536,
      "accepted_facts": 26838,
      "duplicate_skips": 0,
      "late_facts": 0,
      "queue_drops": 0,
      "cardinality_rejections": 0,
      "flush_successes": 130,
      "flush_failures": 0,
      "pending_snapshots": 5,
      "last_success_at": 1790000000000000,
      "latest_event_at": 1790000000000000,
      "degraded": false,
      "last_error": null
    },
    "rollup": {
      "running": true,
      "runs": 11,
      "failures": 0,
      "last_success_at": 1790000000000000,
      "degraded": false,
      "last_error": null
    }
  }
}

投影器或汇总任务报告问题时，degraded 为 true，last_error 说明原因。queue_drops、flush_failures 或 cardinality_rejections 持续增长，可以解释数据中的缺口。

阅读响应元数据

每个端点都返回通用 meta 对象：

{
  "range": {
    "from": 1785801600000000,
    "to": 1785888000000000
  },
  "resolution": "minute",
  "projection_started_at": 1785798000000000,
  "last_complete_bucket_at": 1785887940000000,
  "data_quality": {
    "partial": false,
    "gaps": [],
    "overflow_dimensions": []
  },
  "activation_boundary": false
}

activation_boundary: true 表示 projection_started_at 之前的数据不完整。
data_quality.partial: true 表示数据不完整，不能按完整零值解读。
检查 gaps，确认是否发生队列、存储库、刷写、迟到数据、基数或关闭失败。
使用 last_complete_bucket_at 判断最近数据是否仍在完成处理中。
依赖高基数明细前，请检查 overflow_dimensions。

错误

状态码	原因
`400`	参数无效：不支持的 `sort`（`unsupported APM sort field`）、超出 1 到 200 的 `limit`、为空或过长的过滤值（`invalid APM service filter`）、超过最大值的时间范围（`APM query range exceeds configured maximum`）、结束早于开始（`APM range end precedes start`），未知的 `direction`、`resolution`，未通过上述校验的 SLO（`SLO objective must be between 0 and 1, exclusive`），或缺少 `namespace`、`service`、`environment` 之一的 SLO 列表过滤条件。
`403`	Token 缺少 `streams.query`，或写入时缺少 `apm.manage`。
`404`	范围内不存在该错误指纹、事务、服务或 SLO。
`409`	要删除的 SLO 仍有告警规则在监控。

APM 指南

为服务接入埋点，并在界面中调查性能问题。

链路采集

发送用于生成 APM 的 OpenTelemetry trace。

最后修改于 2026年10月26日

概览

身份验证

数据采集

查询

APM

用户体验

数据流

告警

关联与 Web

平台与管理

端点

通用查询参数

排序字段

查询概览

读取洞察

列出服务并分页

读取 RED 指标

维护服务定义

标记关键事务

读取服务的数据覆盖

读取服务的运行情况

设置错误分组的状态

维护服务等级目标

区分同名事务

比较版本

读取服务的版本

读取错误发生的分布

维护错误聚合规则

读取服务地图

读取服务的影响范围

上报与列出发布

维护 APM 设置

检查投影健康状态

阅读响应元数据

错误

APM 指南

链路采集

​端点

​通用查询参数

​排序字段

​查询概览

​读取洞察

​列出服务并分页

​读取 RED 指标

​维护服务定义

​标记关键事务

​读取服务的数据覆盖

​读取服务的运行情况

​设置错误分组的状态

​维护服务等级目标

​区分同名事务

​比较版本

​读取服务的版本

​读取错误发生的分布

​维护错误聚合规则

​读取服务地图

​读取服务的影响范围

​上报与列出发布

​维护 APM 设置

​检查投影健康状态

​阅读响应元数据

​错误

APM 指南

链路采集

端点

通用查询参数

排序字段

查询概览

读取洞察

列出服务并分页

读取 RED 指标

维护服务定义

标记关键事务

读取服务的数据覆盖

读取服务的运行情况

设置错误分组的状态

维护服务等级目标

区分同名事务

比较版本

读取服务的版本

读取错误发生的分布

维护错误聚合规则

读取服务地图

读取服务的影响范围

上报与列出发布

维护 APM 设置

检查投影健康状态

阅读响应元数据

错误