可观测性与稳定性 / 系统课时
应用 Semantic Conventions
应用 Semantic Conventions
Semantic Conventions 把“同一件事”统一成可跨语言、跨服务消费的字段和命名。本课用 HTTP、RPC、数据库与消息四类遥测建立一套落地方法,并说明约定升级时怎样避免查询、仪表盘和告警一起失效。
学习目标
- 能按领域选择标准的 Span 名称、属性与指标语义,而不是自造近义字段
- 能识别 HTTP、RPC、数据库和消息遥测中的关键语义属性
- 能评估语义约定版本变化对采集端与后端消费端的影响
把语义约定当成数据契约
Semantic Conventions 不只是“推荐字段名”。它同时约束属性名称、类型和含义,也会规定 Span 名称、Span Kind、指标名称与单位等。只有生产端和消费端理解的是同一份契约,跨服务查询、聚合和关联才不会依赖某个 SDK 的私有命名。
工程上应先查现有约定,再决定是否增加自定义属性。确实没有标准字段时,自定义命名空间也不要占用 OpenTelemetry 已使用的标准命名空间,否则未来标准新增同名字段时会产生冲突。
按领域选择标准属性
下面是片段示例,用来展示四类 Span 的“语义形状”;它不是可直接发送的完整 OTLP 报文,真实字段的 Requirement Level 与稳定性应以所用 Semantic Conventions 版本和 instrumentation 文档为准。
{
"httpServerSpan": {
"name": "GET /orders/{id}",
"attributes": {
"http.request.method": "GET",
"http.response.status_code": 200,
"http.route": "/orders/{id}",
"server.address": "api.example.test"
}
},
"rpcClientSpan": {
"name": "catalog.v1.Catalog/GetItem",
"attributes": {
"rpc.system.name": "grpc",
"rpc.method": "catalog.v1.Catalog/GetItem"
}
},
"databaseClientSpan": {
"name": "SELECT orders",
"attributes": {
"db.system.name": "postgresql",
"db.namespace": "shop",
"db.operation.name": "SELECT",
"db.collection.name": "orders"
}
},
"messagingConsumerSpan": {
"attributes": {
"messaging.system": "kafka",
"messaging.destination.name": "orders",
"messaging.operation.name": "process"
}
}
}验证时不要只检查“有没有属性”,还要检查值的语义。例如 HTTP 服务端应优先记录路由模板 /orders/{id},而不是把 /orders/847291 之类真实路径冒充 http.route;数据库操作也不要把 SQL 文本塞进 db.operation.name。
| 领域 | 优先表达的问题 | 常见标准属性 |
|---|---|---|
| HTTP | 方法、路由、状态与对端 | http.request.method、http.route、http.response.status_code、server.address |
| RPC | RPC 系统、逻辑方法与结果 | rpc.system.name、rpc.method、rpc.response.status_code |
| 数据库 | DBMS、命名空间、操作与目标 | db.system.name、db.namespace、db.operation.name、db.collection.name |
| 消息 | 消息系统、目的地与操作 | messaging.system、messaging.destination.name、messaging.operation.name |
处理约定版本变化
Semantic Conventions 会独立演进,而且不同领域的成熟度可能不同。升级 instrumentation 时,风险不只在采集端:字段重命名、Span 名称变化、指标单位变化都会影响后端查询、仪表盘、告警、采样规则和保存的检测逻辑。历史上就出现过 http.method 迁移到 http.request.method、db.system 迁移到 db.system.name 这类变化。

因此升级前应记录三件事:当前 instrumentation 实际发出的约定版本或字段集合、后端依赖这些字段的查询清单、迁移期间是否支持旧新语义并存。若某个 instrumentation 明确支持 OTEL_SEMCONV_STABILITY_OPT_IN,再按它的迁移文档选择对应领域的 opt-in 或兼容模式;不要假设所有语言和所有 instrumentation 都支持相同开关。
建立可重复的验收
先在预发布环境抓取一批真实 Span 与 Metric,按 HTTP、RPC、数据库、消息各抽样检查字段名称、类型、值域和 Span 名称。再运行现有仪表盘、告警和追踪查询,确认新旧版本下结果口径一致;若使用双写,只把它作为迁移窗口,不要永久保留重复属性。
真正落地 Semantic Conventions 的标准不是“字段看起来像官方名字”,而是生产端、Collector、存储与查询端对同一语义达成一致,并且版本升级时有可验证的迁移路径。