Debezium 日志记录

Debezium 的连接器内置了丰富的日志功能，你可以更改日志配置，以控制哪些日志语句会出现在日志中，以及这些日志的输出位置。Debezium（以及 Kafka 和 Kafka Connect）在 Java 中使用 Log4j 日志框架。

默认情况下，连接器在启动时会产生大量有用的信息，但当连接器能够及时处理源数据库的变更时，日志输出就会非常少。当连接器运行正常时，这通常已经足够；但当连接器表现异常时，这些日志可能就不够用了。在这种情况下，你可以更改日志级别，让连接器生成更加详细的日志消息，描述连接器正在做什么以及没有在做什么。

日志记录的基本概念

Log4j 的日志配置决定了你会看到哪些 Debezium 消息以及它们出现在哪里，从而让你能够监控连接器健康状况、排查问题并理解连接器的行为。理解记录器（logger）、日志级别（log level）和输出器（appender）如何协同工作，有助于你设置合理的日志配置，以过滤日志输出，从而更清晰地查看相关信息。

记录器

Debezium 会将产生的每条日志消息发送给特定的记录器，例如 io.debezium.connector.mysql。记录器按层次结构组织。例如，io.debezium.connector.mysql 记录器是 io.debezium.connector 记录器的子记录器，而后者又是 io.debezium 记录器的子记录器。根记录器是层次结构中所有其他记录器的父记录器，其配置作为所有后代记录器的默认配置。你可以覆盖后代记录器的默认配置，为其指定特定的日志级别和输出器。

日志级别

应用程序会为每条日志消息指定以下日志级别之一：

输出器

输出器用于指定 Debezium 写入日志消息的目标位置。由于每个输出器都会将消息格式化工作委托给关联的布局（Layout），因此你可以通过将消息发送到特定的输出器来控制消息格式。

理解默认日志配置

如果你在 Kafka Connect 进程中运行 Debezium 连接器，那么 Kafka Connect 会使用 Kafka 安装目录下的 Log4j 配置文件（例如 /opt/kafka/config/connect-log4j.properties）。以下代码块展示了 connect-log4j.properties 中默认配置的示例：

log4j.rootLogger=INFO, stdout

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=[%d] %p %m (%c)%n
...

以下列表说明了前面 connect-log4j.properties 配置中的部分字段：

log4j.rootLogger

根日志器，用于定义默认的日志器配置。默认情况下，日志器包含 INFO、WARN 和 ERROR 级别的消息。这些日志消息会写入 stdout 附加器（appender）。

log4j.appender.stdout

将 stdout 附加器定向为把日志消息写入控制台，而不是写入文件。

log4j.appender.stdout.layout

指定 stdout 附加器使用模式匹配算法来格式化日志消息。

log4j.appender.stdout.layout.ConversionPattern

stdout 附加器所使用的模式（详情参见 Log4j 文档）。

除非你配置了其他日志器，否则 Debezium 使用的所有日志器都会继承 rootLogger 的配置。

配置日志

默认情况下，Debezium 连接器会将所有 INFO、WARN 和 ERROR 级别的消息写入控制台。你可以通过以下任一方法更改默认的日志配置：

• 通过配置日志器设置日志级别
• 使用 Kafka Connect REST API 动态设置日志级别
• 通过添加映射诊断上下文设置日志级别

通过配置日志器设置日志级别

默认的 Debezium 日志级别提供的信息足以显示连接器是否运行正常。但是，如果连接器运行不正常，你可以更改其日志级别来排查问题。

通常，Debezium 连接器会将日志消息发送给与生成该日志消息的 Java 类的完全限定名同名的日志器。Debezium 使用包来组织具有相似或相关功能的代码。这意味着你可以控制特定类的日志消息，或控制特定包内及以下所有类的日志消息。

操作步骤

1. 打开 connect-log4j.properties 文件。

2. 为连接器配置日志器。

   以下示例展示了一种可能的 connect-log4j.properties 配置，用于为 MySQL 连接器启用日志器，以便以 DEBUG 日志级别监控该连接器的数据库模式历史实现：

   ...
   log4j.logger.io.debezium.connector.mysql=DEBUG, stdout
   log4j.logger.io.debezium.relational.history=DEBUG, stdout
   
   log4j.additivity.io.debezium.connector.mysql=false
   log4j.additivity.io.debezium.storage.kafka.history=false
   ...

以下列表描述了前面 connect-log4j.properties 配置中的部分字段：

log4j.logger.io.debezium.connector.mysql

将名为 io.debezium.connector.mysql 的日志记录器配置为把 DEBUG、INFO、WARN 和 ERROR 级别的消息发送到 stdout 附加器（appender）。

log4j.logger.io.debezium.relational.history

将名为 io.debezium.relational.history 的日志记录器配置为把 DEBUG、INFO、WARN 和 ERROR 级别的消息发送到 stdout 附加器。

log4j.additivity.io.debezium.connector.mysql

这一对 log4j.additivity.io 条目会禁用可加性。如果你使用了多个附加器，应将 additivity 的值设置为 false，以防止重复的日志消息被发送到父日志记录器的附加器中。
3. 如有必要，修改连接器中某一特定类子集的日志级别。

提高整个连接器的日志级别会增加日志的详细程度，可能导致难以理解究竟发生了什么。在这种情况下，你可以只修改与所排查问题相关的那一组类的日志级别。

1. 将连接器的日志级别设置为 DEBUG 或 TRACE。

2. 查看连接器的日志消息。

   找出与所排查问题相关的日志消息。每条日志消息的末尾会显示生成该消息的 Java 类名。

3. 将连接器的日志级别恢复为 INFO。

4. 为你识别出的每个 Java 类分别配置日志记录器。

   例如，假设你不确定 MySQL 连接器在处理 binlog 时为什么会跳过某些事件。此时不必为整个连接器开启 DEBUG 或 TRACE 日志，而可以将连接器的日志级别保持为 INFO，只为读取 binlog 的那个类配置 DEBUG 或 TRACE：

   示例 1. 为 BinlogReader 类启用 DEBUG 日志的 connect-log4j.properties 配置

   ...
   log4j.logger.io.debezium.connector.mysql=INFO, stdout
   log4j.logger.io.debezium.connector.mysql.BinlogReader=DEBUG, stdout
   log4j.logger.io.debezium.relational.history=INFO, stdout
   
   log4j.additivity.io.debezium.connector.mysql=false
   log4j.additivity.io.debezium.storage.kafka.history=false
   log4j.additivity.io.debezium.connector.mysql.BinlogReader=false
   ...

使用 Kafka Connect REST API 动态设置日志级别

你可以使用 Kafka Connect REST API 在运行时动态设置连接器的日志级别。与在 connect-log4j.properties 中设置的日志级别变更不同，通过 API 所做的变更会立即生效，且无需重启工作进程。

在 API 中指定的日志级别仅适用于接收该请求的端点所在的工作进程，集群中其他工作进程的日志级别保持不变。

指定的级别在工作进程重启后不会被保留。要使日志级别的变更持久生效，请在 connect-log4j.properties 中通过配置日志记录器或添加映射诊断上下文来设置日志级别。

操作步骤

• 向 admin/loggers 端点发送 PUT 请求以设置日志级别，请求中需指定以下信息：

  • 要更改其日志级别的包。

  • 要设置的日志级别。

    curl -s -X PUT -H "Content-Type:application/json" http://localhost:8083/admin/loggers/io.debezium.connector.<connector_package> -d '{"level": "<log_level>"}'

例如，要记录 Debezium MySQL 连接器的调试信息，请向 Kafka Connect 发送以下请求：

```shell
curl -s -X PUT -H "Content-Type:application/json" http://localhost:8083/admin/loggers/io.debezium.connector.mysql -d '{"level": "DEBUG"}'
```

使用映射诊断上下文设置日志级别

大多数 Debezium 连接器（以及 Kafka Connect 工作进程）会使用多个线程来执行不同的活动。这会导致查看日志文件时，很难只找到与某个特定逻辑活动相关的日志消息。为了使日志消息更易于查找，Debezium 提供了若干映射诊断上下文（MDC），为每个线程提供额外信息。

Debezium 提供以下 MDC 属性：

dbz.connectorType

连接器类型的简短别名。例如 MySql、Mongo、Postgres 等。与同一类型的连接器相关的所有线程都使用相同的值，因此可以使用该属性查找由给定类型连接器产生的所有日志消息。

dbz.connectorLogicalName

在连接器配置中定义的连接器或数据库服务器的名称。例如 products、serverA 等。与特定连接器实例相关的所有线程都使用相同的值，因此可以找到由特定连接器实例产生的所有日志消息。

dbz.connectorContext

作为连接器任务中的独立线程运行的活动的简短名称。例如 main、binlog、snapshot 等。在某些情况下，当连接器将线程分配给特定资源（如表或集合）时，可能会使用该资源的名称来代替。与连接器相关的每个线程都会使用不同的值，因此可以找到与此特定活动相关的所有日志消息。

要为连接器启用 MDC，请在 connect-log4j.properties 文件中配置一个 appender。

操作步骤

1. 打开 connect-log4j.properties 文件。

2. 配置 appender 以使用任意受支持的 Debezium MDC 属性。在以下示例中，stdout appender 被配置为使用这些 MDC 属性。

   示例 2. 将 stdout appender 配置为使用 MDC 属性的 connect-log4j.properties 配置

   ...
   log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %-5p  %X{dbz.connectorType}|%X{dbz.connectorLogicalName}|%X{dbz.connectorContext}  %m   [%c]%n
   ...

上例中的配置会产生类似于以下输出的日志消息：

...
2017-02-07 20:49:37,692 INFO   MySQL|dbserver1|snapshot  Starting snapshot for jdbc:mysql://mysql:3306/?useInformationSchema=true&nullCatalogMeansCurrent=false&useSSL=false&useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=convertToNull with user 'debezium'   [io.debezium.connector.mysql.SnapshotReader]
2017-02-07 20:49:37,696 INFO   MySQL|dbserver1|snapshot  Snapshot is using user 'debezium' with these MySQL grants:   [io.debezium.connector.mysql.SnapshotReader]
2017-02-07 20:49:37,697 INFO   MySQL|dbserver1|snapshot  GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'debezium'@'%'   [io.debezium.connector.mysql.SnapshotReader]
...

日志中的每一行都包含连接器类型（例如 MySQL）、连接器名称（例如 dbserver1）以及线程的活动（例如 snapshot）。

在 Debezium 容器镜像中配置日志级别

用于 Kafka 和 Kafka Connect 的 Debezium 容器镜像都会设置各自的 log4j.properties 文件，以便配置与 Debezium 相关的日志记录器。所有日志消息都会发送到 Docker 容器的控制台（因此也会出现在 Docker 日志中）。日志消息同时也会写入 /kafka/logs 目录下的文件。

容器使用 LOG_LEVEL 环境变量来设置根日志记录器的日志级别。你可以使用该环境变量设置容器中运行的服务的日志级别。启动容器并将该环境变量的值设置为某个日志级别（例如 -e LOG_LEVEL=DEBUG），容器内的所有代码就会使用该日志级别。

还可以覆盖其他 log4j 属性。如果你想以不同的方式配置 log4j.rootLogger，请使用环境变量 CONNECT_LOG4J_LOGGERS。例如，若只想输出到标准输出（不使用 appender），可以使用 CONNECT_LOG4J_LOGGERS=INFO, stdout。你还可以设置带有 CONNECT_LOG4J 前缀的其他受支持的 log4j 环境变量，这些变量会通过移除 CONNECT_ 前缀、将所有字符转换为小写、并将所有 \_ 字符转换为 .，来映射为 log4j.properties 文件中的属性。

如果你需要对日志配置进行更多控制，请基于我们的镜像创建一个新的容器镜像，只需在你的 Dockerfile 中，将你自己的 log4j.properties 文件复制到镜像内。例如：

Dockerfile

...
COPY log4j.properties $KAFKA_HOME/config/log4j.properties
...