Menu Docs

Exploração madeireira

Neste guia, você pode aprender como configurar um registrador no driver Node.js O driver permite que você registre informações categorizadas nos seguintes níveis de gravidade:

  • emergency

  • alert

  • critical

  • error

  • warn

  • notice

  • info

  • debug

  • trace

  • off

A lista anterior é ordenada por nível de gravidade decrescente. A especificação de um nível de gravidade também registra todas as mensagens com níveis de gravidade mais altos. Por exemplo, definir o nível de registro como critical também resulta em mensagens de registro com níveis de gravidade emergency e alert.

Quanto menor o nível de gravidade especificado, mais informações o driver registra, o que pode impacto o desempenho do seu aplicação.

Você pode configurar o registro no driver Node.js sem alterações de código especificando variáveis de ambiente. Você também pode configurar o registro programaticamente especificando as opções do cliente no construtor MongoClient.

Observação

Como as cadeias de conexão geralmente são compartilhadas entre uma implantação de diferentes aplicativos que podem ter suporte de registro diferente, não recomendamos o uso de uma string de conexão para configurar o registro.

Você pode configurar o registro para diferentes componentes do driver especificando um nível de gravidade em uma ou mais das seguintes variáveis de ambiente:

  • MONGODB_LOG_ALL: especifica a gravidade padrão para quaisquer componentes não definidos

  • MONGODB_LOG_COMMAND: Registra todos os comandos enviados para o servidor

  • MONGODB_LOG_TOPOLOGY: Registra quaisquer alterações na topologia do cluster

  • MONGODB_LOG_SERVER_SELECTION: Registra o processo de seleção do servidor

  • MONGODB_LOG_CONNECTION: registra todos os eventos do pool de conexões

  • MONGODB_LOG_CLIENT: Registra todos os eventos do cliente

Se você não especificar nenhuma das variáveis de ambiente anteriores, o driver usará o valor de MONGODB_LOG_ALL que, se não for especificado, será implicitamente definido como off.

Dica

O registro no nível de comando é a opção de registro com maior desempenho devido à frequência com que os comandos são enviados ao servidor. Especifique esta opção somente se necessário para depurar seu aplicação.

O exemplo a seguir define o nível de registro para todos os componentes como debug, exceto para MONGODB_LOG_COMMAND:

export MONGODB_LOG_ALL="debug"
export MONGODB_LOG_COMMAND="off"

Você pode especificar se o driver registra como stderr ou stdout definindo a variável de ambiente MONGODB_LOG_PATH como "stderr" ou "stdout", conforme mostrado no exemplo a seguir:

export MONGODB_LOG_PATH="stderr"

Por padrão, o driver registra em stderr.

O driver stringifica documentos registrados usando EJSON, que limita strings a 1000 caracteres por padrão. Você pode especificar um comprimento máximo de documento para o seu registrador especificando a variável de ambiente MONGODB_LOG_MAX_DOCUMENT. Defina esta variável como 0 para não executar o truncamento.

O exemplo a seguir define o comprimento máximo do documento para 500 caracteres:

export MONGODB_LOG_MAX_DOCUMENT_LENGTH=500

Você pode configurar o registro programaticamente especificando opções de cliente no construtor MongoClient. Como as opções do cliente têm precedência sobre as variáveis de ambiente, especifique-as somente no cliente se não quiser mais que o driver responda às variáveis de ambiente.

Dica

Se seu aplicação depender do formato stdout ou stderr, recomendamos configurar o registro usando as opções do cliente para evitar conflitos com as variáveis de ambiente do usuário do aplicação .

Você pode especificar qual componente configurar o registro especificando uma ou mais das seguintes opções do cliente :

  • default: especifica a gravidade padrão para quaisquer componentes não definidos

  • command: Registra todos os comandos enviados para o servidor

  • topology: Registra quaisquer alterações na topologia do cluster

  • serverSelection: Registra o processo de seleção do servidor

  • connection: registra todos os eventos do pool de conexões

  • client: Registra todos os eventos do cliente

Para especificar um nível de registro para um componente, defina a opção mongodbLogComponentSeverities como um objeto que contém o componente e o nível de gravidade desejado. O exemplo a seguir define o nível de registro de todos os componentes como debug, exceto command:

const client = new MongoClient("<connection string>", {
mongodbLogComponentSeverities: {
default: "debug",
command: "off"
}
});

Você pode especificar se o driver registra como stderr ou stdout definindo a opção mongodbLogPath como "stderr" ou "stdout", conforme mostrado no exemplo a seguir:

const mongodbLogComponentSeverities = {
default: "debug"
};
const mongodbLogPath = "stdout";
const client = new MongoClient("<connection string>",
{ mongodbLogComponentSeverities, mongodbLogPath }
);

Por padrão, o driver registra em stderr.

Você também pode especificar um destino de registro personalizado. O exemplo a seguir cria um destino de registro personalizado:

import fs from 'node:fs/promises';
import util from 'node:util';
const mongodbLogPath = {
file: await fs.open(`./server-${+new Date()}.logs`, 'w'),
async write(log) {
try {
await this.file?.appendFile(util.inspect(log) + '\n');
} catch (fileError) {
console.log('cannot log anymore', fileError);
this.file = null;
}
}
}
const client = new MongoClient("<connection string>", { mongodbLogPath });

Se sua função gerar um erro na operação de gravação, o erro lançado encerrará o registrador. Por isso, recomendamos que você lide com erros tornando a função de gravação um no-op em vez de lançar um erro, como mostrado no exemplo anterior.

Observação

O registro pode esgotar o espaço em disco se o sistema de rotação de registros adequado não estiver implementado. Recomendamos que você conecte sua função de escrita personalizada a uma biblioteca de registro popular.

O driver stringifica documentos registrados usando EJSON, que limita strings a 1000 caracteres por padrão. Você pode especificar um tamanho máximo de documento para o seu registrador especificando a opção mongodbLogMaxDocumentLength. Defina esta opção como 0 para não executar nenhum truncamento.

O exemplo a seguir define o comprimento máximo do documento para 500 caracteres:

const mongodbLogComponentSeverities = {
default: "debug"
};
const mongodbLogLength = 500;
const client = new MongoClient("<connection string>", {
mongodbLogComponentSeverities,
mongodbLogLength
});

Para obter mais informações sobre o monitoramento com o driver Node.js , consulte os seguintes guias de monitoramento:

Para saber mais sobre qualquer uma das opções ou tipos discutidos neste guia, consulte a seguinte documentação da API: