可观测性与稳定性 / 系统课时
统一服务身份与 Resource 属性
统一服务身份与 Resource 属性
Resource 属性决定后端如何把 Span、Metric 和 Log 归到同一个实体。真正需要治理的不是“多加几个标签”,而是让服务名、命名空间、环境和实例身份各司其职,避免同名服务混在一起或部署后不断漂移。
学习目标
- 设计稳定的
service.name、service.namespace与部署环境属性。 - 区分逻辑服务身份、部署上下文和实例级身份。
- 通过 SDK 环境变量与 Collector 处理器减少命名漂移。
先把身份与上下文分开
service.name 表示逻辑服务名,同一服务的水平副本应保持一致;service.namespace 用来区分不同系统或业务域中的同名服务。两者组合后,后端更容易稳定地聚合同一逻辑服务,而不是把 Pod 名、主机名或版本号误塞进服务名。
deployment.environment.name 表示部署环境,例如 production、staging、development 或 test。它是查询和分组维度,不改变服务本身的逻辑身份。旧属性 deployment.environment 已被替代,新接入应使用 deployment.environment.name。
| 属性 | 建议职责 | 示例 | 是否应随副本变化 |
|---|---|---|---|
service.namespace |
系统、业务域或组织命名空间 | commerce |
否 |
service.name |
逻辑服务名 | checkout |
否 |
deployment.environment.name |
部署环境 | production |
否,同一环境内稳定 |
service.instance.id |
单个运行实例身份 | checkout-7f6c9d8b7f-x2k4m |
是,不同并发实例应唯一 |

先定命名规则再接入 SDK
团队应先固定命名来源,再让所有语言 SDK 和部署平台遵守同一规则。一个实用策略是让 service.namespace 对应稳定业务域,让 service.name 对应仓库或部署单元的逻辑名称,并把环境、版本、Pod 名等放进各自的标准属性。
例如生产环境中的结算服务可以使用 service.namespace=commerce、service.name=checkout、deployment.environment.name=production。发布新版本时只更新 service.version;扩容副本时只让 service.instance.id 不同。不要生成 checkout-prod-v42 这类服务名,否则一次发布或环境切换就会制造新的“服务”。
在遥测源头写入稳定属性
应用侧应优先设置它自己最清楚的身份。OpenTelemetry SDK 通常支持 OTEL_SERVICE_NAME 和 OTEL_RESOURCE_ATTRIBUTES;当两处同时提供 service.name 时,OTEL_SERVICE_NAME 的值优先,因此不要在两个入口维护不同答案。
下面是启动环境的主示例。它把服务名放在专用变量中,其余稳定 Resource 属性集中放进 OTEL_RESOURCE_ATTRIBUTES:
export OTEL_SERVICE_NAME='checkout'
export OTEL_RESOURCE_ATTRIBUTES='service.namespace=commerce,deployment.environment.name=production,service.version=1.14.3'
printf '%s\n%s\n' "$OTEL_SERVICE_NAME" "$OTEL_RESOURCE_ATTRIBUTES"预期输出:
checkout
service.namespace=commerce,deployment.environment.name=production,service.version=1.14.3这一步只能证明部署环境已正确注入变量。真正验收时还要在追踪、指标或日志后端检查 Resource,确认三种信号看到相同的 service.namespace、service.name 与 deployment.environment.name,而不是只有某一种信号配置正确。
让 Collector 只补它真正知道的上下文
共享 Gateway 不应无条件重写 service.name,因为一个 Gateway 往往同时接收多个服务;如果在这里把所有数据 upsert 成同一名称,会直接把不同服务合并。Collector 更适合补充它能够确定的基础设施或环境上下文。
片段示例:假设这个 Gateway 只承载 production 环境,可以统一修正环境属性;该处理器仍需挂到实际的 traces、metrics 或 logs pipeline 才会生效。
processors:
resource/environment:
attributes:
- key: deployment.environment.name
value: production
action: upsertupsert 会让进入该 Gateway 的数据统一使用 production,因此只有在 Gateway 与环境一一对应时才安全。若同一个 Gateway 同时接收多个环境,应从可信路由信息推导属性,或在应用侧设置后原样保留,不能使用这段固定值配置。
用门禁发现同名和漂移
上线前至少检查三类问题。首先,不允许正式服务长期以 unknown_service 进入后端;这通常说明服务名没有在应用启动时注入。其次,同一个 service.namespace 下的 service.name 应对应唯一逻辑服务,不能让两个团队各自把不同系统都命名为 api、worker 这类过宽名称。
最后,查询和告警应显式带上 deployment.environment.name。同一个逻辑服务可以同时存在于 production 和 staging;如果仪表盘只按 service.name 聚合,两套环境的数据仍可能被混在一起。service.instance.id 则用于下钻到单实例,不应拿它作为长期服务级看板的主分组键。
稳定的做法是:服务自己声明逻辑身份,部署系统提供环境和版本,运行平台生成实例信息,Collector 只补充它能可靠判断的上下文。这样即使扩容、滚动发布或迁移集群,服务级时间序列和追踪视图仍能保持连续。