如何命名你的Span
发布时间：2025-08-11 22:22 浏览量：1
好的 Span 名称应遵循“{谓语} {宾语}”结构，例如“处理付款”。避免在 Span 名称中包含唯一标识符以保持低基数。这种命名方式与 OpenTelemetry 语义约定一致，有助于构建强大而有效的可观测性策略。
作者： Juraci Paixão Kröhling (OllyGarden)
良好检测的一个最基本但经常被忽视的方面是命名。这篇文章是专门讨论 OpenTelemetry 中事物命名艺术和科学的系列文章中的第一篇。我们将从 span 开始，它是分布式追踪的构建块，并在最开始就告诉你最重要的收获：如何命名描述你独特业务逻辑的 span。
虽然 OpenTelemetry 的自动检测功能非常适合覆盖标准操作（例如传入的 HTTP 请求或数据库调用），但最有价值的见解通常来自你添加到自己的业务逻辑中的自定义 span。这些是你的应用程序域独有的操作。
对于这些自定义 span，我们建议采用一种借鉴基本语法的模式。简单明了的句子通常遵循 主语 -> 谓语 -> 宾语 结构。“主语”（执行工作的服务）已经是追踪上下文的一部分。我们可以使用该结构的其余部分作为我们的 span 名称：
{谓语} {宾语}
这种模式具有描述性，易于理解，并有助于保持较低的基数——我们稍后将讨论的一个关键概念。
{谓语}：描述正在完成的工作的动词（例如：处理、发送、计算、渲染）。
{宾语}：描述正在被操作的事物的名词（例如：付款、发票、购物车、广告）。
让我们看一些例子：
为什么这种模式有效
那么为什么 process payment 好，而 process*invoice*#98765 不好呢？原因是基数。基数是指一条数据可以拥有的唯一值的数量。一个 span 名称应该具有低基数。如果在 span 名称中包含唯一标识符（如用户 ID 或发票号码），你将为每个操作创建一个唯一的名称。这会淹没你的可观测性后端，使分组和分析类似操作变得不可能，并且会显着增加成本。
{谓语} {宾语} 模式自然会产生低基数名称。唯一的、高基数的细节（invoice\_#98765, user_jane_doe）属于 span 属性，我们将在以后的博客文章中介绍。从语义约定中学习
这种 {谓语} {宾语} 方法不是随意的。它是一种最佳实践，反映了官方 OpenTelemetry 语义约定 (SemConv) 背后的原则。SemConv 为常见操作提供了一组标准化的名称，确保 HTTP 请求的 span 名称保持一致，无论使用哪种语言或框架。当你仔细观察时，你会看到这种描述资源操作的相同模式在整个约定中回荡。通过对你的自定义 span 遵循它，你正在与整个 OpenTelemetry 生态系统的既定理念保持一致。
让我们看一些来自 SemConv 的例子。
HTTP span
对于服务器端 HTTP span，约定是 {method} {route}。示例：GET /api/users/:ID
分析：这是一个作用于宾语 (/api/users/:id) 的动词 (GET)。使用路由模板而不是实际路径 (/api/users/123) 是保持低基数的完美示例。
数据库 span 通常命名为 {db.operation} {db.name}.{db.sql.table}。示例：INSERT my_database.users
分析：这是一个作用于宾语 (my_database.users) 的动词 (INSERT)。正在插入的特定值是高基数的，因此被正确地从名称中排除。
对于远程过程调用，约定是 {rpc.service}/{rpc.method}。示例：com.example.UserService/GetUser
分析：虽然格式不同，但原理是相同的。它描述了一个方法 (GetUser)，这是一个动词，位于一个服务 (com.example.UserService) 中，该服务是宾语或资源。
{谓语} {宾语}培养健康的系统
命名 span 不是一件小事。它是构建强大而有效的可观测性策略的基础实践。通过为你的业务特定 span 采用清晰、一致的模式（如 {谓语} {宾语}），你可以将遥测数据从混乱的混乱状态转变为精心照料的花园。一个命名良好的 span 是对你未来和你的团队的礼物。它在压力大的中断期间提供清晰度，实现强大的性能分析，并最终帮助你构建更好、更可靠的软件。
在本系列的下一篇文章中，我们将深入研究下一个细节层次：span 属性。我们将探讨如何向你的 span 添加丰富的、高基数的上下文，这对于深度调试是必要的，而不会影响你的 span 名称的可聚合性。