分布式跟踪

概述

可观察性是面向微服务的应用程序的一个重要方面。可观察性的关键要素之一是分布式跟踪。

当应用程序将记录写入稍后由 Debezium 处理的数据库时，需要提供额外的预防措施。活动跟踪由写入数据库来有效划分界限。如果您想在应用程序的跟踪器中包含 Debezium 数据，则必须将跟踪元数据传递给 Debezium。

您可以通过OpenTelemetry 规范为 Debezium 添加跟踪支持。

安装

要启用 Debezium 中的可跟踪性，您必须在 Kafka Connect 集群上安装所需的 OpenTelemetry API 包，以及 OpenTelemetry SDK。

在 Kafka Connect 上安装 OpenTelemetry 主要有三种方法，每种方法都有其优点

手动安装

提供更多控制和自定义。

Docker 安装

提供更轻松的集成。

Strimzi 安装

在 Kubernetes 上提供现成的解决方案，其中包含所有必需的 OpenTelemetry 组件。

手动安装 OpenTelemetry

手动安装可提供更大的控制和自定义。

安装 OpenTelemetry API

将以下软件包安装到 Kafka Connect 类路径中

您可以直接从 Maven 存储库下载 OpenTelemetry 包，或使用 Maven 依赖插件检索包以确保版本兼容性。

使用 Maven 依赖插件

  1. 创建一个类似于以下示例的 POM 文件。在您的文件中，指定要使用的 OpenTelemetry 包的版本。

    <?xml version="1.0"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>group.id</groupId>
 <artifactId>artifact-id</artifactId>
 <version>0.0.1</version>
 <properties>
  <version.opentelemetry.api>1.23.1</version.opentelemetry.api>
  <version.opentelemetry.kafka.clients.2.6>1.23.0-alpha</version.opentelemetry.kafka.clients.2.6>
 </properties>
 <dependencies>
  <dependency>
   <groupId>io.opentelemetry</groupId>
   <artifactId>opentelemetry-api</artifactId>
   <version>${version.opentelemetry.api}</version>
  </dependency>
  <dependency>
   <groupId>io.opentelemetry.instrumentation</groupId>
   <artifactId>opentelemetry-kafka-clients-2.6</artifactId>
   <version>${version.opentelemetry.kafka.clients.2.6}</version>
  </dependency>
 </dependencies>
</project>

  2. 在包含 pom.xml 文件的目录中，运行以下命令将所有依赖项（包括传递依赖项）下载到指定目录（例如 ./lib）

    mvn dependency:copy-dependencies -DoutputDirectory=./lib

安装 OpenTelemetry SDK

安装 API 后，安装 OpenTelemetry SDK。使用Java 代理在 Kafka Connect 集群上安装 OpenTelemetry SDK 以实现自动检测。

使用 Docker 安装 OpenTelemetry

如果您想在本地开发或测试中使用 Docker，请优先选择此安装方法。

OpenTelemetry API 依赖项已安装在Debezium Kafka Connect容器镜像中。JAR 文件下载到单独的目录中。默认情况下，JAR 文件不会添加到类路径。要将 JAR 文件添加到类路径，请将环境变量 ENABLE_OTEL 设置为 true。您还必须安装OpenTelemetry Java 代理。

使用 Strimzi 安装 Open Telemetry

Strimzi 提供了一种在 Kubernetes 上部署 Apache Kafka 集群的方法。

Strimzi Kafka 镜像包含所有必需的 OpenTelemetry 组件。

如果您想查看 Strimzi 镜像中可用的 OpenTelemetry 组件，请检查Debezium Outbox 示例中提供的复合文件。

配置 OpenTelemetry

有关如何配置 OpenTelemetry 的信息，请参阅OpenTelemetry 文档。

Debezium 已在 Debezium Kafka Connect 镜像和包含以下配置设置的 Strimzi 发行版上进行了测试

  • otel.traces.exporter=otlp

  • otel.propagators=tracecontext

ActivateTracingSpan SMT

Debezium 中跟踪的主要实现点是 io.debezium.transforms.tracing.ActivateTracingSpan SMT。在这种情况下，写入数据库的应用程序负责提供跟踪跨度上下文。编写器必须将跨度上下文注入到 java.util.Properties 实例中，该实例将被序列化并作为表的独立字段写入数据库。

如果未提供跨度上下文，则 SMT 将创建新的跨度。在这种情况下，Debezium 操作以及元数据将被跟踪，但不会与业务事务跟踪连接以实现端到端跟踪。

当调用此 SMT 并带有一个消息时，它将

  • 提取消息中存在的父跨度上下文

  • 创建事件 db-log-write 跨度上下文，并将开始时间戳设置为数据库日志写入时间戳

  • 将 source 块的字段插入到跨度中作为**标签**

  • 将处理 debezium-read 跨度创建为 db-log-write 跨度的子项，并将开始时间戳设置为事件的处理时间

  • 将信封中的字段（如 op）插入到处理跨度中作为**标签**

  • 将处理跨度上下文注入到消息头中

Kafka Producer 跟踪

可以选择在 Kafka Producer 级别启用跟踪。如果您在 Kafka Producer 中启用了跟踪，当消息写入 Kafka Broker 时，Producer 会从 Kafka 消息头中提取 Debezium 处理跨度上下文，创建一个新的子跨度，然后记录有关写入 Broker 的操作的信息。然后，它将新跨度注入到消息头中，以便消息的 Consumer 可以恢复跟踪并继续端到端跟踪。

如果启用了 Kafka 检测，拦截器就无法传播可跟踪性上下文。拦截器在将检测委托给 OpenTelemetry SDK 之前，仅传播可跟踪性上下文。

启用端到端可跟踪性

  1. 下载并安装debezium-interceptor到 Kafka Connect 类路径。

  2. 通过将 otel.instrumentation.common.default-enabled 的值设置为 false 来禁用 Kafka Producer 和 Consumer 上的自动 OpenTelemetry 检测。

配置选项

配置属性

Type

Default (默认值)
tracing.span.context.field

包含跨度上下文的字段名称。

发送方必须将跨度上下文写入数据库列中，作为一个序列化的 java.util.Properties 实例，其中注入了跨度上下文。

string

tracingspancontext
tracing.operation.name

表示 Debezium 处理跨度的操作名称。

string

debezium-read
tracing.with.context.field.only

只有包含序列化上下文字段的事件才会被跟踪。

如果设置为 true，则仅为具有关联跟踪跨度上下文字段的事件创建跟踪跨度。如果设置为 false，则为所有传入事件创建跟踪跨度，而不管其是否具有关联的跨度上下文。

boolean

false

Outbox 扩展

用于实现 Outbox 模式的 DebeziumQuarkus 扩展提供了开箱即用的上下文传播跟踪所需的附加功能。具体来说，它在 Outbox 表中提供了 tracingspancontext 字段，该字段用于将跟踪跨度上下文从使用 Outbox 扩展的服务传递到 Debezium 连接器。

当发出 Outbox 事件时，扩展将

  • 创建一个新的 outbox-write 跨度，作为当前活动跨度的子项

  • 将跨度上下文注入到序列化到 tracingspancontext 列中的 java.util.Properties 实例中

  • 将记录写入数据库

如果存在 quarkus-opentelemetry 扩展，Outbox 扩展中的跟踪集成将自动启用。如果您想在存在 quarkus-opentelemetry 扩展的情况下禁用 Outbox 扩展的跟踪支持，请在 Quarkus application.properties 文件中将选项 quarkus.debezium-outbox.tracing.enabled=false 设置为 false。

Event Router SMT

Event Router SMT 是 Outbox 扩展的对应项，它执行与 ActivateTracingSpan SMT 相同的步骤，并代替它使用。