资源语义约定
状态: 混合
本文档定义了资源的标准属性。这些属性通常用于 Resource，并且也建议在任何需要一致地描述资源的地方使用。这些属性中的大部分继承自 OpenCensus Resource standard。
待办事项
- 添加更多计算单元：AppEngine 单元等。
- 添加 Web 浏览器。
- 决定是否只使用小写字符串。
- 考虑为每个属性和属性组合添加可选/必需（例如，当提供 k8s 资源时，所有 k8s 可能都是必需的）。
文档约定
状态: 稳定
属性按它们描述的概念类型进行逻辑分组。同一组中的属性具有以点结尾的公共前缀。例如，所有描述 Kubernetes 属性的属性都以“k8s.”开头。
有关何时应包含属性的详细信息，请参阅 Attribute Requirement Levels。
特殊处理的属性
状态: 稳定
鉴于其重要性，某些资源属性将按如下方式进行特殊处理。
具有专用环境变量的语义属性
这些是可以通过专用环境变量配置的属性，如 OpenTelemetry Environment Variable Specification 中所述。
具有 SDK 提供默认值的语义属性
这些是必须由 SDK 提供的属性，如 Resource SDK specification 中所述。
服务
状态：
类型： service
描述： 服务实例。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
service.name |  | 必需 | 字符串 | 服务的逻辑名称。[1] | shoppingcart |
service.instance.id |  | 推荐 | 字符串 | 服务实例的字符串 ID。[2] | 627cc493-f310-47de-96bd-71410b7dec09 |
service.namespace | | 推荐 | 字符串 | service.name 的命名空间。[3] | Shop |
service.version | | 推荐 | 字符串 | 服务 API 或实现的字符串版本。格式不由这些约定定义。 | 2.0.0; a01dbef8a |
[1] service.name： 对于水平缩放的服务的所有实例，它必须相同。如果未指定该值，SDK 必须回退到 unknown_service: 加上 process.executable.name，例如 unknown_service:bash。如果 process.executable.name 不可用，则该值必须设置为 unknown_service。
[2] service.instance.id： 对于同一 service.namespace,service.name 对的每个实例，它必须是唯一的（换句话说，service.namespace,service.name,service.instance.id 三元组必须是全局唯一的）。该 ID 有助于区分同一时间存在的同一服务的实例（例如，水平缩放服务的实例）。
建议实现（例如 SDK）生成随机的 V1 或 V4 RFC 4122 UUID，但如果稳定性是可取的，可以自由使用固有的唯一 ID 作为此值的来源。在这种情况下，ID 应该用作 UUID V5 的来源，并应使用以下 UUID 作为命名空间：4d63009a-8d0f-11ee-aad7-4c796ed8e320。
通常建议使用 UUID，因为只需要一个不透明的值来识别服务实例。与 /etc/machine-id 文件手册页中可以看到的类似，底层数据（如 pod 名称和命名空间）应被视为机密，用户可以选择是否通过另一个资源属性公开它。
对于在应用程序服务器（如 unicorn）后面运行的应用程序，我们不建议为参与应用程序的所有进程使用单个标识符。相反，建议每个分区（例如 unicorn 中的工作线程）拥有自己的 instance.id。
不建议 Collector 设置 service.instance.id，如果它无法明确确定生成该遥测数据的服务实例。例如，基于 pod.name 创建 UUID 可能会出错，因为 Collector 可能不知道遥测数据来自该 pod 中的哪个容器。但是，Collector 如果能够明确确定该遥测数据的服务实例，则可以设置 service.instance.id。这通常是抓取接收器的情况，因为它们知道目标地址和端口。
[3] service.namespace: 一个字符串值，其含义有助于区分服务组，例如拥有服务组的团队名称。在同一命名空间内，service.name 应该具有唯一性。如果在 Resource 中未指定 service.namespace，则 service.name 应该对于所有没有明确定义命名空间的服务是唯一的（因此空/未指定的命名空间只是另一个有效的命名空间）。零长度命名空间字符串假定等于未指定的命名空间。
注意：service.namespace 和 service.name 无意串联起来以形成服务单一的全局唯一名称。例如，以下 2 组属性实际上描述了 2 个不同的服务（尽管串联会产生相同的字符串）
# Resource attributes that describes a service.
namespace = Company.Shop
service.name = shoppingcart
# Another set of resource attributes that describe a different service.
namespace = Company
service.name = Shop.shoppingcart
遥测 SDK
状态:
类型： telemetry.sdk
描述： 用于捕获由检测库捕获的数据的遥测 SDK。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
telemetry.sdk.language | | 必需 | 字符串 | 遥测 SDK 的语言。 | cpp; dotnet; erlang |
telemetry.sdk.name | | 必需 | 字符串 | 如上定义的遥测 SDK 名称。[1] | opentelemetry |
telemetry.sdk.version | | 必需 | 字符串 | 遥测 SDK 的版本字符串。 | 1.2.3 |
[1] telemetry.sdk.name： OpenTelemetry SDK 必须将 telemetry.sdk.name 属性设置为 opentelemetry。如果使用另一个 SDK，例如分叉或供应商提供的实现，则此 SDK 必须将 telemetry.sdk.name 属性设置为该 SDK 主入口点的完全限定类或模块名，或根据语言的其他合适标识符。标识符 opentelemetry 是保留的，在此情况下不得使用。所有自定义标识符在不同版本实现之间都应保持稳定。
telemetry.sdk.language 具有以下一组已知的（well-known）值。如果其中一个适用，则必须使用相应的值；否则，可以自由使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
cpp | cpp | |
dotnet | dotnet | |
erlang | erlang | |
go | go | |
java | java | |
nodejs | nodejs | |
php | php | |
python | python | |
ruby | ruby | |
rust | rust | |
swift | swift | |
webjs | webjs | |
遥测分发版
状态:
类型： telemetry.distro
描述： 用于捕获由检测库捕获的数据的遥测 SDK 的分发版。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
telemetry.distro.name | | 推荐 | 字符串 | 自动仪器化代理或分发版的名称（如果使用）。[1] | parts-unlimited-java |
telemetry.distro.version | | 推荐 | 字符串 | 自动仪器化代理或分发版的版本字符串（如果使用）。 | 1.2.3 |
[1] telemetry.distro.name: 官方的自动仪器化代理和分发版应将 telemetry.distro.name 属性设置为以 opentelemetry- 开头的字符串，例如 opentelemetry-java-instrumentation。
计算单元
状态: 开发中
定义计算单元的属性（例如，容器、进程、函数即服务）
计算实例
状态: 开发中
定义计算实例的属性（例如，主机）
环境
状态: 开发中
定义运行环境的属性（例如，操作系统、云、数据中心、部署服务）
版本属性
状态: 稳定
版本属性，例如 service.version，是 string 类型的值。它们用于标识工件的精确版本。这可能是一个语义版本，例如 1.2.3，git 哈希，例如 8ae73a，或任意版本字符串，例如 0.1.2.20210101，无论是在构建工件时使用的什么。
特定于云提供商的属性
状态: 开发中
仅适用于特定云提供商资源的属性。目前，这些资源只能为在 Cloud 中以及下文中列为有效 cloud.provider 的提供商定义。特定于提供商的属性都位于 cloud-provider 目录中。有效的云提供商是：
- 阿里云 (
alibaba_cloud) - Amazon Web Services (
aws) - Google Cloud Platform (
gcp) - Microsoft Azure (
azure) - Tencent Cloud (
tencent_cloud) - Heroku dyno