OpenTelemetry属性命名的五个最佳实践

在故障排除和事后分析中，为了使数据具有价值，属性名称需要在每种遥测类型、工具和服务中保持一致。

译自 Top 5 Best Practices for Naming OpenTelemetry Attributes，作者 Carl Brahms 是Chronosphere客户成功团队的成员，拥有多年的监控、观测和事件管理平台经验。他对三件事情充满激情：协助团队发现实时数据洞察、生成式人工智能以及...

当涉及使用 OpenTelemetry（OTel）分布式追踪数据时，仅仅收集数据是不够的；您需要采取措施确保数据易于查找并与其他数据相关联。这就是制定良好属性命名标准的目的。

有效的属性命名不仅仅是一种最佳实践；它是一项关键要求。为了使数据在故障排除和事后分析中具有价值，属性名称需要在每个遥测类型、每个工具和每个服务中保持一致。如果缺乏这种一致性，您的 OTel 数据的实用性将大大降低。

OTel 的语义约定和最佳实践使数据在云原生环境中更加互连、可移植和可用。上下文数据是可观测性团队中最有益的数据类型，而最佳实践确保您可以最大化数据的使用和效果。

这些准则和最佳实践将有助于使您的组织从收集的追踪数据中获得最大的利益。

要实施有效和有用的 OTel 属性，早期涉及所有受影响的团队至关重要。为了取得成功的采用，您应考虑组织研讨会，让每个人都了解在整个堆栈的所有层面上都有清晰一致的命名标准带来的积极结果。一致性创造清晰度，在事件响应和调试过程中至关重要。

得到软件和系统架构师的支持，通过说明命名标准的好处并专注于与贵公司和应用程序相关的领域。

然后起草一份详细的文件，概述命名约定，包括语法、结构和示例。制定一个修改标准的过程，通过反馈改进它，并在事后处理发现的任何空白。

有五个主要的最佳实践，作为您的 OTel 属性命名约定的一部分，以充分利用您的可观测性数据。

语义名称有助于确保高效的根本原因分析。

• 确保您的属性清晰、描述性，并适用于它们描述的资源的整体。诸如 http.status_code 和 db.system 这样的名称易于识别，并立即提供关于问题性质的见解，无论是在数据库还是在 Web 服务中。
• 非语义名称如 attribute、info 或 session_data 太通用，在后期分析遥测数据时会导致混淆。
  • 示例：app.service.version
• 为您的属性定义命名空间。
  • 示例：app.component.name
  • 当多个服务团队拥有自己的标准属性时，这点尤为重要。
• 保持属性名称简短。
  • 示例：http.url
• 在错误跨度上设置错误属性。
  • 示例：client.error

使用描述性的属性名称，您可以轻松查看资源并具备了解其内容和关联性的所有必要上下文。要了解现有语义约定的出色解释，请访问官方规范，您可以在那里学到一般和系统属性，并按信号或操作类型（如 HTTP 或数据库）组织它们，包括技术特定的约定。

创建已知属性的库的实践有助于对您关心的数据进行编目，其文档记录了对客户而言重要的数据。

当多个团队将共享属性时，标准化它们以避免差异至关重要。跨团队的属性命名约定差异可能使关联数据变得困难或根本不可能。例如，如果后端团队将延迟命名为 latency，而前端团队将其命名为 duration，查询比较或聚合跨服务的延迟将无法正常工作。标准化的属性使团队能够利用共享资源（比如仪表板或警报），并允许您在多个系统和服务之间获得洞见。

有时，您可能需要为公司或应用程序的特定方面创建新属性。在这样做之前，最好先查阅 OpenTelemetry 属性注册表，以确保您需要的属性不存在。一旦确认没有与您需要的匹配的属性，您就可以创建一个新属性。在创建过程中，遵循 OTel 属性命名指南中的提示尤为重要，特别是关于使用前缀的部分。

在属性名称中使用前缀有助于区分您的自定义属性名称与标准名称、其他项目选择的名称、与您合作的供应商或公司选择的名称。如果自定义属性意外地与另一个属性共享名称，可能会导致错误的结论和决策、有缺陷的仪表板和警报，并使跟踪事务的流程或状态变得困难。

为避免与其他项目、供应商或公司发生冲突，明智的做法是考虑使用基于公司域名的前缀，以相反的顺序，例如 io.chronosphere.myapp。

即使您确定该名称绝对不会在您的应用程序之外使用，仅在公司内部使用，前缀仍然是防止冲突的重要手段。考虑使用与您的应用程序或项目相关联的前缀名称，例如 bluebook.widget_count。

你可能会想要利用属于 OpenTelemetry 或其他项目或供应商的现有前缀。共享前缀可能导致后续发生名称冲突，使您和同事在事故期间努力找到将他人的数据与您的数据分开的方法。

在决定要应用于您的跟踪的属性时，请记住您的应用程序的重点是为客户提供高质量的软件体验。这一使命被编码在您服务/应用程序的服务水平目标（SLOs）中，可能以 99.999% 的正常运行时间期望的形式存在。从 SLO 中，您可以缩小到哪些服务水平指标（SLIs）最好支持或最有可能威胁实现 SLOs。您的属性应支持您的服务水平。

例如，如果您在流量的不同部分之间有延迟 SLO，使用提供段维度的属性，如 ProductID、FeatureID 或 RegionID，可以帮助您相应地组织警报。

将属性视为分布式系统中模式匹配的根源。如果您想要调查跨类别和类别之间的关系，属性是排序和比较的工具。

逐步尝试不同的属性，看看会有什么变化。让我们考虑一个例子。

你的高级客户是否因发票错误而联系支持？难道订单服务不是几分钟前部署了新版本吗？对比属性，例如 service.version 和 membership.level，对服务名称为 order 的错误指标进行关联，可以帮助确定高级会员的升高错误率是否与订单服务的新版本高度相关。

在制定 OpenTelemetry 的标准属性时进行了大量慎重考虑，而这个列表一直在不断发展。尽管这里无法提及所有类别，但在制定内部命名标准时探索现有内容并强调在调查回归时对团队有用的内容可能会很有帮助。以下是注册表中的一些示例：

• 常规属性：常规属性提供有关整体环境和网络的广泛背景信息。
  • server.address：服务器的地址。
  • destination.address：目标的地址。
  • network.carrier.name：网络承载方的名称。
  • code.filepath：代码的文件路径。
• 消息系统：与消息系统相关的属性，有助于跟踪和诊断消息处理中的问题。
  • messaging.destination：描述消息发布到的逻辑实体。
  • messaging.kafka.consumer.group：处理消息的 Kafka 消费者组。
  • messaging.message.body.size：消息主体的大小（字节）。
• HTTP：对于跟踪 HTTP 请求和响应至关重要，提供有关 Web 事务的见解。
  • http.url：完整的 HTTP 请求 URL。
  • http.status_code：HTTP 响应状态码。
  • user_agent.original：客户端的 HTTP User-Agent 头的值。
• 资源属性：这些属性提供有关服务、基础设施和操作环境的详细背景信息。
  • service.version：服务的版本。
  • k8s.cluster.name：Kubernetes 集群的名称。
  • gcp.gce.instance.name：Google Compute Engine 实例的名称。
  • aws.ecs.container.arn：ECS 容器的 Amazon 资源名称（ARN）。

有一种特殊类型的跨度属性称为跨度事件日志经常被忽视。跨度事件与日志非常相似，但它们是放置上下文信息的好地方，这些信息在故障排除事务问题时可能非常有用。

在考虑要放入跨度事件日志的内容时，应清理任何私人用户数据的有效负载/添加跨度内发生的任何事件，包括所发生事件的简要摘要、任何异常或完整的错误消息，以及额外的上下文信息。

我们一直在关注属性的“做法”，但这里更仔细地看一下一些要避免的属性陷阱。

• 使用晦涩的语义属性名称，比如 errorcode，只会引起混淆，使获取信息变得更加困难。
• 使用 otel.* 命名空间，除非您认为该名称适用于行业中的其他应用。在这种情况下，您可以提交提案，将新名称添加到语义约定中。
• 创建您不使用的属性，即使看起来将来可能对某人有用。除非有确凿的证据证明属性的有用性，最好还是暂时不要添加。
• 将堆栈跟踪、uuid（唯一用户标识）或异常信息放入自定义属性。建议在发生时将它们记录为跨度上的 Event，并且事件的名称必须为 "exception"。详见规范中的异常部分。
• 属性键重复 —— 要么覆盖同一跨度上的键，要么拥有两个具有不同名称的相同值。重复的属性键可能会引起冲突并覆盖数据。它还使查询和分析变得复杂。
• 未设置或空值。未设置的值提供不了有用的信息。没有值的属性占用存储空间，但对故障排除或分析没有帮助。它们还可能通过扭曲总数来扭曲分析。这也会引起混淆。

在 OpenTelemetry 文档中还有更多有用的见解和建议，因此在制定属性标准时建议查阅最新的规范。

追踪数据收集是观测性的一个必要部分。但这需要建立一套流程，以确保数据是有用的、可访问的，并且具有洞察力。命名规范需要一些前期工作，但通过采纳这些最佳实践 —— 从确保语义清晰和维护统一库到了解数据、与服务水平保持一致，以及预测新的用例 —— 您的团队可以提升遥测的效用。

这种方法不仅简化故障排除，还帮助您在组织内建立一个有效的观测文化。这项工作的结果是一个充满可访问洞察的丰富 OTel 数据集，使更加智能、更加迅速的决策成为可能。