Exploração madeireira
Nesta página
Visão geral
Neste guia, você pode aprender como definir e configurar um logger no MongoDB Kotlin driver.
Você vai aprender como:
Definir um logger usando o Simple Logging Facade For Java (SLF4J)
Configurar o nível de registro do seu logger
Este guia mostra como gravar eventos no driver. Se você quiser aprender como usar informações sobre a atividade do driver no código, considere ler nosso guia sobre monitoramento.
Configurar um registrador
Esta seção fornece informações básicas sobre as dependências necessárias para definir um criador de logs e fornece um exemplo de definição do criador de logs.
Plano de fundo
O driver do MongoDB Kotlin usa o Simple Logging Facade For Java (SLF4J). O SLF4J permite que você especifique sua estrutura de registro preferida no momento da implementação. Para obter mais informações sobre o SLF4J, , consulte a4documentação do SLF J.
Configurar um registrador é opcional. Quando você inicia seu aplicativo, o driver MongoDB Kotlin procura o artefato slf4j-api em seu caminho de classe. Se o driver não conseguir localizar o artefato slf4j-api , ele registrará o seguinte aviso com java.util.logging e desabilitará todos os registros adicionais:
WARNING: SLF4J not found on the classpath. Logging is disabled for the 'org.mongodb.driver' component
Para definir um logger, você deve incluir o seguinte em seu projeto.
O artefato
slf4j-apiUma estrutura de registro
Uma vinculação
Observação
Para as estruturas de registro mais populares, há frequentemente um único artefato de ligação que lista o slf4j-api e a estrutura de registro como dependências. Isso significa que você pode configurar um registrador adicionando um artefato à lista de dependência do seu projeto. Você verá isso no exemplo abaixo.
Um vínculo é um pedaço de código que conecta o artefato do slf4j-api a uma estrutura de registro. O exemplo a seguir mostra como vincular o artefato slf4j-api a duas estruturas de registro mais populares, Log4j2 e Logback.
Exemplo - Configuração
Este exemplo mostra como configurar seu registrador. Clique na guia correspondente à estrutura de registro que você gostaria de usar em seu projeto.
Dica
Versões de dependência
As seguintes versões listadas são ilustrativas em vez de uma fonte da verdade. Você deve verificar a documentação oficial do SLF4J e sua estrutura de registro de escolha para obter informações de versão atualizadas garantidas.
Selecione a ferramenta de construção que você está utilizando em 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.kts :
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 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}}}
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, veja o exemplo nesta página na seção Como configurar seu registrador.
Para obter mais informações sobre Logback, consulte o manual de Logback.
Selecione a ferramenta de construção que você está utilizando em 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.kts.
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:
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
Observação
Nível de registro padrão
O nível de registro padrão do Registro4J2 é ERRO. Isso significa que a execução de operações padrão no driver Kotlin do MongoDB não produzirá saída do Registro4J2 sem configuração. Para saber como alterar o nível de registro do registrador do Log4J2 , veja o exemplo nesta página na seção Como configurar seu registrador.
Para obter mais informações sobre o registro4j2, consulte o manual do registro j .42
Configure seu registrador
Para configurar seu registrador, você deve usar o sistema de configuração da estrutura de registro vinculada ao SLF4J.
No exemplo a seguir, mostramos como você pode usar o sistema de configuração da estrutura de registro para definir o nível de log do logger.
O nível de log de um logger especifica um limite inferior para determinar a urgência necessária para que o logger emita essa mensagem.
Exemplo - Configurar
Este exemplo mostra como configurar o nível de log do seu logger para INFO. Selecione a aba correspondente a estrutura de registro que você está usando no projeto.
Especifique as configurações do Logback em um arquivo chamado logback.xml. Seu arquivo logback.xml não precisa estar em um local específico, mas deve estar acessível a partir do seu classpath.
A estrutura Logback define os seguintes níveis de registro. A seguir, listamos os níveis de registro, ordenados do mais urgente para o menos urgente:
ERROR
WARN
INFO
DEBUG
TRACE
Configure 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 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>
Para obter mais informações sobre como configurar o Logback, consulte o Manual do Logback.
Especifique as configurações do Log4j2 em um arquivo chamado log4j2.xml. Seu arquivo log4j2.xml não precisa estar em um local específico, mas deve estar acessível a partir do seu classpath.
A estrutura Log4j2 define os seguintes níveis de registro. A seguir, listamos os níveis de registro, ordenados do mais urgente para o menos urgente:
Fatal
ERROR
WARN
INFO
DEBUG
TRACE
TUDO
Configure seu arquivo log4j2.xml para o seguinte.
<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 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>
Para mais informações sobre como configurar o Log4j2, consulte o guia oficial de configuração do Log4j .2
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".
Como exemplo prático, veja como uma hierarquia de loggers se apresenta no código.
import org.slf4j.LoggerFactory
val loggerParent = LoggerFactory.getLogger("parent") val loggerChild = LoggerFactory.getLogger("parent.child")
Um logger herda as propriedades de seu logger ancestral e pode definir as suas próprias. Você pode pensar nisso como algo semelhante à herança de classes em Kotlin.
O driver Kotlin do MongoDB define os seguintes nomes de registradores para organizar diferentes eventos de registro no driver. Aqui estão os nomes dos registradores definidos no driver e os eventos de registro aos quais eles correspondem:
org.mongodb.driver.authenticator: autenticaçãoorg.mongodb.driver.client: eventos relacionados a instâncias deMongoClientorg.mongodb.driver.cluster: monitoramento dos servidores MongoDBorg.mongodb.driver.connectionconexões e pools de conexõesorg.mongodb.driver.connection.tls: TLS/SSLorg.mongodb.driver.operation: operações, incluindo registro relacionado a novas tentativas automáticasorg.mongodb.driver.protocol: comandos enviados e respostas recebidas do MongoDB Serverorg.mongodb.driver.uri: análise de connection stringorg.mongodb.driver.management: JMX (Extensões de gerenciamento Java)
Exemplo - Nomes
Este exemplo mostra como alterar o nível de registro de um registrador de driver específico. Definimos o registrador raiz como DESATIVADO e o registrador org.mongodb.driver.connection como INFO. Isso fará com que o aplicativo registre somente mensagens relacionadas à conexão com uma instância MongoDB.
Selecione a aba correspondente ao framework de registro que você está usando no projeto.
Configure 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="INFO" 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 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>
Para mais informações sobre como configurar o Logback, consulte o guia oficial de configuração do Logback.
Configure seu arquivo log4j2.xml para o seguinte.
<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 está correta, execute o seguinte código.
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>
Para obter mais informações sobre como configurar o Log4j2, consulte o guia oficial4de2 configuração do Log J .