资源 SDK

状态：稳定，除非另有说明

一个 资源 是产生遥测数据的实体的不可变表示，以 属性 的形式。例如，一个在 Kubernetes 容器中运行的产生遥测数据的进程具有 Pod 名称，它位于一个命名空间中，并且可能是一个也具有名称的 Deployment 的一部分。这三个属性都可以包含在 Resource 中。请注意，某些 属性 具有规定含义。

资源作为 SDK 中的一等概念的主要目的是将资源信息的发现与导出器分离开。这使得用户能够独立开发并轻松定制，以便与闭源环境集成。SDK 必须允许创建 Resources 并将它们与遥测数据关联。

与分布式跟踪结合使用时，可以在创建 TracerProvider 时将资源与之关联。此后不能更改此关联。当与 TracerProvider 关联时，由该提供程序生成的任何 Span 都必须与此 Resource 关联。

与分布式跟踪类似，与指标结合使用时，可以将资源与 MeterProvider 关联。当与 MeterProvider 关联时，由该提供程序生成的任何 Meter 的所有指标都将与此 Resource 关联。

SDK 提供的资源属性

SDK 必须提供对资源（至少包含 具有 SDK 提供的默认值的语义属性 中列出的属性）的访问。如果未明确指定其他资源，则此资源必须与 TracerProvider 或 MeterProvider 关联。

注意：这意味着可以创建并关联一个不包含所有或任何 SDK 提供的属性的资源。但是，默认情况下不会发生这种情况。如果用户希望将自定义属性与默认资源合并，他们可以使用 Merge 操作与自定义资源进行合并，或者通过实现 自定义资源探测器 来指定属性，而不是显式关联资源。

资源创建

SDK 必须支持两种实例化新资源的方式。它们是：

创建

该接口必须提供一种方法，根据 属性 创建新资源。例如，工厂方法或资源对象的构造函数。建议使用工厂方法以支持缓存对象。

必需参数

  • Attributes
  • [since 1.4.0] schema_url (可选): 指定在发出的资源中记录的 Schema URL。如果 schema_url 参数未指定，则创建的资源将具有空的 Schema URL。

合并

该接口必须提供一种方法，用于将旧资源和更新资源合并为新资源。

注意：这旨在用于合并来自不同来源的资源的属性，例如环境变量或从主机或容器中提取的元数据。

结果资源必须包含任一输入资源上的所有属性。如果一个键同时存在于旧资源和更新资源上，则必须采用更新资源的值（即使更新后的值为空）。

结果资源将按照以下方式计算 Schema URL：

  • 如果旧资源的 Schema URL 为空，则结果资源的 Schema URL 将设置为更新资源的 Schema URL；
  • 否则，如果更新资源的 Schema URL 为空，则结果资源的 Schema URL 将设置为旧资源的 Schema URL；
  • 否则，如果旧资源和更新资源的 Schema URL 相同，则该 URL 将是结果资源的 Schema URL；
  • 否则，这是一个合并错误（当旧资源和更新资源的 Schema URL 均不为空且不同时）。结果资源未定义，其内容特定于实现。

必需参数

  • 旧资源
  • 更新资源，其属性具有优先权

空资源

建议（但不强制）提供一种快速创建空资源的方法。

从环境中检测资源信息

与通用平台（例如 Docker、Kubernetes）或特定供应商环境（例如 EKS、AKS、GKE）相关的自定义资源探测器必须实现为独立于 SDK 的包。

资源探测器包必须提供一种返回资源的方法。然后，该资源可以按照上述说明与 TracerProvider 或 MeterProvider 实例关联。

资源探测器包可以检测来自多个可能来源的资源信息，并使用上述 Merge 操作合并结果。

资源探测逻辑预计会很快完成，因为这段代码将在应用程序初始化期间运行。错误应按照 错误处理原则 中的规定进行处理。请注意，未能检测到任何资源信息不得视为错误，而尝试检测资源信息时发生的错误应视为错误。

填充符合 OpenTelemetry 语义约定的资源属性的资源探测器必须确保资源具有一个 Schema URL，该 URL 设置为与语义约定匹配的值。如果探测器没有用任何具有语义约定的已知属性填充资源，或者探测器不知道它将填充什么属性（例如，从环境变量读取属性的探测器将不知道使用什么 Schema URL），则应使用空的 Schema URL。如果组合了多个探测器，并且探测器使用了不同的非空 Schema URL，则这必须是错误，因为无法合并此类资源。结果资源未定义，其内容特定于实现。

资源探测器名称

状态: 开发中

资源探测器应具有唯一的名称，以便在配置中进行引用。例如，用户可以在 声明式配置 中按名称列出和配置单个资源探测器。名称应为 snake_case，并包含小写字母数字字符和 _，这确保它们符合声明式配置 属性名称要求。

资源探测器名称应反映其填充的属性的 根命名空间。例如，一个名为 os 的资源探测器会填充 os.* 属性。填充来自多个根命名空间的资源探测器应选择一个能恰当传达其用途的名称。

识别多个同名资源探测器的 SDK 应报告错误。为了限制冲突，资源探测器应以易于发现的方式记录其名称。资源探测器的作者应检查现有的资源探测器，以确保其目标名称尚未被使用。此外，以下探测器名称保留给随语言 SDK 一起发布的内置资源探测器：

通过环境变量指定资源信息

SDK 必须从 OTEL_RESOURCE_ATTRIBUTES 环境变量中提取信息，并将其作为辅助资源与用户提供的任何资源信息进行 合并，即用户提供的资源信息具有更高的优先级。

OTEL_RESOURCE_ATTRIBUTES 环境变量将包含键值对列表，这些键值对应采用 W3C Baggage 的格式，但不支持额外的分号分隔的元数据，即：key1=value1,key2=value2。所有属性值都必须视为字符串，并且 baggage-octet 范围之外的字符必须进行百分比编码。

资源操作

资源是不可变的。因此，除了资源创建之外，只应提供以下操作：

检索属性

SDK 应提供一种方法来检索与资源关联的只读属性集合。

无需保证属性的顺序。

检索属性时最常见的操作是枚举它们。因此，建议优化结果集合以快速枚举，而不是考虑其他因素，例如一种快速检索具有特定键的属性值的方法。