如何命名你的 Span
良好仪器化中最基本但常常被忽视的方面之一是命名。本文是致力于 OpenTelemetry 中命名事物的艺术与科学的系列文章的第一篇。我们将从 Span 开始，Span 是分布式跟踪的构建块，并立即给您最重要的收获：如何命名描述您独特业务逻辑的 Span。
命名你的业务 Span
虽然 OpenTelemetry 的自动仪器化在覆盖标准操作（如传入的 HTTP 请求或数据库调用）方面非常出色，但最有价值的见解通常来自您添加到自己业务逻辑中的自定义 Span。这些是您的应用程序域特有的操作。
对于这些自定义 Span，我们推荐一种借鉴基本语法的模式。简单、清晰的句子通常遵循主语 -> 动词 -> 直接宾语的结构。“主语”（执行工作的服务）已包含在跟踪的上下文中。我们可以使用该结构的其余部分来命名我们的 Span。
{动词} {宾语}
这种模式具有描述性，易于理解，并有助于保持低 基数 — 这是我们稍后会介绍的一个关键概念。
- {动词}：描述正在进行的工作的动词（例如：处理、发送、计算、渲染）。
- {宾语}：描述正在操作的对象的名词（例如：付款、发票、购物车、广告）。
让我们看一些例子
| 糟糕的名称 | 好的 Span 名称 | 为什么它更好 |
|---|---|---|
| process_payment_for_user_jane_doe | 处理 付款 | 动词和宾语都很清晰。用户 ID 应该放在属性中。 |
| sendinvoice#98765 | 发送 发票 | 可聚合。您可以轻松找到发送所有发票的 P95 延迟。 |
| render_ad_for_campaign_summer_sale | 渲染 广告 | 具体活动是细节，而不是核心操作。将其放在属性中。 |
| calculate_shipping_for_zip_90210 | 计算 运费 | 操作是一致的。邮政编码是一个参数，而不是名称的一部分。 |
| validation_failed | 验证 用户输入 | 关注操作，而不是结果。结果属于 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，约定是 {方法} {路由}。
- 示例：
GET /api/users/:ID - 分析：这是一个作用于宾语（
/api/users/:id）的动词（GET）。使用路由模板而不是实际路径（/api/users/123）是保持低基数的绝佳示例。
数据库 Span
数据库 Span 通常命名为 {db.operation} {db.name}.{db.sql.table}。
- 示例：
INSERT my_database.users - 分析：这是一个作用于宾语（
my_database.users）的动词（INSERT）。正在插入的具体值是高基数的，并且被正确地排除在名称之外。
RPC Span
对于远程过程调用，约定是 {rpc.service}/{rpc.method}。
- 示例：
com.example.UserService/GetUser - 分析：虽然格式不同，但原理是相同的。它描述了服务（
com.example.UserService）中的一个方法（GetUser），其中方法是动词，服务是宾语或资源。
关键的收获是，通过使用 {动词} {宾语}，您正在与您的其他仪器化组件使用相同的语言。
培育健康系统
命名 Span 并非易事。它是构建强大而有效的可观察性策略的基础实践。通过为您的特定业务 Span 采用像 {动词} {宾语} 这样清晰、一致的模式，您可以将遥测数据从杂乱无章变成精心打理的花园。
一个命名良好的 Span 是给未来自己和团队的礼物。它能在压力巨大的故障时提供清晰度，支持强大的性能分析，并最终帮助您构建更好、更可靠的软件。
在下一篇文章中，我们将深入探讨下一层细节：Span 属性。我们将探讨如何为 Span 添加丰富的、高基数的上下文，这对于深度调试至关重要，同时又不影响 Span 名称的可聚合性。