Registrar eventos de driver

Visão geral

Neste guia, você pode aprender como definir e configurar um logger no driver Kotlin Sync.

Este guia mostra como gravar eventos no driver. Se quiser aprender como usar informações sobre a atividade do driver no código, consulte o guia Monitorar eventos de aplicativos.

Configurar um registrador

O driver Kotlin Sync usa Simple Logging Facade For Java (SLF4J) para permitir que você especifique sua estrutura de registro de escolha. Para obter mais informações sobre o SLF4J, consulte a documentação do SLF4J.

Configurar um registrador é opcional. Para definir um logger, você deve incluir o seguinte em seu projeto:

O artefato slf4j-api no seu caminho de classe
Uma estrutura de registro
Uma vinculação que conecta o artefato slf4j-api a uma estrutura de registro

Se o driver não conseguir localizar o artefato slf4j-api em seu caminho de classe, ele emitirá o seguinte aviso e desabilitará todos os registros adicionais:

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

Exemplo de configuração do registrador

O exemplo a seguir mostra como configurar um registrador. Selecione a aba Logback ou Log4j2 para ver a sintaxe correspondente :

Selecione a aba Maven ou Gradle para saber como configurar o Logback com a ferramenta de gerenciamento de dependência do seu projeto:

Adicione a seguinte dependência ao seu arquivo pom.xml.

<dependencies>
  <dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.11</version>
  </dependency>
</dependencies>

Adicione a seguinte dependência ao seu arquivo build.gradle.

dependencies {
   implementation 'ch.qos.logback:logback-classic:1.2.11'
}

Depois de incluir a dependência anterior, conecte-se à sua instância do MongoDB e recupere um documento com o seguinte código:

val mongoClient = MongoClient.create(<connection uri>);
val database = mongoClient.getDatabase(<database>);
val collection = database.getCollection<Document>(<collection>);
collection.find().first();

O código anterior produzirá uma mensagem semelhante à seguinte:

...
12:14:55.833 [main] DEBUG org.mongodb.driver.connection - Checkout started for connection to <MongoDB hostname>
12:14:55.834 [main] DEBUG org.mongodb.driver.connection - Connection created: address=<MongoDB hostname>, driver-generated ID=3
12:14:55.836 [main] DEBUG org.mongodb.driver.connection - Connection ready: address=<MongoDB hostname>, driver-generated ID=3, established in=4 ms
12:14:55.843 [main] DEBUG org.mongodb.driver.connection - Connection checked out: address=<MongoDB hostname>, driver-generated ID=3, duration=9 ms

Observação

Nível de registro padrão

O nível de log padrão do Logback é DEBUG. Para saber como alterar o nível de registro do registrador do Logback, consulte a seção Configurar nível de registro desta página.

Selecione a aba Maven ou Gradle para saber como configurar o Log4j2 com a ferramenta de gerenciamento de dependência do seu projeto.

Adicione a seguinte dependência ao seu arquivo pom.xml.

<dependencies>
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-slf4j-impl</artifactId>
    <version>2.17.1</version>
  </dependency>
</dependencies>

Adicione a seguinte dependência ao seu arquivo build.gradle.

dependencies {
  implementation 'org.apache.logging.log4j:log4j-slf4j-impl:2.17.1'
}

Depois de incluir a dependência anterior, registre um erro usando o seguinte código:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
val logger = LoggerFactory.getLogger("MyApp");
logger.error("Logging an Error");

O código anterior produzirá uma mensagem semelhante à seguinte:

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

Observação

Nível de registro padrão

O nível de registro padrão do Log4J2 é ERRO. Isso significa que executar operações padrão no driver Kotlin Sync não produzirá saídas do Log4J2 sem configuração. Para saber como alterar seu nível de registro do registrador4J2, consulte a seção Configurar nível de registro desta página.

Configurar nível de registro

Você pode configurar o nível de registro do seu registrador usando o sistema de configuração da estrutura de registro vinculada a SLF4J. O nível de log especifica um limite inferior para determinar a urgência necessária para que o logger emita essa mensagem.

Exemplo de configuração do registrador

O exemplo a seguir configura o nível de registro para INFO. Selecione a aba Logback ou Log4j2 para ver a sintaxe correspondente:

Especifique as configurações do Logback em um arquivo chamado logback.xml. Você deve conseguir acessar este arquivo a partir do seu classpath.

A estrutura Logback define os seguintes níveis de registro ordenados do mais urgente para o menos urgente:

ERROR
WARN
INFO
DEBUG
TRACE

Defina seu arquivo logback.xml para o seguinte:

<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 está correta, execute o seguinte código:

val mongoClient = MongoClient.create(<connection uri>);
val database = mongoClient.getDatabase(<database>);
val collection = database.getCollection<Document>(<collection>);
collection.find().first();

Este código produz um resultado semelhante ao seguinte:

...
317  [main] INFO  org.mongodb.driver.client - MongoClient with metadata {"driver": {"name": "<driver-name>", "version": "<driver-version>"}, "os": {"type": "<os-type>", "name": "<os-name>", "architecture": "<architecture>", "version": "<os-version>"}, "platform": "<platform-info>"} created with settings <MongoClientSettings>
345  [cluster-ClusterId{value='<cluster-id>', description='null'}-<MongoDB hostname>] INFO  org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=<MongoDB hostname>, type=<server-type>, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=<max-wire-version>, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=<round-trip-nanos>, minRoundTripTimeNanos=<min-round-trip-nanos}

Especifique as configurações do Log4j2 em um arquivo chamado log4j2.xml. Você deve conseguir acessar este arquivo a partir do seu classpath.

A estrutura do Log4j2 define os seguintes níveis de registro, ordenados do mais urgente para o menos urgente:

FATAL
ERROR
WARN
INFO
DEBUG
TRACE
ALL

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 está correta, execute o seguinte código:

val mongoClient = MongoClient.create(<connection uri>);
val database = mongoClient.getDatabase(<database>);
val collection = database.getCollection<Document>(<collection>);
collection.find().first();

Este código produz um resultado semelhante ao seguinte:

...
21:19:25.696 [main] INFO  org.mongodb.driver.client - MongoClient with metadata {"driver": {"name": "<driver-name>", "version": "<driver-version>"}, "os": {"type": "<os-type>", "name": "<os-name>", "architecture": "<architecture>", "version": "<os-version>"}, "platform": "<platform-info>"} created with settings <MongoClientSettings>
21:19:25.710 [cluster-ClusterId{value='<cluster-id>', description='null'}-<MongoDB hostname>] INFO  org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=<MongoDB hostname>, type=<server-type>, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=<max-wire-version>, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=<round-trip-nanos>, minRoundTripTimeNanos=<min-round-trip-nanos}

Nomes de registradores

Seu logger usa nomes de loggers para ajudar a organizar diferentes eventos de logger. Os nomes de logger são strings que formam uma hierarquia. Um logger é um ancestral de outro logger se seu nome seguido por um "." for um prefixo do nome do outro logger. Por exemplo, "grandparent" é um ancestral de "grandparent.parent", que é um ancestral de "grandparent.parent.child". Um logger herda as propriedades de seu logger ancestral e também pode definir suas próprias propriedades.

O driver Kotlin Sync define os seguintes nomes de registradores para organizar diferentes eventos de registro:

Nome do registrador	Descrição
`org.mongodb.driver.authenticator`	Registra eventos de autenticação
`org.mongodb.driver.client`	Registra eventos relacionados a instâncias MongoClient
`org.mongodb.driver.cluster`	Registra eventos relacionados ao monitoramento de sistemas MongoDB
`org.mongodb.driver.connection`	Conexões de registro e pools de conexões
`org.mongodb.driver.connection.tls`	Registra eventos TLS
`org.mongodb.driver.operation`	Operações de registro, incluindo registros relacionados a novas tentativas automáticas
`org.mongodb.driver.protocol`	Registra comandos enviados e respostas recebidas de implementações MongoDB
`org.mongodb.driver.uri`	Registra eventos de análise de string de conexão
`org.mongodb.driver.management`	Registra eventos de extensões de gerenciamento Java (JMX)

Exemplo de nome do registrador

O exemplo a seguir desabilita o registrador raiz e define o nível de registro do registrador org.mongodb.driver.connection como DEBUG. Isso fará com que o driver registre mensagens somente relacionadas a conexões e pools de conexões no nível DEBUG ou superior. Selecione a aba Logback ou Log4j2 para ver a sintaxe correspondente:

Defina seu arquivo logback.xml para o seguinte:

<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="DEBUG" additivity="true"/>
   <root level="OFF">
      <appender-ref ref="CONSOLE" />
   </root>
</configuration>

Para testar se a configuração do seu registrador está correta, execute o seguinte código.

val mongoClient = MongoClient.create(<connection uri>);
val database = mongoClient.getDatabase(<database>);
val collection = database.getCollection<Document>(<collection>);
collection.find().first();

Este código produz um resultado semelhante ao seguinte.

...
255  [main] DEBUG org.mongodb.driver.connection - Connection pool created for <MongoDB hostname> using options <connection-pool-options>
301  [cluster-ClusterId{value='<cluster-id>', description='null'}-<MongoDB hostname>] DEBUG org.mongodb.driver.connection - Connection pool ready for <MongoDB hostname>
321  [main] DEBUG org.mongodb.driver.connection - Checkout started for connection to <MongoDB hostname>
323  [main] DEBUG org.mongodb.driver.connection - Connection created: address=<MongoDB hostname>, driver-generated ID=3
335  [main] DEBUG org.mongodb.driver.connection - Connection ready: address=<MongoDB hostname>, driver-generated ID=3, established in=<connect-duration> ms
336  [main] DEBUG org.mongodb.driver.connection - Connection checked out: address=<MongoDB hostname>, driver-generated ID=3, duration=<checkout-duration> ms
363  [main] DEBUG org.mongodb.driver.connection - Connection checked in: address=<MongoDB hostname>, driver-generated ID=3

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>
      <Logger name="org.mongodb.driver.connection" level="DEBUG"/>
      <Root level="OFF">
            <AppenderRef ref="Console"/>
      </Root>
   </Loggers>
</Configuration>

Para testar se a configuração do seu registrador está correta, execute o seguinte código.

val mongoClient = MongoClient.create(<connection uri>);
val database = mongoClient.getDatabase(<database>);
val collection = database.getCollection<Document>(<collection>);
collection.find().first();

Este código produz um resultado semelhante ao seguinte:

...
21:27:17.035  [main] DEBUG org.mongodb.driver.connection - Connection pool created for <MongoDB hostname> using options <connection-pool-options>
21:27:17.058  [cluster-ClusterId{value='<cluster-id>', description='null'}-<MongoDB hostname>] DEBUG org.mongodb.driver.connection - Connection pool ready for <MongoDB hostname>
21:27:17.064  [main] DEBUG org.mongodb.driver.connection - Checkout started for connection to <MongoDB hostname>
21:27:17.069  [main] DEBUG org.mongodb.driver.connection - Connection created: address=<MongoDB hostname>, driver-generated ID=3
21:27:17.075  [main] DEBUG org.mongodb.driver.connection - Connection ready: address=<MongoDB hostname>, driver-generated ID=3, established in=<connect-duration> ms
21:27:17.075  [main] DEBUG org.mongodb.driver.connection - Connection checked out: address=<MongoDB hostname>, driver-generated ID=3, duration=<checkout-duration> ms
21:27:17.086  [main] DEBUG org.mongodb.driver.connection - Connection checked in: address=<MongoDB hostname>, driver-generated ID=3

Informações adicionais

Para saber mais sobre os recursos de registro do MongoDB, consulte Mensagens de registro no manual do MongoDB Server.

Para obter informações completas sobre as estruturas de registro discutidas neste guia, consulte a seguinte documentação externa:

Voltar

Registro e monitoramento

Monitoramento