Exploração madeireira

Visão geral

Neste guia, você pode aprender como configurar e configurar um logger no driver MongoDB Scala.

Este guia mostra como registrar eventos no driver. Se você quiser aprender como usar informações sobre a atividade do driver no código, consulte o guia Monitoramento.

Configurar um registrador

Esta seção explica as dependências necessárias para configurar um criador de logs e fornece um exemplo de configuração do criador de logs.

Plano de fundo

O driver Scala do MongoDB usa o Simple Logging Facade For Java (SLF4J). Você pode especificar um framework de registro em log no momento da implantação ao usar o SLF4J. Configurar um registrador é opcional no driver Scala.

Quando você inicia seu aplicativo, o driver MongoDB Scala procura o artefato slf4j-api em seu caminho de classe. Se o driver não conseguir encontrar o artefato slf4j-api, ele registrará o seguinte aviso e desativará todos os logs adicionais:

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

Para configurar um registrador, você deve incluir os seguintes componentes em seu projeto:

O artefato slf4j-api
Uma estrutura de registro
Uma vinculação, que conecta o artefato slf4j-api a um framework de registro

O exemplo a seguir mostra como vincular o artefato slf4j-api ao framework de registro escolhido.

Exemplo de registrador

Selecione a aba Logback ou Log4j2 para configurar o framework de registro escolhido e ver os exemplos de código correspondentes:

Para usar o Logback, adicione as seguintes linhas ao arquivo build.sbt do seu projeto. Essas linhas incluem o artefato slf4j-api, o framework de registro em log e a vinculação.

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

Para testar a configuração do Logback, adicione o seguinte código ao arquivo Main.scala do seu projeto. O código se conecta à sua implantação do MongoDB e recupera um documento. Depois de adicionar o código, use sbt run para executar seu aplicativo no terminal em vez do 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}}}

Observação

Nível de registro padrão

O nível de log padrão do Logback é DEBUG. O nível DEBUG registra mensagens de diagnóstico detalhadas destinadas à solução de problemas, como conexões abertas e os comandos que o driver envia e recebe do MongoDB. Para **aprender** como alterar o nível de log do registrador do Logback, veja o **exemplo** na seção Configurar seu registrador desta página.

Para obter mais informações sobre Logback, consulte o manual de Logback.

Para usar Log4j2, adicione as seguintes linhas ao arquivo build.sbt do seu projeto. Essas linhas incluem o artefato slf4j-api, o framework de log e a vinculação.

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"

Para testar sua configuração do Log4j2, adicione o seguinte código ao arquivo Main.scala do seu projeto. O código registra uma mensagem de erro. Depois de adicionar o código, use sbt run para executar seu aplicativo no terminal em vez do 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

Observação

Nível de registro padrão

O nível de log padrão do Log4j2 é ERROR. Isso significa que a execução de operações padrão no driver Scala do MongoDB não produzirá saída do Log4j2 sem configuração de nível de log. Para aprender como alterar o nível de log do logger Log4j2, consulte o exemplo na seção Configurar o logger desta página.

Para obter mais informações sobre o Log4j2, consulte o manual do Log4j2.

Para obter mais informações sobre SLF4J, consulte a documentação do SLF4J.

Configure seu registrador

Para configurar seu logger, você deve usar o sistema de configuração do framework de registro em log ao qual você se vinculou ao SLF4J.

Exemplo de configuração

Um nível de log especifica a urgência de uma mensagem para que o logger emita essa mensagem. O exemplo a seguir mostra como usar o sistema de configuração de cada framework de log para definir o nível de log como INFO. Selecione a aba Logback ou Log4j2 para ver o código correspondente para cada abordagem:

O Logback lê sua configuração de um arquivo chamado logback.xml em seu classpath. Este arquivo não existe por padrão, portanto, você deve criá-lo. Você pode colocar logback.xml em qualquer lugar do seu projeto Scala, desde que ele esteja acessível a partir do seu classpath.

O framework Logback define os seguintes níveis de log, listados do mais urgente para o menos urgente:

ERROR
WARN
INFO
DEBUG
TRACE

Para saber mais sobre o que cada nível de log significa, consulte Nível efetivo na documentação do Logback.

Insira o seguinte código no seu arquivo 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>

Para testar se a configuração do seu registrador foi bem-sucedida, execute o seguinte código usando o comando sbt run em vez do seu 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>

Para obter mais informações sobre como configurar o Logback, consulte o Manual do Logback.

Log4j2 lê sua configuração de um arquivo chamado log4j2.xml em seu classpath. Este arquivo não existe por padrão, portanto, você deve criá-lo. Você pode colocar log4j2.xml em qualquer lugar em seu projeto Scala, desde que ele esteja acessível a partir do seu classpath.

O framework Log4j2 define os seguintes níveis de log, listados do mais urgente para o menos urgente:

Fatal
ERROR
WARN
INFO
DEBUG
TRACE
TUDO

Para saber mais sobre o significado de cada nível de log, consulte Níveis de log personalizados na documentação do Log4j2.

Defina seu arquivo log4j2.xml para o seguinte:

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

Para testar se a configuração do seu registrador foi bem-sucedida, execute o seguinte código usando o comando sbt run em vez do seu 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>

Para obter mais informações sobre como configurar o Log4j2, consulte o guia de configuração do Log4j2 na documentação do Log4j2.

Nomes de registradores

Os frameworks de registro usam nomes de logger hierárquicos para organizar eventos de registro. Um logger é um ancestral de outro logger se seu nome seguido por um "." for um prefixo do nome do outro logger. Por exemplo, o logger grandparent é um ancestral do logger grandparent.parent, que é um ancestral do logger grandparent.parent.child.

O código a seguir cria um logger parent e um logger parent.child, no qual o logger parent é um ancestral do logger parent.child:

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

Uma hierarquia de logger é semelhante a uma hierarquia de classe em Scala: um logger herda as propriedades de seu logger ancestral e também pode definir as suas próprias.

O driver Scala inclui os seguintes nomes de registradores padrão:

org.mongodb.driver.authenticator: autenticação
org.mongodb.driver.client: MongoClient instância
org.mongodb.driver.cluster: Monitoramento de implantação do MongoDB
org.mongodb.driver.connectionconexões e pools de conexões
org.mongodb.driver.connection.tls: TLS/SSL
org.mongodb.driver.operation: operações, incluindo novas tentativas automáticas
org.mongodb.driver.protocol: Comandos e respostas trocados com implantações do MongoDB
org.mongodb.driver.uri: análise de connection string
org.mongodb.driver.management: Extensões de gerenciamento Java (JMX)

Exemplo de nome do registrador

O exemplo a seguir mostra como definir a configuração do registrador raiz como OFF e a configuração do registrador org.mongodb.driver.connection como INFO, para que o aplicativo registre apenas mensagens relacionadas à conexão a uma implantação do MongoDB.

Selecione a aba Logback ou Log4j2 para ver a configuração de exemplo e a saída do framework correspondente:

Insira o seguinte código no seu arquivo 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>

Para testar se a configuração do seu registrador foi bem-sucedida, execute o seguinte código usando o comando sbt run em vez do seu 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>

Para mais informações sobre como configurar o Logback, consulte o guia oficial de configuração do Logback.

Insira o seguinte código no seu arquivo 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>

Para testar se a configuração do seu registrador foi bem-sucedida, execute o seguinte código usando o comando sbt run em vez do seu 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>

Para obter mais informações sobre como configurar o Log4j2, consulte o guia de configuração oficial do Log4J2.

Configurações de registro do cliente

Você pode aplicar configurações de registro à sua instância do MongoClient utilizando os métodos applyToLoggerSettings() e applicationName().

A tabela a seguir descreve os métodos que você pode conectar às configurações do registrador para modificar o comportamento do registro:

Método	Descrição
`maxDocumentLength()`	Define o tamanho máximo do documento , em caracteres, de uma única mensagem de registro Padrão: `1000`

Exemplo de configurações de registro do cliente

O exemplo a seguir nomeia o aplicativo que envia solicitações e especifica 5000 caracteres como o comprimento máximo da mensagem de log. Execute o exemplo usando o comando sbt run em vez de sua 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
...

Para obter mais informações, consulte a documentação da API MongoClientSettings.Builder.

Voltar

Monitoramento

Fluxos de alterações