语义约定是什么
语义约定（Semantic Conventions）规定属性与字段的命名口径：HTTP 用请求方法与响应状态码的标准名，数据库用系统名与操作类型的标准名。它的作用是把「同一个含义在不同服务里写法不同」这件事消灭掉——命名统一后，看板、检索与告警规则才能跨服务复用。约定本身在版本演进中调整过命名风格，迁移期需要新旧字段并行一段时间再切换。
基本信息
| 适用平台 | OpenTelemetry 各语言 SDK 与 Collector |
|---|---|
| 覆盖范围 | 资源属性、span 属性、事件与日志字段 |
| 演进情况 | 新版本把部分字段改为带前缀的层级命名 |
| 落地方式 | 以 SDK 版本为准，统一迁移或双写过渡 |
典型使用场景
- 统一埋点：多个团队按同一套字段名上报，看板可直接复用
- 跨服务分析：用统一的字段筛选链路，不受实现语言影响
- 数据库观测：统一记录数据库系统与操作类型，便于慢查询分析
- 日志关联：字段名一致后日志与链路可以直接按标识关联
- 规范评审：新埋点上线前按约定清单核对字段名
常用字段对照
常用字段对照
# HTTP 相关 span
http.request.method = GET # 新式命名
http.response.status_code = 500
url.path = /v1/orders/1024
server.address = api.internal
# 数据库相关 span
db.system = mysql
# db.operation = SELECT
# 旧式命名示例（迁移期可能同时出现）
# http.method / http.status_code
# 迁移建议：先双写新旧字段，确认消费方全部切换后再下线旧字段字段命名对照
| 用途 | 新式写法 | 迁移注意 |
|---|---|---|
| HTTP 方法 | http.request.method | 旧版为 http.method |
| 响应状态码 | http.response.status_code | 旧版为 http.status_code |
| 请求路径 | url.path | 旧版为 http.target |
| 数据库系统 | db.system | 值用小写系统名 |
| 服务端地址 | server.address | 旧版为 net.peer.name |
版本差异是迁移中的主要坑：同一集群里新旧字段并存时，看板会出现双份分组，建议先双写再统一切换，切换后保留一个观察周期。
自定义字段命名也要有规范：错误码统一用同一种风格，避免同一含义出现多种写法导致跨团队查询无法复用。