OpenTelemetry 语义约定：让遥测数据说同一种语言
OpenTelemetry 语义约定（Semantic Conventions）统一了遥测属性与事件的命名规范（如 service.name、http.request.method），让不同语言、不同框架产出的数据可以互相对齐。本文讲解 Resource/Trace/Metric/Log 四类约定与自定义属性命名规则。
OpenTelemetry 语义约定是一套标准化的命名规范，规定遥测数据中资源、Span、指标与事件的属性名称、类型与取值——没有它，同样的 HTTP 请求在 Java 里叫 httpMethod、在 Go 里叫 http_method，跨语言分析就无从谈起；有了它，任何服务的数据都能用同一套查询与视图分析。
核心要点速览
- 语义约定的价值：数据可移植、视图可复用、工具可自动理解数据含义；
- 四大类约定：Resource（数据来源）、Trace（调用语义）、Metric（指标命名）、Log/Event；
- 遵循稳定性等级：稳定约定放心用，实验性约定留意变更；
- 自定义属性用反向域名前缀命名（如
com.example.order.id），避免与标准冲突。
语义约定为什么重要？
可观测性数据的分析价值取决于一致性：告警规则、仪表板、AI 根因分析都建立在「字段含义确定」的假设上。语义约定把约定俗成变成明文标准，让 http.request.method=GET 在任何语言、任何框架中都长一个样。
四类核心约定
Resource 语义约定
描述「谁产生了数据」：service.name（服务名，最重要的一个）、service.version、deployment.environment.name、host.name、k8s.pod.name、cloud.region 等。统一资源属性是后续按服务、环境、地域切片分析的基础。
Trace 语义约定
描述「这次调用是什么」：HTTP（http.request.method、http.response.status_code、url.path）、数据库（db.system、db.statement）、消息队列（messaging.system、messaging.destination.name）、RPC 等场景的 Span 名称与属性规范。
Metric 语义约定
规定指标命名（小写、点分层级、复数单位后缀如 http.server.request.duration）、单位（秒、字节用 UCUM 标准）、仪器类型选择与属性的需求级别（Required/Recommended/Optional）。
Log 与 Event 语义约定
日志记录的标准字段（如 severity_text、异常字段 exception.type/message/stacktrace），以及事件（Event）的命名规范（如 exception 事件）。
自定义属性怎么命名？
业务字段没有标准约定时，遵循两条规则：
- 加公司/项目前缀：
com.example.order.id、com.acme.user.tier，避免与未来标准冲突； - 保持低基数警觉：自定义属性进入指标标签时遵守基数纪律（见《高基数问题》）。
观测云落地
观测云的数据模型与 OTel 语义约定天然对齐：
- 服务识别：
service.name直接映射为 APM 中的服务名，务必规范填写； - 环境划分：
deployment.environment.name等属性用于区分生产/测试数据； - 内置视图：观测云的内置视图与监控模板基于标准属性设计，遵循约定的数据开箱即用；
- 关联分析：日志中注入
trace_id、service等字段后，与链路、指标自动关联。
常见问题（FAQ）
Q：语义约定会变吗？我的埋点要跟着改吗？ 约定分稳定与实验两级。稳定约定承诺向后兼容；实验性约定可能调整。SDK 升级时关注 release notes 即可。
Q：老埋点不符合约定怎么办？ 不必改代码——在 Collector 用 OTTL 做属性重命名，或在观测云 Pipeline 侧做字段映射，统一到标准命名。
Q：HTTP 语义约定为什么感觉老在改？ HTTP 约定经历过一次大的稳定化重构（如 http.method → http.request.method），稳定后不再变动。以所用 SDK 版本对应的约定文档为准。
Q：必须背下所有约定吗？ 不需要。自动埋点产生的数据天然遵循约定；手动埋点时查官方文档对应场景的约定表即可。
