日志记录

Overview

在本指南中，您可以学习；了解如何在MongoDB Scala驾驶员中设立和配置记录器。

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

设置记录器

本节介绍设立记录器所需的依赖项，并提供了一个记录器设置示例。

背景

MongoDB Scala驾驶员使用Java简易日志记录门面 (SLF4J)。使用 SLF4J 时，您可以在部署时指定日志记录框架。在Scala驾驶员中设置记录器是可选项。

当您启动应用程序时， MongoDB Scala驾驶员会在类路径中查找 slf4j-api 工件。如果驾驶员找不到 slf4j-api 工件，则会记录以下警告并禁用所有进一步的日志记录：

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

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

slf4j-api 工件
日志框架
绑定，用于将slf4j-api 产品连接到日志框架

以下示例展示了如何将 slf4j-api 产品绑定到所选日志记录框架。

记录器示例

选择 Logback 或 Log4j2标签页以设立所选日志记录框架并查看相应的代码示例：

要使用 Logback，将以下行添加到项目的 build.sbt文件中。这些行包括 slf4j-api 工件、日志记录框架和绑定。

libraryDependencies += "org.slf4j" % "slf4j-api" % "2.0.13"
libraryDependencies += "ch.qos.logback" % "logback-classic" % "1.5.6"

要测试您的 Logback设置，请将以下代码添加到项目的 Main.scala文件中。该代码连接到您的MongoDB 部署并检索文档。添加代码后，使用 sbt run 在终端而不是 IDE 中运行应用程序。

val mongoClient = MongoClient("<connection string>")
val database: MongoDatabase = mongoClient.getDatabase("<database>")
val collection: MongoCollection[Document] = database.getCollection("<collection>")
collection.find().first().printHeadResult()

...
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。 DEBUG 级别记录用于故障排除的详细诊断消息，例如打开的连接以及驾驶员发送到 MongoDB 和从MongoDB接收的命令。要学习；了解如何更改 Logback 记录器的日志级别，请参阅本页配置记录器部分的示例。

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

要使用 Log4j2，将以下行添加到项目的 build.sbt文件中。这些行包括 slf4j-api 工件、日志记录框架和绑定。

libraryDependencies += "org.slf4j" % "slf4j-api" % "2.0.13"
libraryDependencies += "org.apache.logging.log4j" % "log4j-slf4j2-impl" % "2.24.3"
libraryDependencies += "org.apache.logging.log4j" % "log4j-core" % "2.24.3"

要测试 Log4j2设置，请将以下代码添加到项目的 Main.scala文件中。该代码会记录错误消息。添加代码后，使用 sbt run 在终端而不是 IDE 中运行应用程序。

import org.slf4j.Logger
import org.slf4j.LoggerFactory
val 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。这意味着，如果没有配置日志级别，在MongoDB Scala驾驶员中运行标准操作不会产生 Log4 j2 的输出。要学习；了解如何更改 Log4 j2 记录器的日志级别，请参阅本页“配置记录器”部分中的示例。

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

有关 SLF4 J 的更多信息，请参阅 SLF4 J 文档。

配置您的记录器

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

配置示例

日志级别指定记录器输出该消息的紧急程度。以下示例展示了如何使用每个日志记录框架的配置系统将日志级别设立为 INFO。选择Logback 或Log4j2 标签页，查看每种方法对应的代码：

Logback 从类路径上名为 logback.xml 的文件中读取其配置。默认下，此文件不存在，因此必须创建它。您可以将 logback.xml 放置在Scala项目中的任何位置，只要可从类路径访问即可。

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

ERROR
WARN
INFO
DEBUG
TRACE

要进一步学习；了解每个日志级别的含义，请参阅 Logback 文档中的有效级别。

将以下代码插入 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>

要测试记录器配置是否成功，请使用 sbt run 命令而不是 IDE运行以下代码：

val mongoClient = MongoClient("<connection string>")
val database: MongoDatabase = mongoClient.getDatabase("<database>")
val collection: MongoCollection[Document] = database.getCollection("<collection>")
collection.find().first().printHeadResult()

...
1317 [cluster-<your cluster id>-<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 从类路径上名为 log4j2.xml 的文件中读取其配置。默认下，此文件不存在，因此必须创建它。您可以将 log4j2.xml 放置在Scala项目中的任何位置，只要可从类路径访问即可。

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

致命
ERROR
WARN
INFO
DEBUG
TRACE
所有

要详细学习；了解每个日志级别的含义，请参阅 Log4 j2 文档中的自定义日志级别。

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

要测试记录器配置是否成功，请使用 sbt run 命令而不是 IDE运行以下代码：

val mongoClient = MongoClient("<connection string>")
val database: MongoDatabase = mongoClient.getDatabase("<database>")
val collection: MongoCollection[Document] = database.getCollection("<collection>")
collection.find().first().printHeadResult()

...
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 文档中的 Log4 j2 配置指南。

记录器名称

日志记录框架使用分层记录器名称来组织日志记录事件。如果一个记录器的名称后跟"." 是另一个记录器名称的前缀，则该记录器是另一个记录器的祖先。示例，grandparent 记录器是grandparent.parent 记录器的祖先，而后者又是grandparent.parent.child 记录器的祖先。

以下代码创建一个 parent 记录器和一个 parent.child 记录器，其中 parent 记录器是 parent.child 记录器的祖先：

import org.slf4j.Logger
import org.slf4j.LoggerFactory
val loggerParent: Logger = LoggerFactory.getLogger("parent")
val loggerChild: Logger = LoggerFactory.getLogger("parent.child")

记录器层次结构类似于Scala中的类层次结构：记录器继承其祖先记录器的属性，也可以定义自己的属性。

Scala驾驶员包含以下默认记录器名称：

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部署交换的命令和回复
org.mongodb.driver.uri：连接字符串解析
org.mongodb.driver.management: Java 管理扩展 (JMX)

记录器名称示例

以下示例展示了如何将根记录器配置设立为 OFF 并将 org.mongodb.driver.connection 记录器配置设置为 INFO，以便应用程序仅记录与连接到MongoDB 部署相关的消息。

选择 Logback 或 Log4j2标签页，查看相应框架的示例配置和输出：

将以下代码插入 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>

要测试记录器配置是否成功，请使用 sbt run 命令而不是 IDE运行以下代码：

val mongoClient = MongoClient("<connection string>")
val database: MongoDatabase = mongoClient.getDatabase("<database>")
val collection: MongoCollection[Document] = database.getCollection("<collection>")
collection.find().first().printHeadResult()

...
829  [cluster-<your cluster id>-<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>

要测试记录器配置是否成功，请使用 sbt run 命令而不是 IDE运行以下代码：

val mongoClient = MongoClient("<connection string>")
val database: MongoDatabase = mongoClient.getDatabase("<database>")
val collection: MongoCollection[Document] = database.getCollection("<collection>")
collection.find().first().printHeadResult()

...
15:40:23.005 [cluster-<your cluster id>-<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 配置指南。

客户端日志记录设置

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

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

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

客户端日志记录设置示例

以下示例为发送请求的应用程序命名，并指定 5000 个字符作为最大日志消息长度。使用 sbt run 命令而不是 IDE 运行该示例。

val mongoClient = MongoClient(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applicationName("<application name>")
        .applyToLoggerSettings(builder =>
            builder.maxDocumentLength(5000))
        .build())

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

有关更多信息，请参阅 MongoClientSettings.Builder API文档。

后退

监控

来年

Change Streams