可观测性与稳定性 / 系统课时

应用 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 文档为准。

json
{
  "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、存储与查询端对同一语义达成一致,并且版本升级时有可验证的迁移路径。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

应用 Semantic Conventions

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通