用途:这是一套语言无关的 OpenTelemetry 约定,用于在新增或评审 span、结构化日志等遥测信号时,保证信号可查询、可互操作,并显式表达操作结果。
主要能力与做法:
- 把 span 当作操作记录,把具名日志记录当作事件记录。在代表操作的 span 上记录安全、有界、对运维有用的输入、最终输出与结果;仅在有意的时间点发生事件时才发出具名日志。不要从一种信号推断另一种信号。
- 在定义应用属性前先使用既有的 OpenTelemetry 语义约定;当规范未定义时,把自定义策略与 OpenTelemetry 要求显式分开。
- 每个日志记录在活动 span 期间都要保留 trace 与 span 关联;结构化日志记录优先使用稳定 eventName,便于消费者选择正确的属性模式。
- 带时长的子操作用子 span 表示,而不是完成事件;每次循环执行都用自己的 span,以便时长、结果、决策与每次迭代记录保持关联。
- 不要仅因 span 结束就发成功日志;span 的结束时间、最终属性与状态已记录完成。所有可失败工作完成后显式将成功 span 设为 OK 并保持。
- 失败操作的结果独立于异常记录位置来判定;先应用语义约定再应用自定义策略。
- 使用目标语言官方语义约定库中的稳定常量与 API,并遵循其稳定性指引。
- 遥测中排除密钥、凭证、个人数据与无界负载。
适用场景:为跨语言、SDK、收集器与后端的遥测设计统一约定,评审 span、日志、循环与异常记录,判定错误结果与严重级别。
限制:资料为示例性 JavaScript SDK 代码,需按目标语言的官方 OpenTelemetry API、原生异常链与资源管理约定适配;未提供具体安装命令、价格或平台支持信息。