使用 OpenTelemetry 构建可观测性 02 - 埋点

这是讲解 OpenTelemetry 系列博客的第二篇。在上一篇博客中，我们介绍了 OpenTelemetry 是什么以及由什么组成。现在我们将讨论如何使用 OTel 准确收集遥测数据和链路追踪数据。

本文重点解释 OpenTelemetry 埋点的两种方式：

• 手动埋点：显式创建 Span、设置属性和事件，适合需要精确表达业务语义的关键路径。
• 自动埋点：利用已有 instrumentation 库自动采集框架、数据库、HTTP 等通用遥测数据，适合快速接入和低成本试点。

理解埋点的关键，是先理解 trace 和 span。trace 表示一次请求跨多个服务的完整路径，span 表示这条路径中的某个具体操作。

手动埋点

我们这里谈论“埋点”(代码插桩)，是指通过技术手段采集链路追踪数据的行为。通常有两种方式：手动和自动（下面讨论）。顾名思义，手动埋点需要在软件中显式的选择要暴露哪些数据。

手动埋点被认为是更高级和定制的遥测方法。手动和自动埋点分别有各自的使用场景，我们将在下文介绍。

一个请求进入系统并通过多个后端服务时，OpenTelemetry 能够记录该请求在系统中调用流程和经过的完整路径，这个路径被称为 链路追踪（trace） 。请求可能触发多个操作，每个操作都被记录在一个 跨度（span） 中，表示具体操作的实例。

每个跨度都有一个父跨度，除非它是链路追踪中的第一个跨度，在这种情况下，其父跨度 ID 为零（形成树状结构）。

注：示例应用程序主要是用 Go 和一些 Python 编写的。我将使用 Go 语言展示代码示例，但其中原理和概念同样适用于 OTel 支持的其他编程语言。

我们可以通过 API 将跨度添加到现有链路追踪中（或启动新链路追踪）。对于 Go 语言，这意味着我们将引用 go.opentelemetry.io/otel 库，它包含了手动埋点所需的所有函数方法。我们可以通过函数调用，使用全局链路追踪生产者来创建跨度：

import "go.opentelemetry.io/otel"

// ... other code ...

ctx, span := otel.Tracer("my-telemetry-library").Start(r.Context(), "get_user_cart")
defer span.End()

这里有几点需要注意。首先，我们先获取全局链路追踪的实例，使用这个实例创建一个新的跨度。

我们将在下一篇博客文章中更深入地讨论链路追踪生产者，它是 SDK 的一个组件，负责决定和管理这些遥测数据的流向和传输方式。

链路追踪生产者既可以通过调用 otel.Tracer 也可以显式地使用参数传递。此示例应用程序依赖于全局跟踪器提供程序。当我们调用 otel.Tracer 时，我们传入埋点对象名称，该名称通常是处理埋点库名。在示例应用中，它被设置为“ github.com/trstringer/otel-shopping-cart ”。

一旦我们得到了链路追踪生产者，就可以调用 Start 函数并向其传递两个参数：上下文对象（ context ，允许我们在不同的执行环境中共享数据，并且可以跨多函数调用、请求处理或线程之间）和跨度的名称。上下文对象可以被新建（例如 context.Background() ）或从它的父上下文传递（在本例中我使用的是 HTTP 请求上下文）。跨度名称可以是任何字符串，但在这个项目中，使用了一种标准化的命名方式，即选择描述标识符来命名并且使用下划线将不同标识符分隔。

Start 函数的返回值之一是上下文对象，我们可以把它传递给代码不同执行分支或路径（例如创建子跨度），以满足那些需要使用相同上下文的调用；而另一个返回值跨度对象，可以用来处理其他操作。

正如在此示例中所示，首先是通过 defer 关键字声明对函数 span.End 的调用，以便可以将此跨度标记为完成。我们还可以为 span 对象添加属性。

还需要注意的是，跨度是可以被嵌套使用的。通常一个新跨度是进入了一个代码执行分支或路径并且包含一个父跨度。这样就形成了跨度的嵌套关系，准确地反映了请求所经历的代码调用路径。

手动埋点适合放在业务含义明确的位置，例如查询购物车、计算价格、调用支付、写入订单等关键动作。它的价值不只是记录耗时，还能把用户、订单、数据库行数、外部依赖等上下文放进 span，帮助排障时快速回答“这次请求到底发生了什么”。

属性

在链路追踪系统中，我们采集各种与系统行为相关的数据，并将这些数据与特定的跨度进行关联，以便更好地理解系统行为。通过利用具有多样取值的高基数数据，我们能够获取更加详细和全面的上下文信息，从而更好地观测和分析系统的运行情况。

可以像下面给跨度设置属性：

span.SetAttributes(attribute.String("user.name", userName))

创建了一个名为 user.name 的字符串类型的属性并赋值。跨度的记录就会变成下面这样：

Span #4
    Trace ID       : d6b58718e2d607f2a881e55200b387d5
    Parent ID      : ef6c51753d66f227
    ID             : 95dcb2657f5bca91
    Name           : get_user_cart
    Kind           : SPAN_KIND_INTERNAL
    Start time     : 2022-08-07 16:37:51.184919236 +0000 UTC
    End time       : 2022-08-07 16:37:51.231164398 +0000 UTC
    Status code    : STATUS_CODE_UNSET
    Status message :
Attributes:
     -> user.name: STRING(tlasagna)

太棒了！现在名为 get_user_cart 的跨度就包含这个新属性 user.name 。还可以在 Jaeger 中同样看到这个属性：

事件

在许多情况下，当使用链路追踪时，您可能希望记录一些文本或发生在跨度期间的事件。通过调用 span.AddEvent，可以实现这一点：

span.AddEvent(
    "Successfully retrieved rows from database",
    trace.WithAttributes(attribute.Int("row.count", rowCount)),
)

记录的事件中还可以设置属性变量，如下例所示：

Span #1
    Trace ID       : 2d77674bf5bee80afcaf0df064f961ed
    Parent ID      : 5989852864910844
    ID             : f47e44dd5e23f016
    Name           : db_get_cart
    Kind           : SPAN_KIND_INTERNAL
    Start time     : 2022-08-07 18:37:39.167046809 +0000 UTC
    End time       : 2022-08-07 18:37:39.168098188 +0000 UTC
    Status code    : STATUS_CODE_UNSET
    Status message :
Events:
SpanEvent #0
     -> Name: Successfully retrieved rows from database
     -> Timestamp: 2022-08-07 18:37:39.16803511 +0000 UTC
     -> DroppedAttributesCount: 0
     -> Attributes:
         -> row.count: INT(2)

属性和事件的区别可以这样理解：

实践中，属性更适合筛选和聚合，事件更适合还原执行过程。

自动埋点

在前面的例子中，我们展示了如何手动在跨度中进行埋点操作。然而，OpenTelemetry 具有一个非常强大的特性，即支持广泛的自动埋点。

自动埋点适用于以下情况：

• 对于 OpenTelemetry (OTel) 的新手，他们希望能够快速利用 OTel 收集与应用程序性能相关的指标和日志信息。
• 在现有代码库的基础上尝试集成和使用 OTel 的功能。
• 对于一些常用的组件或服务，在对遥测数据没有特殊要求的情况下，使用默认的自动埋点机制能够自动处理数据收集。

在购物应用的示例程序中，在 Python 服务（定价服务）中使用自动埋点来处理了两个事情：

• Flask web 服务
• MySQL 连接服务

from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.mysql import MySQLInstrumentor

app = Flask(__name__)

FlaskInstrumentor().instrument_app(app)
MySQLInstrumentor().instrument()

自动埋点的神奇之处就在于，它所需要的仅仅是启用自动埋点功能！然后，不需要任何额外的工作或编写代码，就能够获得一些关于 Flask 路由和 MySQL 查询的非常有用的数据。这是 Flask 框架自动埋点的 Span：

记录中可以看到大量与请求相关的信息，例如 http.target 、 net.peer.ip 、 http.method 等等。

MySQL 自动埋点有很多有价值的信息：

这太棒了。通过零代码开发，仅自动获取跨度，它就已经告诉我一个关键的数据：查询的持续时间。此外，还可以看到运行中的查询以及运行该查询的用户。

这些数据提供了足够的信息，用于对慢查询进行故障排除，并帮助我们识别可能发生在数据库侧的意外情况。这一切都是因为一行代码启用了 MySQL 自动埋点！

手动埋点和自动埋点并不是二选一。更常见的落地方式是：先用自动埋点快速拿到框架、HTTP、数据库等基础 span；再在关键业务流程上补手动埋点，让 trace 既有技术调用路径，也有业务语义。

什么时候用手动，什么时候用自动

总结

埋点是 OpenTelemetry 的核心。它定义了如何去收集哪些遥测数据，我们既可以选择手动埋点还可以利用现成的自动埋点代码库。在下一篇博文中，我们将了解 OTel SDK 是如何处理这些数据！

FAQ：OpenTelemetry 埋点常见问题

Q1：自动埋点够用吗？

自动埋点适合快速开始，也能覆盖框架、HTTP、数据库等通用场景。但它不知道业务含义，关键业务流程通常仍然需要手动补充 Span、属性或事件。

Q2：Span 属性应该放多少信息？

属性应该帮助定位和分析问题，但不应该无节制堆字段。优先放服务、资源、请求、用户或业务对象等对排障有价值的信息，同时注意敏感数据和高基数风险。

Q3：事件和日志有什么区别？

Span 事件是 trace 内的时间点信息，天然属于某个 span；日志可以更自由地记录文本和上下文。二者可以互补，尤其是日志里带 TraceID、SpanID 时更容易关联。

本文翻译自：https://trstringer.com/otel-part2-instrumentation/

扩展阅读：

• 方法论：面向故障处理的可观测性体系建设
• 白皮书：事件 OnCall 中心建设方法
• 好工具：Flashduty - 一站式告警处理平台：告警降噪、排班OnCall