OpenTelemetry 怎样为服务添加资源属性

OpenTelemetry 的服务级信息应放在 Resource 中，并在创建 TracerProvider、MeterProvider 或 LoggerProvider 时绑定。最小可用做法是设置 service.name，再按需要补充版本和实例标识；不要把这些稳定信息重复写到每个 Span 的属性里。

官方地址：https://opentelemetry.io/

本文只讨论 OpenTelemetry 为服务添加资源属性：如何写、如何用环境变量补充，以及为什么初始化完成后不能指望再改 provider 的 Resource。

Resource 和 Span 属性不是一回事

Resource 描述“谁在产生遥测数据”，例如服务名、服务版本、实例 ID、部署环境、容器或主机信息；Span 属性描述“一次请求发生了什么”，例如 HTTP 路径、订单号或数据库操作。前者适合跨 trace、metric 统一筛选，后者只属于某个遥测记录。

OpenTelemetry SDK 没有显式设置服务名时，通常会给出 unknown_service。这会让后端按服务聚合时失去稳定入口，因此 service.name 应成为初始化清单中的必填项。

用语义约定创建并绑定 Resource

Go SDK 提供 resource.NewWithAttributes 创建资源，属性键优先使用 semconv 的语义约定。下面的代码只展示 Resource 与 trace provider 的关系，SDK 模块版本应与项目现有依赖保持一致。

package telemetry

import (
    "context"

    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    "go.opentelemetry.io/otel/semconv/v1.30.0"
)

func NewTracerProvider(ctx context.Context) (*sdktrace.TracerProvider, error) {
    res, err := resource.New(ctx,
        // 用语义约定保证 service.name 和版本键能被后端稳定识别。
        resource.WithAttributes(
            semconv.ServiceNameKey.String("order-api"),
            semconv.ServiceVersionKey.String("2026.10"),
            attribute.String("deployment.environment.name", "production"),
        ),
    )
    if err != nil {
        // 初始化失败直接返回，避免服务带着不完整的遥测配置继续运行。
        return nil, err
    }

    // Resource 在 provider 创建时绑定，之后由该 provider 产生的 Span 共享它。
    return sdktrace.NewTracerProvider(sdktrace.WithResource(res)), nil
}

如果只需要固定的少量属性，也可以直接使用 resource.NewWithAttributes。关键不在函数名，而在于把 Resource 交给 provider 的 WithResource 选项，并且在第一次创建 provider 前完成。

代码属性和环境变量怎样合并

容器部署时，服务名和部署环境经常由发布系统注入。OpenTelemetry 支持 OTEL_SERVICE_NAME 与 OTEL_RESOURCE_ATTRIBUTES，Go 侧可用 resource.WithFromEnv() 读取，再用 resource.WithAttributes 放置代码中必须固定的属性。

res, err := resource.New(ctx,
    // 读取 OTEL_SERVICE_NAME 与 OTEL_RESOURCE_ATTRIBUTES。
    resource.WithFromEnv(),
    // SDK 自身信息和进程信息由对应 detector 补充。
    resource.WithTelemetrySDK(),
    resource.WithProcess(),
    // 代码属性用于保证关键业务标识不会随部署脚本遗漏。
    resource.WithAttributes(
        semconv.ServiceNameKey.String("order-api"),
    ),
)
if err != nil {
    // PartialResource 等非致命问题可记录；真正的初始化错误需要停止启动。
    return nil, err
}

部署侧可以这样设置一组属性：

# 服务名单独设置，其他键放入逗号分隔的资源属性列表。
export OTEL_SERVICE_NAME=order-api
export OTEL_RESOURCE_ATTRIBUTES='deployment.environment.name=production,service.version=2026.10'

初始化时机决定资源边界

Resource 是 provider 初始化时的服务级身份。官方文档明确说明，provider 创建后不能再改变已经关联的 Resource；因此不要在请求处理函数里根据租户、用户或请求参数修改 service.name。这些变化属于 Span 属性、Baggage 或业务字段，应按对应语义记录。

实际落地时可以按下面的边界检查：

最后确认三件事：服务名不是 unknown_service；provider 创建时已经带上 Resource；环境变量中的键名和代码中的语义键没有互相覆盖到不可预期。做到这三点，后端就能用稳定服务身份聚合 trace 和 metric。

常见问题

Resource 属性能在 provider 创建后修改吗？

不能把它当成可变配置。需要变更服务身份时，应重新初始化对应 provider，或在新的服务实例启动时提供新的 Resource。

所有自定义字段都应该放进 Resource 吗？

不是。只有描述遥测生产者且在同一服务实例范围内稳定的字段适合 Resource；请求级、用户级和业务实体级字段应留在 Span、Metric 或业务数据中。

只设置 OTEL_SERVICE_NAME 够不够？

它能解决服务名缺失，但生产环境通常还需要服务版本、部署环境和实例信息。可以用环境变量统一注入，也可以在代码中补充不可由部署系统保证的固定属性。