APM 应用性能监控
本章覆盖：拓扑 / 链路列表 / 服务 / 接口 / 错误 / Trace 详情。 APM（Application Performance Monitoring，应用性能监控）基于 OpenTelemetry（OTel）采集的链路（Trace）与指标数据，帮助研发与 SRE 从"服务全景"一路下钻到"单次调用的某个 Span"，快速定位慢请求、错误来源与依赖瓶颈，缩短故障定位时间（MTTR）。
APM 各功能统一收敛在同一入口下的顶部 Tab 中，从左到右依次为：调用拓扑、链路列表、服务列表、接口分析、错误分析。服务详情、Trace 详情、接口详情则通过在这些页面中点击相应链接进入。
进入路径：左侧主导航 数据查询 → 链路追踪（页面地址 /query/traces）。
页面顶部为统一的数据源与范围控制条，对下方所有 Tab 生效：
| 控制项 | 含义 |
|---|---|
| 数据源（Jaeger） | 选择提供 Trace 明细的 Jaeger 数据源；驱动"链路列表"与"Trace 详情"。未配置时使用系统内置默认 Jaeger |
| 指标源（Prometheus） | 选择提供拓扑 / 服务 / 接口 / 错误指标的 Prometheus 数据源（数据来自 spanmetrics 与 servicegraph）。留空时后端回退到租户第一个启用的 Prometheus |
| 套 | 按 service.namespace（多套租户隔离归属）过滤所有 Tab；无命名空间数据时自动降级为"全部" |
| 刷新数据源 | 右上角，重新拉取已注册的数据源列表 |
| OpenTelemetry 标签 | 提示当前数据来源体系为 OpenTelemetry |
注意事项：拓扑、服务、接口、错误四类分析依赖 Prometheus 指标（spanmetrics + servicegraph）；链路明细依赖 Jaeger。若某一类数据缺失，请先确认对应数据源已在"数据源管理"中正确配置并启用。
服务拓扑
1. 功能简介
服务拓扑以有向图的形式，将各服务之间的真实调用关系可视化，呈现调用方向、请求速率、成功率、响应时间与健康状态，帮助你一眼看清系统全貌、识别核心链路与异常节点。
2. 进入路径
数据查询 → 链路追踪 → 调用拓扑 Tab（默认打开的第一个 Tab）。
3. 界面总览 界面从左到右分为三个区域：中间为拓扑画布（服务节点 + 调用连线，支持缩放、拖拽、小地图导航），右侧上方为图例，右侧为选中服务的详情抽屉。
4. 界面元素说明
服务节点卡片字段：
| 字段 | 含义 |
|---|---|
| 服务名称 | 服务名（含图标）；节点右上角为健康状态圆点与图标 |
| 套徽标 | 该服务所属的 service.namespace（有归属时显示） |
| ↓ n/s | 入向请求速率（每秒请求数，rps） |
| n ms | 平均响应时间（P95 近似） |
| ×n | 实例数 |
调用连线与图例：
| 元素 | 含义 |
|---|---|
| 实线 | 同步调用 |
| 虚线 | 异步调用 |
| 连线标签 | 成功率百分比 · 请求速率（如 99.8% · 12.30/s） |
| 连线粗细 | 与请求量正相关，量越大线越粗 |
| 连线颜色 | 灰色正常 / 橙色存在错误 / 红色错误率 > 5%（并以动画流动强调） |
| 健康-健康（绿点） | 无错误且有流量 |
| 健康-警告（黄点） | 错误率 > 0 或存在警告级告警 |
| 健康-异常（红点） | 错误率 > 5% 或存在严重告警 |
| 健康-未知（灰点） | 无流量、无法判定 |
顶部工具条：
| 控件 | 说明 |
|---|---|
| 健康状态 | 多选下拉，按健康状态（健康 / 警告 / 异常 / 未知）过滤画布中显示的节点 |
| 搜索服务 | 选中某服务后，画布收敛为"该服务 + 直接上下游"的邻域视图 |
| 最近 15 分钟 | 当前统计时间范围 |
| 显示设置 | 开关，控制是否在连线上显示成功率 / 速率标签 |
右侧服务详情抽屉（点击节点后展开，含 概览 / 追踪 / 指标 / 日志 / 告警 五个 Tab）：
| 抽屉内容 | 含义 |
|---|---|
| 基本信息 | 服务名、实例数等 |
| 当前指标 | 请求数（rps）、错误率、平均延迟（P95）、成功率四张指标块，均带迷你趋势图 |
| 上游依赖 / 下游依赖 | 该服务的调用方与被调用方，标注占比与速率 |
| 概览 / 指标 Tab | 响应时间、错误率、调用数（成功 / 失败）趋势图 |
| 告警 Tab | 该服务当前活跃告警 |
| 查看追踪详情 → | 跳转到"链路列表"并按该服务预过滤 |
5. 操作步骤
- 进入 链路追踪 → 调用拓扑 Tab，画布自动加载全量服务调用关系（默认每 30 秒刷新一次）。
- 用鼠标滚轮缩放、拖拽平移；左下角控制条可复位视图，右下角小地图可快速导航。
- 观察节点右上角健康圆点与连线颜色，快速锁定异常服务或异常调用。
- 在顶部"搜索服务"中选择目标服务，画布收敛为其上下游邻域，聚焦排查。
- 点击任一节点，右侧抽屉展开该服务的指标、依赖与告警。
- 在抽屉中点击 查看追踪详情 →，直接跳到该服务的链路列表继续下钻。
6. 常见问题 / 注意事项
- 画布提示"暂无服务调用关系（需 servicegraph 指标接入）"：说明 Prometheus 中缺少 servicegraph 指标，请确认边缘 OTel Collector 已开启 servicegraph 连接器并正常上报。
- 纯生产者节点（如压测 / 流量发生器）只有出向调用，入向请求为 0，健康判定会结合出向活动，避免误判为"未知"。
- 工具条中的"生产环境""全部"两个下拉为本期占位项，暂不可操作。
链路列表
1. 功能简介
链路列表展示一段时间内采集到的调用链（Trace）汇总，每一行是一条完整链路，包含开始时间、入口接口、耗时、状态等，支持多维筛选与排序，便于快速找出慢链路或错误链路并下钻查看。
2. 进入路径
数据查询 → 链路追踪 → 链路列表 Tab。（从拓扑抽屉点击"查看追踪详情"也会跳转到此并预过滤服务。）
3. 界面总览 左侧为筛选面板，右侧为链路结果表；表格上方显示"发现 N 个数据"。
4. 界面元素说明
左侧筛选面板：
| 筛选项 | 含义 |
|---|---|
| 服务 | 按入口服务筛选（下拉，支持搜索） |
| 时间范围 | 近 1 时 / 近 3 时 / 近 6 时 / 近 24 时 |
| 条数 | 拉取上限：50 / 100 / 200 |
| 响应时间（ms） | 双端滑块，按耗时区间过滤（客户端） |
| 状态 | 正常 / 错误 复选 |
| 接口名称 | 按结果集中出现的入口接口多选过滤 |
| 服务（结果集） | 按结果集中出现的入口服务多选过滤 |
链路结果表列：
| 列 | 含义 |
|---|---|
| 开始时间 | 链路起始时间（可点击表头排序） |
| TraceID | 链路唯一标识（截断显示），点击进入 Trace 详情 |
| 接口名称 | 入口操作名（root operation） |
| 状态 | 正常 / 错误 徽标（链路内含错误 Span 则为错误） |
| 耗时 | 链路总耗时（可点击表头排序，自动按 µs/ms/s 换算） |
| 服务 | 入口服务（root service） |
| 套 | 所属 service.namespace 归属徽标 |
| 类型 | 链路类型 |
| 状态码 | 入口状态码 |
| 主机 | 上报主机 |
5. 操作步骤
- 进入 链路列表 Tab，默认加载近 1 小时、上限 100 条链路。
- 在左侧选择服务、时间范围与条数，缩小拉取范围。
- 用"状态=错误"或拖动"响应时间"滑块，快速筛出错误链路或慢链路。
- 点击"开始时间"或"耗时"列表头切换升序 / 降序（列头箭头 ↑ / ↓ 指示当前排序）。
- 点击目标行的 TraceID，进入该链路的调用链详情（见 7.6）。
6. 常见问题 / 注意事项
- 响应时间滑块、接口名称、服务（结果集）三类筛选为客户端过滤，仅作用于已拉取的结果，不会重新查询后端。若要扩大范围，请调大"条数"或时间范围。
- 表格提示"未找到链路"时，多为该时间窗内无数据或所选服务未上报，可放宽时间范围或清空服务筛选。
服务列表与服务详情
1. 功能简介
服务列表以 RED 指标（请求率 / 错误率 / 时延）汇总所有服务的运行状况，并配合 Top-N 趋势图，便于横向比较、快速识别高负载或高错误的服务；点击服务名可进入服务详情，查看实例、依赖关系、属性与告警。
2. 进入路径
数据查询 → 链路追踪 → 服务列表 Tab；点击服务名进入服务详情（页面地址 /apm/services/:name）。
3. 界面总览 顶部为搜索框与 Top-N 选择器，中部为"平均响应时间 / 请求量 / 错误率"三张趋势图，下方为服务指标表。 服务详情页顶部显示服务名与健康状态徽标，下含 服务关系 / 基础信息 / 服务告警 三个 Tab。
4. 界面元素说明
服务列表 —— 表格列：
| 列 | 含义 |
|---|---|
| 服务名称 | 服务名，点击进入服务详情 |
| 套 | 所属 service.namespace 归属徽标 |
| 调用数 | 时间窗内累计调用次数（可排序） |
| 调用速率 | 每秒请求数 /s（可排序） |
| 错误率 | 错误占比，> 5% 红色、>0 橙色、0 绿色（可排序） |
| 平均响应时间 | 平均时延（可排序） |
| 最大响应时间 | P99 近似，受直方图桶上限约束（可排序） |
服务列表 —— 顶部控件：搜索服务（同时过滤表格与趋势图）、Top（5 / 10 / 20，控制趋势图展示的服务条数）。
服务详情 —— 基础信息 Tab：
| 区块 / 字段 | 含义 |
|---|---|
| 实例表 | 服务实例名称、请求量、Node、Pod、Namespace、健康状态 |
| 全部实例平均值 / 按实例排行 Top5 | 切换趋势图口径 |
| 响应时间 / 调用数 / 错误率 | 三张趋势图 |
| 属性信息 | 服务显示名称、检测名称、类型、使用的技术、语言、运行时名称 / 版本、服务版本、数据来源 |
| 标签信息 | 自定义标签（后续提供） |
服务详情 —— 服务关系 Tab：上游服务、当前服务（含最近一小时吞吐迷你图）、下游服务三张卡片，点击上游 / 下游卡片切换下方对端表（上游 / 下游服务名称、接收 / 发出请求量、平均网络耗时、健康状态）。
服务详情 —— 服务告警 Tab：该服务当前活跃告警（告警 ID、发生时间、告警等级、告警描述）。
5. 操作步骤
- 进入 服务列表 Tab，在搜索框输入关键字过滤服务，趋势图随之只展示匹配服务的 Top-N。
- 点击"错误率""调用速率"等列头排序，快速找出高错误或高负载服务。
- 点击某服务名进入服务详情。
- 在"服务关系"Tab 点击上游 / 下游卡片，查看对端服务及网络耗时。
- 在"基础信息"Tab 切换"按实例排行 Top5"，逐实例对比性能；查看"属性信息"了解语言、运行时等元数据。
- 在"服务告警"Tab 查看该服务的活跃告警。
6. 常见问题 / 注意事项
- "最大响应时间"为基于直方图的 P99 近似，受桶上限约束，仅供趋势参考，不等同于精确 P99。
- 服务详情页右上角"接口分析"按钮会返回链路追踪入口。
- 实例表的 Node / Pod / Namespace 需要 K8s 属性上报后才会填充，未接入时可能为空。
接口分析
1. 功能简介
接口分析按协议维度（HTTP / RPC / Redis / SQL / MQ / 外部调用）统计各接口（Endpoint）的调用量、速率、错误率与响应时间，帮助定位到具体接口层面的性能与错误问题。
2. 进入路径
数据查询 → 链路追踪 → 接口分析 Tab；点击接口名进入接口详情（页面地址 /apm/endpoints/:service/:endpoint）。
3. 界面总览 顶部为协议分段选择器与搜索框，中部为"调用数 / 响应时间"组合趋势图，下方为接口列表（可切换"接口列表 / 来源服务"两种视图）。
4. 界面元素说明
顶部控件：
| 控件 | 含义 |
|---|---|
| 协议分段 | HTTP接口 / RPC接口 / Redis调用 / SQL调用 / MQ消费 / 外部调用 |
| 时间范围 | 最近 15 分钟 / 1 小时 / 6 小时 / 24 小时 |
| 搜索接口 / 服务 | 按接口名或服务名过滤 |
| 趋势图 | 柱=调用数(/s)，线=响应时间(ms) |
| 视图切换 | 接口列表 / 来源服务 |
接口列表 —— 表格列：
| 列 | 含义 |
|---|---|
| 接口名称 | 接口路径 / 操作名，点击进入接口详情 |
| 数据来源 | 采集来源（OTLP） |
| 接口性能 | 健康色条：绿正常 / 橙警告(>1%) / 红异常(>5%) |
| 服务名称 | 归属服务 |
| 调用数 | 时间窗内调用次数（可排序） |
| 调用速率 | 每秒调用次数 /s（可排序） |
| 错误率 | 错误占比（可排序） |
| 平均响应时间 | 平均时延（可排序） |
| 最大响应时间(P99) | P99 时延（可排序） |
| 趋势 | 迷你趋势图 |
"来源服务"视图：按服务聚合，展示 服务名称、接口数、调用数、调用速率、错误率、平均响应时间。
5. 操作步骤
- 进入 接口分析 Tab，通过顶部分段选择器切换协议类型（默认 HTTP接口）。
- 在右上角选择时间范围，观察"调用数 / 响应时间"组合趋势。
- 在搜索框输入接口或服务关键字缩小范围。
- 点击列头（调用数 / 错误率 / 平均响应时间等）排序，定位高频或高错误接口。
- 切换"来源服务"视图，从服务维度聚合查看接口分布。
- 点击接口名称进入接口详情，查看该接口的更细粒度指标。
6. 常见问题 / 注意事项
- 每种协议的数据相互独立，切换协议后趋势图与列表会随之刷新；某协议提示"该协议暂无接口数据"属正常（该类型无流量）。
- "数据来源"当前统一显示 OTLP，表示接口指标来自 OpenTelemetry 采集。
错误分析
1. 功能简介
错误分析聚合各服务、各接口的错误来源，按错误率与错误量排序展示，帮助你快速锁定"错误最集中"的服务与接口，是排障时的优先入口。
2. 进入路径
数据查询 → 链路追踪 → 错误分析 Tab。
3. 界面总览 顶部为服务筛选下拉，下方为错误来源表。
4. 界面元素说明
| 列 / 控件 | 含义 |
|---|---|
| 按服务筛选 | 下拉选择只看某个服务的错误（支持搜索） |
| 服务 | 产生错误的服务 |
| 接口 | 产生错误的接口 |
| 错误率 | 错误占比徽标，> 5% 红色、否则橙色 |
| 错误量 | 每秒错误数 /s |
| 趋势 | 错误率迷你趋势图 |
5. 操作步骤
- 进入 错误分析 Tab，默认展示全部服务的错误来源（默认每 30 秒刷新）。
- 在"按服务筛选"下拉中选择目标服务，聚焦单个服务的错误。
- 根据错误率与错误量排布，锁定错误最集中的服务 / 接口。
- 结合"链路列表"按错误状态筛选对应链路，进一步下钻到 Trace 详情定位根因。
6. 常见问题 / 注意事项
- 表格提示"当前无错误"说明所选范围内没有错误数据，属正常状态。
- 错误分析基于 Prometheus 指标聚合，反映错误的分布趋势；要看单次错误的具体 Span 堆栈，请到 Trace 详情中查看标红的 Span。
Trace 调用链详情
1. 功能简介
Trace 调用链详情展示单条链路内所有 Span 的父子关系、时序与耗时，通过瀑布图 / 火焰图直观呈现调用次序，并可逐 Span 查看环境、标签与耗时明细，是定位慢请求、错误 Span 的最终落点。
2. 进入路径
在"链路列表"（7.2）中点击某条链路的 TraceID 进入（页面地址 /apm/traces/:id）。
3. 界面总览 顶部为链路标题、状态徽标、总耗时与 TraceID；下方三个 Tab：调用次序 / 火焰图 / 耗时统计。调用次序与火焰图右侧附有 Span 详情面板。
4. 界面元素说明
顶部信息：
| 字段 | 含义 |
|---|---|
| 状态徽标 | 正常 / 错误（链路内任一 Span 出错即为错误） |
| 标题 | 入口 Span 的操作名与所属服务 |
| 总耗时 | 整条链路耗时 |
| TraceID | 链路唯一标识 |
调用次序 Tab（瀑布图）：
| 元素 | 含义 |
|---|---|
| 搜索框 | 按服务名 / 接口名过滤 Span |
| ▸ / ▾ | 折叠 / 展开子 Span |
| Span 行 | 操作名 · 服务 · 类型；缩进表示层级 |
| 占比 % | 该 Span 耗时占总耗时百分比 |
| 时间条 | 按起始偏移与耗时定位的横条；错误 Span 显示为红色 |
| 右侧耗时 | 该 Span 耗时 |
Span 详情面板（点击某个 Span 后显示）：分为链路串联信息（SpanID、ParentID）、Span 环境信息（数据来源、上报主机、Span 类型、当前服务名、服务实例、线程名称）、Span 详情信息（入口 resource、耗时）、其他信息（全部标签键值）。
火焰图 Tab：以层级色块横向展示各 Span 的时间占用，点击色块可在右侧查看该 Span 详情。
耗时统计 Tab：按 服务 → 接口 两级聚合，列为 Resource、Span 数量、平均耗时、执行时间、执行占比，可折叠 / 展开每个服务下的接口明细。
5. 操作步骤
- 从"链路列表"点击 TraceID 进入本页，默认打开"调用次序"Tab。
- 观察瀑布图，红色时间条即为出错 Span；耗时最长的横条即为主要耗时点。
- 用搜索框按服务或接口名过滤，用 ▸ / ▾ 折叠无关子树。
- 点击任一 Span 行，右侧面板展开该 Span 的环境信息与全部标签。
- 切换"火焰图"从层级视角审视调用深度与耗时分布。
- 切换"耗时统计"，按服务 / 接口定位"哪个服务、哪个接口"占用了最多时间。
6. 常见问题 / 注意事项
- 页面提示"加载链路失败"时，多为该 TraceID 已过采样保留期或所选 Jaeger 数据源不含该链路，可返回列表重新选择或切换数据源。
- Span 详情中的"服务实例""上报主机"等字段来自 OTel 资源属性（如
service.instance.id、host.name、k8s.pod.name），未上报对应属性时会显示为"-"。 - 耗时统计的"执行占比"基于各 Span 耗时之和计算，存在并发 Span 时占比之和可能大于 100%，属正常现象。