telemetry-foundations

遥测基础

概述

为 HVE Core Agent 建立一套通用的可观测性词汇。本技能说明遥测数据有哪些以及如何命名，而不是指定使用哪个 SDK 或供应商。生成规划文档（ADR、PRD、安全／RAI 计划、代码审查报告）的 Agent，以及生成面向用户的应用程序代码的 Agent，都会参考本技能，确保下游管道（追踪、指标、日志）使用与 OpenTelemetry 一致的语言。

适用场景

在以下情况下应用本技能：

• 任何生成会发出 span、指标或结构化日志的面向用户应用程序代码的 Agent。
• 涉及可观测性、监控或审计日志的架构决策记录。
• 标出遥测缺失、span 命名不一致或指标基数无界问题的代码审查报告。
• 引用审计日志、可追溯性或证据链的安全或负责任 AI 计划。
• 规定以服务遥测表示的成功指标的产品或业务需求文档。

核心原则

本技能中的词汇遵循五项原则：

• 声明式，而非规定式。定义名称和形式；SDK、导出器和后端的选择留给实现团队。
• 与 OpenTelemetry 对齐。追踪、指标和日志模型遵循 OTel 数据模型，确保文档可移植。
• 优先采用语义约定。对于存在 OTel 语义约定的领域（HTTP、RPC、数据库、消息传递、GenAI、FaaS），优先使用该约定，而非自定义属性。
• 通过拒绝名单保护 PII。按照 references/pii-denylist.md 中的拒绝名单，默认拒绝 PII；其中列出的任何字段在发出前都必须有明确的脱敏策略。
• 与供应商无关。避免让词汇绑定到单一后端；默认使用 OTLP 作为线路协议。

追踪词汇

Span 描述一项工作单元及其与其他工作的因果关系。

Span 类型：

• server - 由此服务处理的入站请求。
• client - 此服务发出的出站请求。
• producer - 向队列或主题发布的异步消息。
• consumer - 从队列或主题接收的异步消息。
• internal - 没有远程对端的进程内操作。

每个 span 必须包含的资源级属性：

• service.name
• service.version
• deployment.environment

Span 命名模式：使用小写、以点分隔的标记，格式为 <verb>.<resource>。动词描述操作（get、create、publish、consume、query）；资源描述目标实体（order、customer、payment.intent）。示例：get.order、publish.order.created、query.customer.by_email。

对于受 OTel 语义约定覆盖的领域（HTTP、RPC、数据库、消息传递、GenAI、FaaS），请使用该约定的 span 命名指南，而非上述通用模式。

指标术语

指标描述随时间变化的聚合测量值。

仪器类型：

• counter - 单调递增、可累加（请求数、发送的字节数）。
• up-down-counter - 非单调、可累加（队列深度、活动连接数）。
• histogram - 值的分布（请求时长、负载大小）。
• gauge - 最近一次采样的值、不可累加（CPU 温度、已使用内存）。
• observable-counter、observable-up-down-counter、observable-gauge - 由 SDK 轮询的异步变体。

单位约定遵循 UCUM。示例：s（秒）、ms（毫秒）、By（字节）、1（无量纲计数）。默认将时长表示为以秒（s）为单位的直方图，以符合 OTel HTTP 语义约定。

指标命名模式：<domain>.<entity>.<measure>，使用以点分隔的小写标记。示例：http.server.request.duration、db.client.connections.usage、messaging.publish.duration。

基数管理：附加到指标的每个属性都会使时间序列数量成倍增加。在源头限制高基数维度（用户 ID、请求 ID、自由格式字符串），或将其移至示例和跟踪中。

日志术语

结构化日志记录具有严重性和上下文的离散事件。

严重性级别（OTel 日志数据模型）：

• TRACE - 细粒度诊断详情，默认关闭。
• DEBUG - 在开发期间有用的诊断详情。
• INFO - 正常运行事件。
• WARN - 不会阻止操作的异常情况。
• ERROR - 操作失败；调用方很可能遇到了失败。
• FATAL - 进程即将终止。

建议每条日志记录都包含以下结构化字段：

• timestamp（ISO-8601，UTC）。
• severity_text 和 severity_number。
• body（人类可读的消息；结构化数据放在 attributes 中）。
• attributes.*（作用域限定于此事件的类型化键值对）。
• resource.*（从生成日志的服务继承）。

跟踪关联：在活动 Span 中发出日志记录时，注入 trace_id 和 span_id，以便下游能够将跟踪与日志关联起来。与 OTel 上下文传播器集成的日志库会自动完成此操作。

PII 处理

个人身份信息采用拒绝列表进行处理。权威列表位于 references/pii-denylist.md。将列表中的任何字段视为默认拒绝：除非有明确的脱敏策略，否则不得将其作为 Span 属性、指标维度或日志字段发出。

脱敏模式：

• 哈希 - 对必须在不同事件间保持可关联、但不应以人类可读形式呈现的字段进行单向哈希（SHA-256，可选择截断）。
• 丢弃 - 完全省略该字段。
• 令牌化 - 替换为不透明令牌，且只能通过单独的访问受控存储解析。

标识符约定：当遥测数据需要稳定的用户引用时，使用 user.id，并填入规范用户标识符的不透明哈希值，绝不使用原始电子邮件、电话号码或外部账号 ID。

引入可能包含 PII 的新属性时，先将其添加到拒绝列表，并在发出该属性前选择脱敏策略。

采样与成本

采样用于控制发送到下游收集器的遥测数据量。

采样策略：

• 基于头部 - 在 Span 开始时做出决策，并通过跟踪传播。成本低、简单，但无法根据稍后才发现的属性（例如错误）进行偏向性采样。
• 基于尾部 - 在跟踪完成后做出决策，通常由收集器执行。成本较高，但可支持“保留所有错误跟踪”和“保留慢速跟踪”等策略。

默认设置：

• 使用基于父级的采样器，让子 Span 继承父级的采样决策，并保持跟踪完整。
• 可使用基于尾部的采样时，优先保留错误跟踪，并对成功跟踪进行有代表性的采样。

指标和日志采样：指标会预先聚合，通常很少采样；日志通常按严重性进行速率限制，而不是采样。

资源属性

资源属性描述生成遥测数据的实体，并由 SDK 自动附加到每个跨度、指标和日志记录中。

必需：

• service.name
• service.version
• deployment.environment
• telemetry.sdk.name
• telemetry.sdk.language
• telemetry.sdk.version

适用时建议使用：

• cloud.*（云提供商、区域、账号 ID）。
• k8s.*（集群名称、命名空间、Pod 名称）。
• host.*（主机名、架构、操作系统类型）。

请遵循 OTel 资源语义约定，使用规范的属性名称。

决策树

选择是否进行检测以及如何检测时，可使用以下快速指南：

1. 这是否面向用户或属于用户可见的流程？如果不是，优先使用 DEBUG 日志；除非容量规划需要，否则跳过跨度和指标的生成。
2. 拟议属性的基数是否有界？如果没有，请将无界字段移至日志属性或跟踪示例，而不是用作指标维度。
3. 数据是否包含或源自 references/pii-denylist.md 中的字段？如果是，请在生成数据前应用脱敏策略。
4. 操作是否跨越服务边界（网络、队列、进程）？如果是，请生成具有相应 server、client、producer 或 consumer 类型的跨度，并传播上下文。
5. 操作是否具有高流量？如果是，请依赖基于父跨度的采样，以及（如可用）基于尾部的策略；不要彻底禁用检测。
6. OpenTelemetry 语义约定是否涵盖此领域？如果是，请使用其中的属性名称和跨度命名指南；如果不是，请遵循此技能中的命名模式，并在 references/proposed-additions.md 中提出新条目。

参考资料

权威外部来源：

• OpenTelemetry 语义约定 v1.41.0
• W3C 跟踪上下文
• OpenTelemetry 协议（OTLP）规范
• OpenTelemetry 日志数据模型
• OpenTelemetry FaaS 语义约定

部分内容改编自 OpenTelemetry 语义约定，(C) OpenTelemetry Authors，依据 CC BY 4.0 许可。

内部资料：

• references/pii-denylist.md - 权威的 PII 禁用列表及脱敏策略。
• references/proposed-additions.md - 新词汇提案的提交入口。