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

在故障排除和事后分析中，为了使数据具有价值，属性名称需要在每种遥测类型、工具和服务中保持一致。
译自Top 5 Best Practices for Naming OpenTelemetry Attributes，作者 Carl Brahms 是Chronosphere客户成功团队的成员，拥有多年的监控、观测和事件管理平台经验。他对三件事情充满激情：协助团队发现实时数据洞察、生成式人工智能以及...
当涉及使用OpenTelemetry（OTel）分布式追踪数据时，仅仅收集数据是不够的；您需要采取措施确保数据易于查找并与其他数据相关联。这就是制定良好属性命名标准的目的。
有效的属性命名不仅仅是一种最佳实践；它是一项关键要求。为了使数据在故障排除和事后分析中具有价值，属性名称需要在每个遥测类型、每个工具和每个服务中保持一致。如果缺乏这种一致性，您的 OTel 数据的实用性将大大降低。
OTel 的语义约定和最佳实践使数据在云原生环境中更加互连、可移植和可用。上下文数据是可观测性团队中最有益的数据类型，而最佳实践确保您可以最大化数据的使用和效果。
【OpenTelemetry属性命名的五个最佳实践】这些准则和最佳实践将有助于使您的组织从收集的追踪数据中获得最大的利益。
建立 OTel 属性的有效采用要实施有效和有用的 OTel 属性，早期涉及所有受影响的团队至关重要。为了取得成功的采用，您应考虑组织研讨会，让每个人都了解在整个堆栈的所有层面上都有清晰一致的命名标准带来的积极结果。一致性创造清晰度，在事件响应和调试过程中至关重要。
得到软件和系统架构师的支持，通过说明命名标准的好处并专注于与贵公司和应用程序相关的领域。
然后起草一份详细的文件，概述命名约定，包括语法、结构和示例。制定一个修改标准的过程，通过反馈改进它，并在事后处理发现的任何空白。
命名 OTel 属性的最佳实践有五个主要的最佳实践，作为您的 OTel 属性命名约定的一部分，以充分利用您的可观测性数据。
1. 使用语义和描述性属性语义名称有助于确保高效的根本原因分析。

确保您的属性清晰、描述性，并适用于它们描述的资源的整体。诸如http.status_code和db.system这样的名称易于识别，并立即提供关于问题性质的见解，无论是在数据库还是在 Web 服务中。
非语义名称如attribute、info或session_data太通用，在后期分析遥测数据时会导致混淆。

示例：App.service.version

为您的属性定义命名空间。
示例：
app.component.name
当多个服务团队拥有自己的标准属性时，这点尤为重要。
保持属性名称简短。
示例：
http.url
在错误跨度上设置错误属性。
示例：
client.error

使用描述性的属性名称，您可以轻松查看资源并具备了解其内容和关联性的所有必要上下文。要了解现有语义约定的出色解释，请访问官方规范，您可以在那里学到一般和系统属性，并按信号或操作类型（如HTTP或数据库）组织它们，包括技术特定的约定。
2. 使用共享库创建已知属性的库的实践有助于对您关心的数据进行编目，其文档记录了对客户而言重要的数据。
当多个团队将共享属性时，标准化它们以避免差异至关重要。跨团队的属性命名约定差异可能使关联数据变得困难或根本不可能。例如，如果后端团队将延迟命名为latency，而前端团队将其命名为duration，查询比较或聚合跨服务的延迟将无法正常工作。标准化的属性使团队能够利用共享资源（比如仪表板或警报），并允许您在多个系统和服务之间获得洞见。
3. 创建自定义属性有时，您可能需要为公司或应用程序的特定方面创建新属性。在这样做之前，最好先查阅 OpenTelemetry属性注册表，以确保您需要的属性不存在。一旦确认没有与您需要的匹配的属性，您就可以创建一个新属性。在创建过程中，遵循OTel 属性命名指南中的提示尤为重要，特别是关于使用前缀的部分。
在属性名称中使用前缀有助于区分您的自定义属性名称与标准名称、其他项目选择的名称、与您合作的供应商或公司选择的名称。如果自定义属性意外地与另一个属性共享名称，可能会导致错误的结论和决策、有缺陷的仪表板和警报，并使跟踪事务的流程或状态变得困难。