分布式跟踪

概述
安装
ActivateTracingSpan SMT
- Kafka 生产者跟踪
- 配置选项
出站扩展
事件路由 SMT

概述

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

当应用程序将记录写入数据库，然后由 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 依赖插件

创建一个类似于以下示例的 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>

在包含 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 跨度的子级，并将开始时间戳设置为事件的处理时间
将 envelope 中的字段（如 op）作为 **标签** 插入到处理跨度中
将处理跨度上下文注入消息头

Kafka 生产者跟踪

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

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

启用端到端可跟踪性

将 debezium-interceptor 下载并安装到 Kafka Connect 类路径中。
通过将 otel.instrumentation.common.default-enabled 的值设置为 false，禁用 Kafka 生产者和消费者的自动 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

出站扩展

用于实现出站模式的 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 作为出站扩展的对应项，它执行与 ActivateTracingSpan SMT 相同的步骤，并代替它使用。