日志记录
Overview
在本指南中,您可了解如何在 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 驱动程序中运行标准操作不会从 Log 4J2 中生成输出。要了解如何更改 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 框架定义了以下日志级别。以下按从最紧急到最不紧急的顺序列出这些日志级别:
致命
ERROR
WARN
INFO
DEBUG
TRACE
所有
将 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"
的祖先。
举例来说,这是代码中记录器的层次结构。
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 管理扩展)
示例 - 名称
此示例演示如何更改特定驱动程序记录器的日志级别。我们将 root 记录器设置为 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 配置指南。