/ /

日志记录

Overview

在本指南中，您将学习；了解如何：

使用 Simple Logging Facade For Java (SLF4J) 设置记录器
配置记录器的日志级别

本指南介绍如何在驾驶员中记录事件。要学习；了解如何在代码中使用驾驶员的活动信息，请参阅监控指南。

重要

项目 Reactor 库

本指南使用 Project Reactor 库来使用Java Reactive Streams驱动程序方法返回的 Publisher 实例。要学习；了解有关 Project Reactor 库及其使用方法的更多信息，请参阅 Reactor 文档中的入门。

设置记录器

本部分介绍设置记录器所需的相关背景信息，并提供了一个示例记录器设置。

背景

Java Reactive Streams驾驶员使用 Simple Logging Facade For Java (SLF4 J)。 SLF4 J 允许您在部署时指定所选的日志记录框架。有关 SLF4 J 的更多信息，请参阅 SLF4 J 文档。

设置记录器是可选项。当您启动应用程序时， Java Reactive Streams驾驶员会在类路径中查找 slf4j-api 工件。如果驾驶员找不到 slf4j-api 工件，驾驶员会使用 java.util.logging日志以下警告并禁用所有进一步的日志记录：

WARNING: SLF4J not found on the classpath.  Logging is disabled for the 'org.mongodb.driver' component

要设立记录器，必须在项目中包含以下内容：

slf4j-api 工件
日志框架
绑定关系

注意

对于最受欢迎的日志记录框架，通常有一个绑定文件将 slf4j-api 和日志记录框架列为依赖项。这意味着您可以向项目的依赖项列表添加一份绑定文件，从而设置记录器。下面的示例说明了这一点。

绑定是一段将 slf4j-api 产品与日志框架连接起来的代码。选择一个标签页，学习；了解如何设立和配置记录器：

示例 — 设置

此示例展示了如何设立Logback 记录器。

提示

依赖项版本

以下版本仅供参考，并非事实来源。查看 SLF4J 和您选择的日志框架的官方文档，确保获得最新的版本信息。

根据您的构建工具选择 Maven 或 Gradle 指令：

Maven

将以下依赖项添加到您的pom.xml文件：

<dependencies>
  <dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.11</version>
  </dependency>
</dependencies>

Gradle

将以下依赖项添加到您的build.gradle文件：

dependencies {
   implementation 'ch.qos.logback:logback-classic:1.2.11'
}

包含前面的依赖项后，连接到MongoDB实例并使用以下代码检索文档：

MongoClient mongoClient = MongoClients.create("<connection URI>");
MongoDatabase database = mongoClient.getDatabase("<database>");
MongoCollection<Document> collection = database.getCollection("<collection>");
Flux.from(collection.find()).blockFirst();

您应该会看到如下所示的输出：

...
12:14:55.853 [main] DEBUG org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:3}] to <MongoDB hostname>
12:14:55.861 [main] DEBUG org.mongodb.driver.protocol.command - Command "find" started on database <database> using a connection with driver-generated ID 3 and server-generated ID 3 to <MongoDB hostname>. The request ID is 5. Command: {"find": "<collection>", "filter": {}, "limit": 1, "singleBatch": true, "$db": "<database>", "lsid": {"id": {"$binary": {"base64": "<_id>", "subType": "04"}}}, "$readPreference": {"mode": "primaryPreferred"}}
12:14:55.864 [main] DEBUG org.mongodb.driver.protocol.command - Command "find" succeeded in 4.34 ms using a connection with driver-generated ID 3 and server-generated ID 3 to <MongoDB hostname>. The request ID is 5. Command reply: {"cursor": {"id": 0, "ns": "<database>.<collection>", "firstBatch": []}, "ok": 1.0, "$clusterTime": {"clusterTime": {"$timestamp": {"t": 1673778535, "i": 1}}, "signature": {"hash": {"$binary": {"base64": "<_id>", "subType": "00"}}, "keyId": 0}}, "operationTime": {"$timestamp": {"t": 1673778535, "i": 1}}}

注意

默认日志级别

Logback 的默认日志级别为 DEBUG。要了解如何更改 Logback 记录器的日志级别，请参阅本页面配置记录器部分的示例。

有关 Logback 的更多信息，请参阅 Logback 手册。

配置您的记录器

要配置您的记录器，您必须使用绑定到 SLF4J 的日志框架的配置系统。

以下示例展示了如何使用日志记录框架的配置系统来设立记录器的日志级别。

日志记录器的日志级别规定了日志记录器输出消息的紧急程度下限。

示例 - 配置

此示例演示如何将记录器的日志级别配置为 INFO。

在名为 logback.xml 的文件中指定 Logback 配置。您不必在特定位置创建 logback.xml 文件，但必须能够从类路径访问该文件。

Logback框架定义了以下日志级别，按从最紧急到最不紧急的顺序排列：

ERROR
WARN
INFO
DEBUG
TRACE

将以下代码插入 logback.xml文件：

<configuration>
   <appender name="CONSOLE"
             class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>
               %-4relative [%thread] %-5level %logger{30} - %msg%n
         </pattern>
      </encoder>
   </appender>
   <root level="INFO">
      <appender-ref ref="CONSOLE" />
   </root>
</configuration>

要测试记录器配置是否成功，请运行以下代码：

MongoClient mongoClient = MongoClients.create("<connection URI>");
MongoDatabase database = mongoClient.getDatabase("<database>");
MongoCollection<Document> collection = database.getCollection("<collection>");
Flux.from(collection.find()).blockFirst();

您应该会看到如下所示的输出：

...
1317 [cluster-ClusterId{value='<your cluster id>', description='null'}-<your connection uri>] INFO  org.mongodb.driver.cluster - Discovered replica set primary <your connection uri>
1568 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<server value>}] to <your connection uri>

有关配置 Logback 的更多信息，请参阅Logback 手册。

记录器名称

记录器使用记录器名称来帮助组织不同的日志事件。记录器名称是构成层次结构的字符串。如果一个记录器的名称后跟 "." 是另一个记录器名称的前缀，则该记录器是另一个记录器的祖先。示例，"grandparent" 是 "grandparent.parent" 的祖先，而又是 "grandparent.parent.child" 的祖先。

举个具体示例，记录器层次结构在代码中如下所示：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
Logger logger_parent = LoggerFactory.getLogger("parent");
Logger logger_child = LoggerFactory.getLogger("parent.child");

记录器继承其“祖先”记录器的属性，并可以定义自己的属性。您可以认为这类似于 Java 中的类继承。

Java Reactive Streams驾驶员定义了以下记录器名称来组织驾驶员中的不同日志事件：

org.mongodb.driver.authenticator：身份验证
org.mongodb.driver.client：与 MongoClient 个实例相关的事件
org.mongodb.driver.cluster：监控MongoDB部署
org.mongodb.driver.connection：连接和连接池
org.mongodb.driver.connection.tls：TLS/SSL
org.mongodb.driver.operation：操作，包括与自动重试相关的日志记录
org.mongodb.driver.protocol.command：发送到 MongoDB 部署的命令和从MongoDB部署收到的回复
org.mongodb.driver.uri：连接字符串解析
org.mongodb.driver.management： Java管理扩展 (JMX)

示例 - 名称

此示例演示如何更改特定驾驶员记录器的日志级别。该示例将根记录器设置为 OFF，并将 org.mongodb.driver.connection 记录器设置为 INFO。这会导致应用程序仅日志与连接到MongoDB实例相关的消息。

将以下代码插入 logback.xml文件：

<configuration>
   <appender name="CONSOLE"
             class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>
               %-4relative [%thread] %-5level %logger{30} - %msg%n
         </pattern>
      </encoder>
   </appender>
   <logger name="org.mongodb.driver.connection" level="INFO" additivity="true"/>
   <root level="OFF">
      <appender-ref ref="CONSOLE" />
   </root>
</configuration>

要测试记录器配置是否成功，请运行以下代码：

MongoClient mongoClient = MongoClients.create("<connection URI>");
MongoDatabase database = mongoClient.getDatabase("<database>");
MongoCollection<Document> collection = database.getCollection("<collection>");
Flux.from(collection.find()).blockFirst();

您应该会看到如下所示的输出：

...
829  [cluster-rtt-ClusterId{value='<some value>', description='null'}-<your connection URI>] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:2, serverValue:<your server value>}] to <your connection uri>
977  [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>

有关配置 Logback 的更多信息，请参阅官方 Logback 配置指南。

示例 — 设置

此示例展示了如何设立Log4j 记录器。

提示

依赖项版本

以下版本仅供参考，并非事实来源。查看 SLF4J 和您选择的日志框架的官方文档，确保获得最新的版本信息。

根据您的构建工具选择 Maven 或 Gradle 指令：

Maven

将以下依赖项添加到您的pom.xml文件：

<dependencies>
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-slf4j-impl</artifactId>
    <version>2.17.1</version>
  </dependency>
</dependencies>

Gradle

将以下依赖项添加到您的build.gradle文件：

dependencies {
  implementation 'org.apache.logging.log4j:log4j-slf4j-impl:2.17.1'
}

包含前面的依赖项后，使用以下代码日志错误：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
Logger logger = LoggerFactory.getLogger("MyApp");
logger.error("Logging an Error");

您应该会看到如下所示的输出：

12:35:00.438 [main] ERROR <my package path> - Logging an Error

注意

默认日志级别

Log4 j2 的默认日志级别为 ERROR。如果没有配置，在Java Reactive Streams驾驶员中运行标准操作不会从 Log4 j2 中生成输出。要学习；了解如何更改 Log4 j2 记录器的日志级别，请参阅本页“配置记录器”部分中的示例。

有关 Log4j2 的详细信息，请参阅 Log4j2 手册。

配置您的记录器

要配置您的记录器，您必须使用绑定到 SLF4J 的日志框架的配置系统。

以下示例展示了如何使用日志记录框架的配置系统来设立记录器的日志级别。

日志记录器的日志级别规定了日志记录器输出消息的紧急程度下限。

记录器名称

举个具体示例，记录器层次结构在代码中如下所示：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
Logger logger_parent = LoggerFactory.getLogger("parent");
Logger logger_child = LoggerFactory.getLogger("parent.child");

记录器继承其“祖先”记录器的属性，并可以定义自己的属性。您可以认为这类似于 Java 中的类继承。

Java Reactive Streams驾驶员定义了以下记录器名称来组织驾驶员中的不同日志事件：

org.mongodb.driver.authenticator：身份验证
org.mongodb.driver.client：与 MongoClient 个实例相关的事件
org.mongodb.driver.cluster：监控MongoDB部署
org.mongodb.driver.connection：连接和连接池
org.mongodb.driver.connection.tls：TLS/SSL
org.mongodb.driver.operation：操作，包括与自动重试相关的日志记录
org.mongodb.driver.protocol.command：发送到 MongoDB 部署的命令和从MongoDB部署收到的回复
org.mongodb.driver.uri：连接字符串解析
org.mongodb.driver.management： Java管理扩展 (JMX)

示例 - 名称

将以下代码插入 log4j2.xml文件：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">
   <Appenders>
      <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
      </Console>
   </Appenders>
   <Loggers>
      <Logger name="org.mongodb.driver.connection" level="INFO"/>
      <Root level="OFF">
            <AppenderRef ref="Console"/>
      </Root>
   </Loggers>
</Configuration>

要测试记录器配置是否成功，请运行以下代码：

MongoClient mongoClient = MongoClients.create("<connection URI>");
MongoDatabase database = mongoClient.getDatabase("<database>");
MongoCollection<Document> collection = database.getCollection("<collection>");
Flux.from(collection.find()).blockFirst();

您应该会看到如下所示的输出：

...
15:40:23.005 [cluster-ClusterId{value='<some value>', description='null'}-<your connection uri>] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:<your server value>}] to <your connection uri>
15:40:23.159 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>

连接设置

您可以使用 applyToLoggerSettings() 和 applicationName() 方法将日志记录设置应用MongoClient实例。

下表描述了可以链接到记录器设置以修改日志记录行为的方法：

方法	说明
`maxDocumentLength()`	设置单个日志消息的最大文档长度（以字符为单位）默认：`1000`。

例子

此示例为发送请求的应用程序命名，并指定单个日志消息的最大字符数为 5000 个字符。

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyConnectionString(
            new ConnectionString("<connection URI>"))
        .applicationName("<application name>")
        .applyToLoggerSettings(builder ->
            builder.maxDocumentLength(5000))
        .build());
Flux.from(mongoClient.listDatabaseNames())
    .doOnNext(System.out::println)
    .blockLast();

您应该会看到如下所示的输出：

01:20:38.782 [main] INFO org.mongodb.driver.client -- MongoClient with
metadata {"application": {"name": "<application name>"}, ...,
loggerSettings=LoggerSettings{maxDocumentLength=5000}, ... timeoutMS=null}
...
01:20:41.022 [main] DEBUG org.mongodb.driver.protocol.command -- Command
"listDatabases" succeeded ... Command reply: {"databases": [...], ...}
01:20:41.024 [main] DEBUG org.mongodb.driver.connection -- Connection checked in: address=<address>, driver-generated ID=6
myDb
sample_airbnb
sample_analytics
...