日志记录
概述
本指南将教会您如何在MongoDB Java驱动程序中设置和配置记录器。
您将学习如何
使用Simple Logging Facade For Java (SLF4J)设置记录器
配置记录器的日志级别
本指南展示了如何在驱动程序中记录事件。如果您想了解如何在代码中使用有关驱动程序活动信息，请考虑阅读我们的监控指南.
设置记录器
本部分提供了设置记录器所需的依赖项背景信息，并提供了记录器设置示例。
背景
MongoDB Java驱动程序使用Simple Logging Facade For Java (SLF4J)。SLF4J允许您在部署时指定您选择的日志框架。有关SLF4J的更多信息，请参阅SLF4J文档.
设置记录器是可选的。当您启动应用程序时，MongoDB Java驱动程序会在您的类路径中查找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组件与记录框架连接的代码片段。以下示例显示了如何将slf4j-api组件绑定到两个最流行的记录框架：Log4j2和Logback。
示例 - 设置
此示例显示了如何设置您的记录器。单击您项目要使用的记录框架对应的选项卡。
选择您项目使用的构建工具。
将以下依赖项添加到您的pom.xml文件中。
<dependencies> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.2.11</version> </dependency> </dependencies>
将以下依赖项添加到您的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>); collection.find().first();
您应看到类似于以下内容的输出
... 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的更多信息，请参阅Logback手册。
选择您项目使用的构建工具。
将以下依赖项添加到您的pom.xml文件中。
<dependencies> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-slf4j-impl</artifactId> <version>2.17.1</version> </dependency> </dependencies>
将以下依赖项添加到您的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
注意
默认记录级别
Log4J2的默认日志级别是ERROR。这意味着在不进行配置的情况下，运行MongoDB Java驱动程序的标准操作不会产生Log4J2的输出。有关如何更改Log4J2日志记录器的日志级别的示例，请参阅本页面“配置您的日志记录器”部分的示例。
有关Log4j2的更多信息，请参阅Log4j2手册。
配置您的日志记录器
要配置您的日志记录器，您必须使用与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>); collection.find().first();
您应该看到类似以下内容的输出。
... 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手册。
在名为 log4j2.xml 的文件中指定Log4j2配置。您不需要在特定位置创建您的 log4j2.xml 文件，但您必须能够从类路径访问它。
Log4j2框架定义了以下日志级别。以下列出了日志级别，按紧急程度从高到低排序
FATAL
ERROR
WARN
INFO
DEBUG
TRACE
ALL
将您的 log4j2.xml 文件设置为以下内容。
<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> <Root level="INFO"> <AppenderRef ref="Console"/> </Root> </Loggers> </Configuration>
要测试您的记录器配置是否成功，运行以下代码。
MongoClient mongoClient = MongoClients.create(<connection uri>); MongoDatabase database = mongoClient.getDatabase(<database>); MongoCollection<Document> collection = database.getCollection(<collection>); collection.find().first();
您应该看到类似以下内容的输出。
... 10:14:57.633 [cluster-ClusterId{value=<your cluster id>, description='null'}-<your connection uri>] INFO org.mongodb.driver.cluster - Discovered replica set primary <your connection uri> 10:14:57.790 [main] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
有关配置Log4j2的更多信息，请参阅官方Log4j2配置指南。
日志器名称
您的日志器使用日志器名称来帮助组织不同的日志事件。日志器名称是表示层级的字符串。如果一个日志器的名称加上一个"."是另一个日志器名称的前缀，那么这个日志器就是另一个日志器的祖先。例如，"grandparent"是"grandparent.parent"的祖先，而"grandparent.parent.child"又是"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中的类继承。
MongoDB Java驱动程序定义以下日志器名称来组织驱动程序中的不同日志事件。以下是驱动程序中定义的日志器名称及其对应的日志事件。
org.mongodb.driver.authenticator: 认证org.mongodb.driver.client: 与MongoClient实例相关的事件org.mongodb.driver.cluster: 监控MongoDB部署org.mongodb.driver.connection: 连接和连接池org.mongodb.driver.connection.tls: TLS/SSLorg.mongodb.driver.operation: 操作，包括与自动重试相关的日志org.mongodb.driver.protocol: 发送到MongoDB部署的命令和从MongoDB部署收到的回复org.mongodb.driver.uri: 连接字符串解析org.mongodb.driver.management: JMX (Java 管理扩展)
示例 - 名称
此示例演示如何更改特定驱动程序日志记录器的日志级别。我们将根日志记录器设置为 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>); collection.find().first();
您应该看到类似以下内容的输出。
... 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 配置指南。
将您的 log4j2.xml 文件设置为以下内容。
<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>); collection.find().first();
您应该看到类似以下内容的输出。
... 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>
有关配置 Log4j2 的更多信息，请参阅官方 Log4J2 配置指南。