Naming

状态: 稳定，除非另有说明。

通用命名注意事项

本节适用于属性名称（也称为“属性键”），以及指标和事件名称。在本节中，为了简洁起见，当我们使用“名称”一词而不加形容词时，则默认为所有这些。

所有名称都必须是有效的Unicode序列。

注意：我们仅要求名称表示为Unicode序列。本规范不定义Unicode序列的确切编码方式。编码方式可能因编程语言和线上传输格式而异。请使用特定编程语言或线上传输格式中表示Unicode的惯用方式。

名称应遵循以下规则

• 名称应为小写。

• 使用命名空间。使用点字符分隔命名空间。例如，service.version表示服务版本，其中service是命名空间，version是该命名空间中的一个属性。

• 命名空间可以嵌套。例如，telemetry.sdk是顶级telemetry命名空间下的一个命名空间，而telemetry.sdk.name是telemetry.sdk命名空间下的一个属性。

  只要有意义，就应使用命名空间（和点分隔符）。例如，在引入表示对象属性的属性时，请遵循*{object}.{property}模式。如果该对象可能有其他属性，请避免使用下划线（*{object}_{property}）。

• 对于名称中每个由点分隔的多词组件，请使用下划线分隔单词（即使用snake_case）。例如，http.response.status_code表示http命名空间中的状态码。

  已知例外包括K8s API 名称，其中使用单个单词以与仪器化的API保持一致。

  仅当使用点（命名空间）无意义或改变名称的语义含义时，才应使用下划线。例如，使用rate_limiting而不是rate.limiting。

• 要精确。属性、事件、指标和其他名称应具有描述性且无歧义。

  • 在引入描述对象特定属性的名称时，请包含属性名称。例如，使用file.owner.name而不是file.owner，使用system.network.packet.dropped而不是system.network.dropped。
  • 避免引入在不同约定或仪器化中具有不同含义的名称和命名空间。例如，使用security_rule而不是rule。

• 在不牺牲清晰度的情况下，使用更短的名称。当命名空间组件或多词组件中的单词不必要时，请将其删除。例如，vcs.change.id描述了拉取请求ID，其精确度与vcs.repository.change.id相同。

名称缩写指南

当缩写被广泛识别并常用时，可以允许使用。

例如，常见的技术缩写如IP、DB、CPU、HTTP、URL，或产品名称如AWS、GCP、K8s。

仅在特定领域内被广泛识别的缩写，在用相应的命名空间限定时可以使用。

例如，使用container.csi.*而不是container.container_storage_interface，或使用container.oci.*而不是container.open_container_initiative.*。

如果缩写可能引起歧义，例如，当它们适用于多个产品或概念时，应避免使用。

禁止名称重用

两个属性、两个指标或两个事件不得共享相同的名称。不同的实体（属性和指标，指标和事件）可以共享相同的名称。

属性、指标和事件不应从语义约定中删除，无论其成熟度如何。当约定被重命名或不再推荐时，应将其弃用。

对OpenTelemetry作者的建议

• 在提出新的语义约定之前，请务必检查现有的命名空间（Semantic Conventions），以查看是否已存在类似的命名空间。

• 所有属于OpenTelemetry语义约定的名称都应属于一个命名空间。

• 当需要新的命名空间时，请考虑它应该是顶级命名空间（例如service）还是嵌套命名空间（例如service.instance）。

• 语义约定必须将名称限制在可打印的基本拉丁字符（更准确地说，是Unicode码点的U+0021 .. U+007E子集）。建议进一步将名称限制在以下Unicode码点：拉丁字母、数字、下划线、点（作为命名空间分隔符）。

注意：语义约定工具将名称限制为小写拉丁字母、数字、下划线、点（作为命名空间分隔符）。名称必须以字母开头，以字母数字字符结尾，并且不得包含两个或多个连续的分隔符（下划线或点）。

对应用程序开发者的建议

作为应用程序开发者，当您需要记录属性、指标、事件或其他信号时，请首先查阅现有的语义约定。如果不存在合适的名称，您需要提出一个新的名称。为此，请考虑以下几个选项：

• 该名称是您的公司特有的，并可能在公司外部使用。为避免与其他公司引入的名称冲突（在使用多个供应商的应用程序的分布式系统中），建议在新的名称前加上您公司的反向域名，例如com.acme.shopname。

• 该名称是您的应用程序特有的，仅在内部使用。如果您已经有一个内部公司流程来帮助您确保名称不冲突，请随意遵循。否则，建议在属性名称前加上您的应用程序名称，前提是该应用程序名称在您的组织内是相当独特的（例如，myuniquemapapp.longitude可能是可以的）。请确保应用程序名称与现有语义约定命名空间没有冲突。

• 不建议将现有的OpenTelemetry语义约定命名空间用作新的公司或应用程序特定属性名称的前缀。这样做可能会导致将来发生名称冲突，如果OpenTelemetry决定将该名称用于不同目的，或者如果其他第三方仪器化决定使用完全相同的属性名称，而您将该仪器化与您自己的结合使用。

• 该名称可能普遍适用于行业中的应用程序。在这种情况下，请考虑向本规范提交提案，以添加一个新名称到语义约定中，并在必要时也添加一个新命名空间。

建议将名称限制在可打印的基本拉丁字符（更准确地说，是Unicode码点的U+0021 .. U+007E子集）。

Attributes

otel.* 命名空间

以otel.开头的属性名称保留给OpenTelemetry规范定义。这些通常用于在没有相应概念的格式中表达OpenTelemetry概念。

例如，otel.scope.name属性用于记录仪器化范围名称，这是一个OpenTelemetry概念，在OTLP中是原生表示的，但在其他遥测格式和协议中没有等价物。

对otel.*命名空间的任何添加都必须作为OpenTelemetry规范的一部分获得批准。

属性名复数化指南

• 当一个属性代表单个实体时，属性名称应为单数。例如：host.name、container.id。

• 当属性可以代表多个实体时，属性名称应为复数，并且值类型应为数组。例如，process.command_args可能包含多个值：可执行文件名和命令行参数。

• 当一个属性代表一个测量值时，应遵循属性名称的名称复数化指南。

特定于信号的属性

状态: 开发中

属性以信号无关的方式在语义约定中定义。相同的属性预期会用于多个信号。

当定义一个属性时，不总是清楚它是否将适用于某个指标、事件或其他约定之外的用途。

对于不太可能在特定约定之外使用的属性，应将其添加到该指标（事件等）的命名空间下。

示例

指标system.filesystem.usage的属性mode和mountpoint应分别命名为system.filesystem.mode和system.filesystem.mountpoint。

预期指标、事件、资源和其他信号会使用来自多个命名空间的适用属性，并且鼓励这样做。

示例

指标http.server.request.duration使用了注册表中的属性，如server.port、error.type。

指标

状态: 开发中

计数器和UpDownCounter的命名规则

复数化

指标命名空间不应使用复数形式。

指标名称不应使用复数形式，除非正在记录的值代表一个可计数数量的离散实例。通常，只有当指标的单位是非单位（如{fault}或{operation}）时，才应将名称复数化。

示例

• system.filesystem.utilization、http.server.request.duration和system.cpu.time不应复数化，即使记录了多个数据点。
• system.paging.faults、system.disk.operations和system.network.packets应复数化，即使只记录了一个数据点。

不要对UpDownCounter名称进行复数化

UpDownCounter名称不应使用复数形式。

例如，如果我们有一个包含所有进程相关指标的system.process命名空间，那么为了表示进程的数量，我们可以有一个名为system.process.count的指标，而不是system.processes。同样，cicd.pipeline.run.active优于cicd.pipeline.active_runs。

不要使用total

UpDownCounter不应使用_total，因为这样它们看起来会像单调累加和。

计数器也不应附加_total，因为在增量后端其含义会令人困惑。

仪表命名

状态: 开发中

• limit - 衡量某事物恒定、已知总量的仪表应命名为entity.limit。例如，系统总内存量的system.memory.limit。

• usage - 衡量已知总量（limit）中已用量的仪表应命名为entity.usage。例如，system.memory.usage，其属性state = used | cached | free | ...表示每种状态下的内存量。在适当的情况下，usage在所有属性值上的总和应等于limit。

  对无限资源或资源限制未知的情况下的消耗量测量，与usage区分开。例如，进程可能消耗的虚拟内存的最大量会随时间波动，并且通常是未知的。

• utilization - 衡量usage相对于其limit的*分数*的仪表应命名为entity.utilization。例如，内存使用情况的system.memory.utilization。利用率可以相对于固定限制或软限制。利用率值表示为比率，通常在[0, 1]范围内，但在超出软限制的情况下可能会超过1。

• time - 衡量时间流逝的仪表应命名为entity.time。例如，system.cpu.time，其属性state = idle | user | system | ...。time测量不一定是实际时间，并且可能小于或大于测量之间实际经过的时间。

  time仪表是usage指标的一个特殊情况，其中limit通常可以通过将所有属性值上的time相加来计算。时间仪表的utilization可以通过度量事件时间戳自动派生。例如，system.cpu.utilization定义为system.cpu.time测量值之间的差值除以经过的时间和CPU数量。

• io - 衡量双向数据流的仪表应命名为entity.io，并具有方向属性。例如，system.network.io。

• 不符合上述描述的其他仪表可以更自由地命名。例如，system.paging.faults和system.network.packets。单位不需要在名称中指定，因为它们在创建仪表时已包含，但如果存在歧义，可以添加。

客户端和服务器指标

衡量物理或逻辑网络调用的某个方面的指标应包含指示该指标是从哪一侧记录的。

如果给定{area}和{metric_name}的通信侧存在歧义，则这些指标应遵循{area}.{client|server}.{metric_name}模式。否则，当通信侧可以从给定的{area}或{metric_name}推断出来时，应使用{area}.{metric_name}模式。

示例

• http.client.request.duration
• gen_ai.server.request.duration
• messaging.client.sent.messages
• messaging.process.duration - 术语process清楚地表明该指标由消费者报告。
• kestrel.connection.duration - 在此，kestrel是Web服务器的名称，因此不需要额外的指示。

特定于系统的命名

状态: 开发中

系统（项目/产品/提供商）名称属性

某个领域（area）的语义约定通常适用于多个系统（项目、提供商、产品）。

例如，数据库语义约定可用于描述各种数据库系统的遥测数据。

此类约定应定义一个属性来表示系统名称，遵循{area}.system|provider|protocol.name模式。

例如，数据库约定包含db.system.name属性。

选择系统名称

在为语义约定添加新系统时，请按优先级从高到低遵循以下原则：

1. 系统名称应遵循本文档中概述的一般属性命名指南，因为它将在特定于系统的属性名称中用作命名空间。

2. 系统名称应明确识别该特定产品或项目。

   例如，使用gcp.pubsub或oracle.db。避免使用像pubsub这样的通用名称，它可能指代多个消息传递产品，或oracle，它可能指代多个Oracle产品。

3. 在以下情况下，系统名称应与相应的项目或产品名称匹配：

   • 不属于特定公司的独立项目，例如Apache基金会的项目，如kafka或cassandra。
   • 名称与拥有公司相似的产品，例如mongodb或elasticsearch。
   • 在公司生态系统之外广泛认可且流行的产品。这些产品通常拥有不包含公司名称的商标，并拥有自己的顶级域名（例如spring或mysql）。

4. 在其他情况下，系统名称应加上公司（组织、部门或小组）名称作为前缀。对于云服务，名称应使用相应的云提供商名称。例如，使用aws.dynamodb或azure.cosmosdb。

   公司（组织、部门或小组）名称在不同语义约定区域的多个产品名称中应保持一致。

特定于系统的属性

当一个属性特定于某个系统（项目、提供商、产品）时，相应的属性名称应以系统名称开头，遵循{system_name}.*.{property}模式。

示例

• cassandra.consistency.level - 描述特定于Cassandra数据库的一致性级别属性。
• aws.s3.key - 指代AWS S3产品的key属性。
• signalr.connection.status – 指示SignalR网络协议的连接状态。

*.system.name（或类似）属性的值必须与正在定义的系统特定属性中使用的根命名空间匹配。

例如，cassandra.consistency.level属性名称和db.system.name=cassandra都使用相同的系统名称（cassandra）。

特定于系统的指标

当一个指标特定于某个系统（项目、提供商、产品）时，相应的仪表名称应以系统名称开头，遵循{system_name}.*.{metric_name}模式。

例如，azure.cosmosdb.client.operation.request_charge

*.system.name（或类似）属性的值必须与系统特定指标命名空间匹配。

例如，azure.cosmosdb.client.operation.request_charge指标和db.system.name=azure.cosmosdb属性都使用相同的系统名称（azure.cosmosdb）。

已知例外

• 与操作系统和进程相关的操作属性和指标遵循system.{os}和process.{os}的模式。

• RPC和messaging的语义约定尚未遵循特定于系统的命名指南，将逐一更新。