日志记录

在此页面上

Overview

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

Overview

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

您将了解如何：

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

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

设置记录器

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

背景

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

设置记录器是可选项。当您启动应用程序时，MongoDB Kotlin 驱动程序会在您的类路径中查找 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.kts文件：

dependencies {
   implementation("ch.qos.logback:logback-classic:1.2.11")
}

添加上述依赖项后，连接到 MongoDB 实例并使用以下代码检索文档：

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()

...
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.kts 文件中。

dependencies {
  implementation("org.apache.logging.log4j:log4j-slf4j-impl:2.17.1")
}

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

val loggerParent = LoggerFactory.getLogger("parent")
val loggerChild = LoggerFactory.getLogger("parent.child")

val loggerParent = LoggerFactory.getLogger("parent")
val loggerChild = LoggerFactory.getLogger("parent.child")

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

注意

默认日志级别

Log 4 J 2的默认日志级别为 ERROR。这意味着，如果没有配置，在MongoDB Kotlin驾驶员中运行标准操作不会从 Log 4 J 2中生成输出。要学习；了解如何更改 Log 4 J 2记录器的日志级别，请参阅本页“配置记录器”部分中的示例。

有关 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>

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

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()

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

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

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()

...
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.LoggerFactory

val loggerParent = LoggerFactory.getLogger("parent")
val loggerChild = LoggerFactory.getLogger("parent.child")

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

MongoDB Kotlin 驱动程序定义了以下记录器名称来组织驱动程序中的不同日志事件。以下是驱动程序中定义的记录器名称及其对应的日志事件：

org.mongodb.driver.authenticator ：身份验证
org.mongodb.driver.client ：与 MongoClient 个实例相关的事件
org.mongodb.driver.cluster ：监控 MongoDB Server
org.mongodb.driver.connection ：连接和连接池
org.mongodb.driver.connection.tls ：TLS/SSL
org.mongodb.driver.operation ：操作，其中包括与自动重试相关的日志记录操作
org.mongodb.driver.protocol ：发送到 MongoDB Server 的命令和从服务器接收的回复
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>

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

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()

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

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

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()

...
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)

来年

监控