APM 不需要另一套 SDK，也不会新增遥测数据流。发送完整埋点的 trace 后，MoleSignal 会在链路去重之后、尾采样之前派生 APM 数据。因此，最终被采样丢弃的 trace 仍可计入 APM 指标。
页面
APM 以概览为首页，每个服务有自己的页面。
服务页包含以下分区：
服务名后面的一行说明服务的基本情况，并跟随当前选择的环境和版本：
已归档的服务在这一行还会显示已归档。标题行末尾的收藏把服务加入自己的收藏。
导航卡片末尾链接到服务的日志、指标和 Profiles。在当前时间范围终点之前的一天内，某个信号带有这个服务时，对应链接会点亮。MoleSignal 每五分钟重新查看一次：
没有数据的信号会变暗，点击打开数据源中对应的接入页面。查看失败或超过三秒时，链接既不点亮也不变暗。
接入前提
- 把 OpenTelemetry trace 发送到 MoleSignal 的链路采集端点；
- 在组织工作区拥有
streams.query；或者 - 在受保护的
_sys遥测范围拥有sys.telemetry.read。
为服务接入 APM
1
设置稳定的服务资源属性
每个服务都要设置 具体配置方式取决于使用的 OpenTelemetry SDK 或 Collector。
service.name。如果需要筛选服务或比较部署，再添加命名空间、环境、版本和实例属性。2
使用正确的 span kind
为入站请求创建
SERVER span，为消费的消息创建 CONSUMER span。为下游调用创建 CLIENT 或 PRODUCER span。MoleSignal 通过 span kind 区分事务与依赖。3
记录状态与异常
设置 OpenTelemetry span 状态、HTTP 或 RPC 状态属性，并记录 exception event。MoleSignal 用这些信息区分成功与失败，并建立后端错误组。
4
发送 trace 并打开 APM
发送 OTLP trace，然后打开 应用性能 → 服务。把全局时间范围保持在最近流量，等待投影器刷写首批数据桶。
推荐的资源属性
Kubernetes 属性和
cloud.region 通常由 OpenTelemetry Collector 的 k8sattributes 和 resourcedetection 处理器添加，而不是由 SDK 设置。
请使用低基数值。不要把请求 ID、原始 URL、用户 ID 或其他无界值放进服务、环境、版本、路由、操作或依赖属性。
APM 数据如何派生
服务与端点
SERVER 和 CONSUMER span 会计入服务与端点 RED 指标。API 把端点称为事务（transaction）。没有 kind 且没有父 span 的数据可作为服务总量的兼容回退，但显式 span kind 才能生成更完整的页面。
MoleSignal 会从语义属性构造有界端点名称：
- HTTP 方法与
http.route，例如POST /checkout； - RPC 服务与方法；
- 消息操作与目标端；
- 没有更强语义标识时，使用安全、低基数的 span 名称。
/orders/{id} 这样的路由模板，不要使用 /orders/83921 这样的原始路径。
依赖
CLIENT 和 PRODUCER span 会计入依赖 RED 指标。MoleSignal 会把目标分类为服务、数据库、缓存、消息系统、外部 HTTP、外部 RPC 或其他依赖。标准的 peer.service、db.*、messaging.*、rpc.*、server.* 和 HTTP 语义属性可以提高依赖标识质量。
SQL 数据库调用的操作名是语句模板：取 db.query.summary，没有时取 db.query.text 或 db.statement，所有字面量替换为 ?，去掉注释，值列表合并为一个 ?，最多保留 512 字节。双引号中的文字只在把它当作表名或列名的数据库（如 PostgreSQL、Oracle）中保留，在其他数据库中当作值处理。没有语句的调用使用 db.operation.name，缓存调用使用其命令名。一个服务对同一目标每小时最多区分 32 个操作，其余操作在同一目标下合并为其他。
超时的请求（错误类型为超时、gRPC DEADLINE_EXCEEDED、HTTP 408 或 504）和重发的请求（http.request.resend_count 大于 0）会在 RED 指标旁单独计数。
错误
span 包含异常、OpenTelemetry 状态为ERROR、HTTP 状态码不低于 500，或 RPC 状态非零时，MoleSignal 会把该 span 判定为错误。错误组的稳定指纹由错误类型、第一个应用栈帧和事务名称组成；经常变化的错误消息不参与指纹计算。聚合规则可以把错误合并为一组，或让它们不再成组。
理解 RED 指标
错误率达到 2% 或 p95 达到 500 ms 的服务为警告，达到 10% 或 2 s 为严重；APM 设置可以改用其他判定线。服务页和目录里的状态点会说明是哪项指标超过了哪条线。
洞察卡片列出和上一段同样长的时间、上周同时段相比有突变的服务，见洞察的种类。
延迟直方图把延迟每翻一倍分成八个桶，覆盖 125 微秒到约 131 秒，分位数在所在桶内插值读出，与精确值的误差约 ±4%。用旧的固定分桶写入的聚合仍可读取，但精度较粗。
概览和端点抽屉的对比控件会把前一天或上周同一时间段画成虚线，延迟分布也会勾出对比期的轮廓。在服务页面上，这个控件还会列出服务的其他环境：选择后，虚线改为同一时间段在那个环境中的数据。
端点的最慢请求取自 Trace 存储，列出的每个请求都能打开其调用链。错误样本指向的 trace 可能已被尾采样丢弃，此时链路抽屉会说明找不到这条 trace。
服务目录
目录为 APM 看到的每个服务按环境各列一行，也列出尚未上报、已经登记的服务。用服务目录中的登记服务和服务页的设置分区记录：
同一表单中的归档会让服务不再出现在服务目录的默认视图中，数据照常采集，服务页照常打开。服务目录中的 已归档会同时列出已归档的服务。
服务目录要求可以要求某个等级及以上的服务填写团队、负责人或代码仓库。缺少要求项的服务会在目录中显示缺少及缺少的项。
服务定义按命名空间和服务名保存，在所有环境中都适用。服务目录和端点表的列设置可以选择和排序列，排列会按用户保存。除指标和目录字段外，服务目录还提供服务类型、语言 / 框架、实例和 区域列，取自时间范围内的实例，以及标签和最后活跃列。
服务目录每行的星标把服务加入自己的收藏，收藏的服务排在目录最前；收藏只列出收藏的服务。收藏按用户保存。分组按团队、命名空间、等级或某个标签的值分组。服务目录可以按环境和团队筛选；服务分布在多个命名空间或带有标签时，还可以按命名空间和标签筛选。筛选和分组都写在地址里，分享链接会打开同样的视图。在时间范围内出现过、但到时间范围终点已超过一天没有上报的服务标为未活跃。
关键事务是最重要的端点。在端点列表或端点抽屉中点星标即可标记，设置会列出服务的关键事务以及每个关键事务在时间范围内的请求情况。每个服务最多 50 个关键事务。
服务文档和 Runbook 放在 Mole Agent 知识库的
services/<服务名>/ 下，可以放在组织知识库或负责团队的知识库。服务页上的文档会列出这些文件，并可新建 Runbook。Mole Agent 排查这个服务时也会读取这些文件。
编辑服务定义、关键事务和错误状态需要 apm.manage。所有者、管理员和编辑者拥有该权限。
实例
每个为服务上报数据的进程是一个实例，依次用service.instance.id、k8s.pod.name、host.name 区分。MoleSignal 每分钟查看一次实例的 Span，保存它运行的版本和上表中的属性，每项取最后一次上报的值。代码仓库链接保存为不含用户名、密码和查询参数的 https 地址。每个实例处理的请求、错误和延迟单独分桶统计，来源与服务的指标相同。
运行时列出当前时间范围和版本下的实例，最近上报的在前，含吞吐、错误率和 p95，以及实例的日志（按 Pod，没有 Pod 时按主机）和指标（按区分实例的标签）链接。每个服务每小时超过实例基数上限的实例合并为其他实例 一行，所有实例加起来等于服务。点击实例后，运行时图表只显示这个实例，这个选择会写在地址里。超过小时级聚合保留期仍未出现的实例会被删除。
深入端点
端点抽屉在 RED 图表之外还有两张卡片：- 状态码按状态码统计响应：HTTP 状态码取自
http.response.status_code（旧版插桩为http.status_code），gRPC 状态码取自rpc.grpc.status_code，按类别着色，并附趋势。每个分桶最多记录 24 个状态码，更多的计入其他 HTTP 或其他 gRPC。开始统计状态码之前写入的聚合没有状态码。 - 耗时拆解从 Trace 存储读取该端点在时间范围内最近的请求（最多 200 个）及其下的 span。调用的耗时按调用对象归类：数据库（
db.system.name）、缓存（Redis、Memcached、Valkey）、HTTP、RPC、消息，没有说明调用对象的计入其他。内部 span 计为内部处理，请求下没有任何 span 覆盖的时间是请求的自身耗时。每一项显示占比和每个请求的平均耗时。并行的调用加起来可能超过请求时长，此时各项会按请求时长等比缩放。只会读到尾采样保留下来的 trace。
部署
服务页的部署标签把流水线上报的发布与服务 Span 中带的版本放在一起，标出回滚，把每个版本与它之前的版本对比，并把同时运行的两个版本并排展示。流水线通过POST /api/v1/apm/deployments 上报发布。见部署。
依赖
服务依赖标签中的每个目标都有一个从 100 开始的健康评分：调用失败率每 1% 扣 4 分（最多 60 分），超时调用占比每 1% 扣 4 分（最多 20 分）；选择了对比时段时，P95 增长超过五分之一的部分每 1% 扣半分（最多 20 分）。90 分及以上为良好，70 分及以上需要留意。评分的提示会说明扣分原因。设置对比后，每个目标还会显示错误率和 P95 的变化。慢 SQL 按 P95 列出最慢的数据库语句模板。调查性能问题
1
找到服务
打开 应用性能 → 服务，按错误率或 p95 排序，再按环境或团队收窄。
2
阅读概览
打开服务，与前一天或上周对比请求、错误率和时延，并查看时间花在哪些下游。洞察卡片会写明和上一时段、上周同时段相比有哪些指标变了、从什么时候开始，以及附近的变更。见洞察与调查。
3
缩小原因范围
用端点查找慢入口，用依赖检查下游耗时，用错误分析重复失败。当时延与流量都很重要时，按耗时占比排序端点。
4
打开证据
打开端点的最慢请求、错误样本，或调用链中的 trace，链路会在页面上的抽屉中打开。服务范围行末尾的日志、指标和 Profiles 会为同一服务和时间范围打开对应信号。
5
检查部署
打开部署，找出结论为变差的版本。点击它的结论或选择两个版本，查看差异以及变慢的端点和增多的错误。请求不足表示结论尚不可靠，不能直接判定没有回退。
6
交给 Mole Agent
在服务页标题栏、端点或错误抽屉中，或在某条发现上点击调查。Mole Agent 会打开，问题已经写好，并附上该服务。见让 Mole Agent 调查。
跟踪后端错误
错误分组在被设为调查中、已解决或忽略之前都是待处理状态。每个分组都可以交给一个团队，并指派给工作区成员。已解决的分组再次出现时显示为回归。应用性能 → 错误默认显示未解决的分组：待处理、调查中和回归的分组。 列表上方的分布按版本、环境和服务的语言统计所列分组的出现次数；错误分组的抽屉统计它自己的出现次数。抽屉里的相关日志按服务和时间范围打开日志，样本旁的日志打开该样本所在 trace 的日志。用规则聚合错误
错误列表上的聚合规则决定错误在类型、抛出位置和端点之外如何分组。规则指定一个服务或全部服务，以及错误类型、错误消息、抛出位置和端点的匹配模式。每个模式匹配整段文字，不区分大小写，* 代表任意文字；留空表示不限，但规则至少要填写一项。
规则按顺序匹配，第一条匹配的规则生效；上移或下移规则可以调整顺序。规则对保存之后出现的错误生效，半分钟内在所有节点生效，已有的分组保持不变。编辑规则时，表单会显示所列分组中有多少个符合这条规则。错误分组抽屉中的按此错误建规则会以该分组的类型和服务开始一条新规则。
服务等级目标
服务等级目标（SLO）承诺在 7、28 或 30 天的滚动窗口内达标请求所占的比例，对象是某个环境中的一个服务，或其中的一个端点。打开 应用性能 → SLO 并点击新建 SLO，或在服务概览的服务等级目标 卡片中点击新建 SLO。
SLO 读取服务的 APM 聚合，因此统计的是尾采样之前的全部请求。
延迟目标读取延迟直方图，因此阈值内请求数的精度与分位数相同，误差约在 4% 以内。窗口读取小时级聚合，燃烧率读取分钟级聚合。窗口长于小时级聚合的保留期时，只统计保留的天数。
燃烧率告警
在 SLO 抽屉中点击创建燃烧率告警，会添加 Google SRE workbook 推荐的两条告警规则。两条都是针对该目标的 APM 告警规则，通过规则的升级策略发送通知。
短窗口让规则不会因为已经过去的尖峰而触发。有规则监控该 SLO 后，抽屉会列出这些规则，不再显示按钮。创建规则需要
alerts.manage。
编辑 SLO 需要 apm.manage。删除 SLO 时会先删除它的燃烧率告警，因此还需要 alerts.manage。
按 APM 指标告警
APM 告警规则监控服务或其端点的某项指标，读取的是 APM 页面使用的同一份聚合，无需编写查询。1
打开规则编辑器
在服务页或端点抽屉的标题栏打开新建告警，选择阈值告警。编辑器会以 APM 告警数据源打开，并预填服务、环境和端点。在告警 → 告警规则中新建规则时，也可以选择 APM 告警数据源。创建规则需要
alerts.manage。2
选择指标
选择服务、环境或所有环境、端点或整个服务，以及指标。按编辑器在指标下方标注的单位设置阈值。
3
测试并保存
点击测试规则，查看最近 6 小时的指标与阈值的对比，然后创建规则。
每次评估读取规则的窗口：24 小时以内读取分钟级聚合，更长的窗口读取小时级聚合。窗口内没有请求时，请求数、错误数、新错误组和吞吐读数为
0，因此规则可以发现流量中断。其他指标此时没有读数，不会命中任何阈值，进行中的事件随之恢复。
在编辑器中或从 SLO 创建的规则带有 service.name、service.namespace、deployment.environment 和 apm.endpoint 标签（取决于规则指定了哪些对象），事件会复制这些标签。所有 APM 规则的事件还带有 service 标签、affected_services 中的服务，以及取自聚合的一个样本 trace ID。服务目录的告警列、服务页标题栏和端点抽屉统计指向该服务的已打开和已确认事件；事件指定了环境时，只统计该服务所在环境的事件。端点抽屉只统计带有该端点标签的事件。点击数量打开告警 → 事件。
同一菜单中的异常检测告警在指标明显偏离过去几天同一时刻时告警，不需要设置阈值。见对 APM 指标设置异常检测告警。
过滤、分辨率与保留
APM 页面共享全局时间范围。服务目录可按环境和团队筛选，服务页可按环境和版本筛选。列表支持搜索和排序。范围会编码进 URL，便于分享或重新打开。 使用默认部署设置时：- API 未指定范围时查询最近 24 小时；
auto对不超过 24 小时的范围使用分钟桶，对更长范围使用小时桶；- 分钟聚合保留 24 小时；
- 小时聚合和最大查询范围为 30 天。
阅读数据质量提示
每个 APM 响应都带有数据质量元数据。有需要说明的情况时，导航卡片中会出现简短提示，点击查看详情。
请先缩短时间范围并收窄过滤条件。如果部分或延迟状态持续存在，再检查 APM 健康端点与平台遥测。
运行时指标
运行时分区展示服务带上service.name 上报的运行时指标：先是任何语言都有的进程指标，然后是服务在 telemetry.sdk.language 中上报的每种语言的运行时；没有上报语言时，显示所有有指标的运行时。每个图表中每个实例一条线（实例按上文的方式区分），同时支持本平台存储的 OpenTelemetry 语义约定和各运行时常用的 Prometheus 客户端。每个图表取下列指标中服务上报的第一个：
JVM 的堆内存和非堆内存图表读取
jvm.memory.type（OpenTelemetry）或 area（Micrometer）标签。计数器画成五分钟内的每秒速率。Go 的调度延迟是五分钟内的平均值，即直方图的总和除以计数。
分区末尾的 Profiling 把服务在时间范围内的 Profile 合并成火焰图，一次看一种类型，例如 CPU、墙钟、内存分配、堆和锁。在 Profiles 中打开会转到 Profiles 页面继续分析。
隐私与有界数据
APM 保存聚合以及少量脱敏后的证据。APM 聚合不会保留请求体、响应体、URL 查询参数值、Header 或 SQL 参数；SQL 语句只以模板形式保留，所有字面量都替换为?。标识值、代表性消息和栈帧都有长度限制；疑似敏感或易变化的值会在持久化之前删除或掩码。
这些保护不能替代良好的埋点习惯。不要把密钥或个人数据放入 span 名称、状态描述、异常消息或资源属性。
故障排查
APM API
查询 APM 目录、详情、错误状态、服务定义、版本对比与健康状态。
告警与事件响应
通过升级策略和通知渠道处理 APM 事件。
链路
检查 APM 证据背后的具体 span 与 trace。
服务地图
可视化跨服务父子 span 关系。
链路采集
把 OpenTelemetry trace 发送到 MoleSignal。