Docs 菜单
Docs 主页
/
语言
/
Java
/
java sync
/
Fundamentals

日志记录

在此页面上

  • Overview
  • 设置记录器
  • 背景
  • 示例 — 设置
  • 配置您的记录器
  • 示例 - 配置
  • 记录器名称
  • 示例 - 名称

Overview

在本指南中，您可了解如何在 MongoDB Java 驱动程序中设置和配置记录器。

您将了解如何：

  • 使用 Simple Logging Facade For Java (SLF4J) 设置记录器

  • 配置记录器的日志级别

本指南介绍如何在驱动程序中记录事件。如果您想了解如何在代码中使用有关驱动程序活动的信息，请参阅我们有关监控的指南。

设置记录器

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

背景

MongoDB Java 驱动程序使用 Simple Logging Facade For Java (SLF 4 J)。 SLF 4 J 允许您在部署时指定所选的日志记录框架。 有关 SLF4 J 的更多信息， 请参阅 SLF4 J 文档。

设置记录器是可选项。启动应用程序时，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。

示例 — 设置

此示例说明如何设置记录器。点击与要在项目中使用的日志记录框架相对应的标签页。

提示

依赖项版本

以下所列版本仅供参考，并非绝对真实的版本信息。您应检查 SLF4J 和您选择的日志框架的官方文档，以确保获得最新的版本信息。

选择您在项目中使用的构建工具。

将以下依赖项添加到您的 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 的默认日志级别为 DEBUG。要了解如何更改 Logback 记录器的日志级别，请参阅本页配置记录器部分的示例。

有关 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 记录器的日志级别，请参阅本页面配置记录器部分的示例。

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

配置您的记录器

要配置您的记录器，您必须使用绑定到 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的文件中指定 Log 4 j 2配置。您的log4j2.xml文件不必位于特定位置，但必须可以从类路径访问。

Log4j2 框架定义了以下日志级别。以下按从最紧急到最不紧急的顺序列出这些日志级别：

  • 致命

  • ERROR

  • WARN

  • INFO

  • DEBUG

  • TRACE

  • 所有

将 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>
      <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>

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

记录器名称

记录器使用记录器名称来帮助组织不同的日志事件。记录器名称是构成层次结构的字符串。如果一个记录器的名称加上 "." 是另一个记录器名称的前缀，则前者是后者的祖先。例如，"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/SSL

  • org.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 文件设置如下。

<?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>);
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>

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

后退

排序规则(Collations)