KnowForge/Debezium 简体中文
集成

OpenTelemetry

qianmoQqianmoQ· 更新于 2026-09-28· 阅读 15 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

分布式追踪

概述

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

当应用程序向数据库写入记录、而该记录随后由 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 Dependency 插件
  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>

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

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

安装 OpenTelemetry SDK

安装 API 之后，请安装 OpenTelemetry SDK。在 Kafka Connect 集群上安装 OpenTelemetry SDK 时，请使用 Java agent 来实现自动插桩。

使用 Docker 安装 OpenTelemetry

如果你希望使用 Docker 进行本地开发或测试，建议采用这种安装方式。

OpenTelemetry API 依赖项已包含在 Debezium Kafka Connect 容器镜像中。JAR 文件被下载到一个单独的目录中。默认情况下，这些 JAR 文件不会被添加到类路径中。要将 JAR 文件添加到类路径，请将环境变量 ENABLE_OTEL 设置为 true。此外，你还需要安装 OpenTelemetry Java agent。

使用 Strimzi 安装 OpenTelemetry

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

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

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

配置 OpenTelemetry

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

Debezium 已使用 Debezium Kafka Connect 镜像以及包含以下配置设置的 Strimzi 发行版进行了测试：

  • otel.traces.exporter=otlp
  • otel.propagators=tracecontext

ActivateTracingSpan SMT

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

如果未提供 span 上下文，则该 SMT 会创建一个新的 span。在这种情况下，Debezium 操作及其元数据将被追踪，但不会与业务事务追踪相关联，因此无法实现端到端追踪。

当该 SMT 接收到消息时，它会执行以下操作：

  • 如果消息中存在父 span 上下文，则提取该父 span 上下文
  • 创建事件 db-log-write span 上下文，其开始时间戳设置为数据库日志写入时间戳
  • 将 source 块中的字段作为标签插入到 span 中
  • 创建处理 debezium-read span，作为 db-log-write span 的子 span，其开始时间戳设置为事件的处理时间
  • 将信封中的字段（如 op）作为标签插入到处理 span 中
  • 将处理 span 上下文注入到消息头中

Kafka Producer 追踪

可选地，可以在 Kafka 生产者级别启用跟踪。如果你在 Kafka 生产者中启用了跟踪，那么在消息写入 Kafka broker 时，生产者会从 Kafka 消息头中提取 Debezium 处理跨度（span）上下文，创建一个新的子跨度，然后记录关于写入 broker 操作的信息。接着它会将新的跨度注入到消息头中，这样消息的消费者就可以恢复跟踪并继续进行端到端跟踪。

如果启用了 Kafka 插桩，拦截器无法传播可跟踪上下文。拦截器只是在将插桩工作委派给 OpenTelemetry SDK 之前，先传播可跟踪上下文。

启用端到端可跟踪性

  1. 下载并安装 debezium-interceptor 到 Kafka Connect 的 classpath 中。
  2. 通过将 otel.instrumentation.common.default-enabled 的值设置为 false，禁用 Kafka 生产者和消费者上的自动 OpenTelemetry 插桩。

配置选项

配置属性

类型

默认值

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）模式的 Debezium Quarkus 扩展提供了开箱即用的、跟踪上下文传播所需的附加功能。具体来说，它在发件箱表中提供了 tracingspancontext 字段，用于将跟踪跨度上下文从使用发件箱扩展的服务传递到 Debezium 连接器。

当发出一个发件箱事件时，该扩展会：

  • 以当前活动跨度为父跨度，创建一个新的 outbox-write 跨度
  • 将跨度上下文注入到序列化到 tracingspancontext 列中的那个 java.util.Properties 实例
  • 将记录写入数据库

如果存在 quarkus-opentelemetry 扩展，发件箱扩展中的跟踪集成会自动启用。如果你希望尽管存在 quarkus-opentelemetry 扩展，仍然禁用发件箱扩展的跟踪支持，可以在 Quarkus 的 application.properties 文件中设置选项 quarkus.debezium-outbox.tracing.enabled=false。

事件路由器 SMT

事件路由器 SMT 作为 Outbox 扩展的对应组件，执行与 ActivateTracingSpan SMT 相同的步骤，并用于替代它。

评论

登录后参与评论

正在加载评论…