Exploração madeireira

Nesta página

Visão geral

Habilitar registros
Configurar um registrador
Componentes de registro e níveis de gravidade
Exemplo
Usar um registrador personalizado
Exemplo
Integrar registradores de terceiros
Exemplo
Informações adicionais
Documentação da API

Visão geral

Neste guia, você pode aprender como usar o driver para configurar o registro para seu aplicativo. O objetivo do registro é registrar eventos do driver.

Um logger registra mensagens em um nível de gravidade ou verbosidade que você pode especificar. Ao habilitar um logger em seu aplicativo, você pode receber informações sobre as atividades do seu aplicativo em um nível alto, um nível detalhado ou em algum lugar intermediário.

Dica

Para saber mais sobre os níveis de gravidade de registro, consulte o verbete da Wikipedia sobre o padrão do Syslog para registro de mensagens.

Habilitar registros

Para configurar um registrador em sua instância do Client , chame o método SetLoggerOptions() ao criar seu objeto ClientOptions . O método SetLoggerOptions() usa um tipo LoggerOptions como parâmetro. Defina este tipo de LoggerOptions para configurar o registrador para seu aplicativo.

O seguinte código mostra como criar um cliente com o registro habilitado:

loggerOptions := options.
     Logger().
     SetComponentLevel(options.LogComponentCommand, options.LogLevelDebug)
clientOptions := options.
     Client().
     ApplyURI(uri).
     SetLoggerOptions(loggerOptions)
client, err := mongo.Connect(clientOptions)

Configurar um registrador

Para criar um objeto LoggerOptions , chame o método options.Logger() . A tabela a seguir descreve como definir propriedades em um tipo LoggerOptions para configurar seu registrador. A primeira coluna lista as propriedades LoggerOptions , a segunda coluna descreve as propriedades e a terceira coluna lista o método de preparação e os parâmetros correspondentes para cada propriedade:

Propriedade	Descrição	Método de preparação
`ComponentLevels` Type: `map[LogComponent]LogLevel`	A mapping of components to log severity levels. The driver uses the `LogLevel` for each `LogComponent` to determine if the log message is generated. To learn more about the `LogComponent` and `LogLevel` types, see the Log Components and Severity Levels section of this guide.	`SetComponentLevel()` Parameters: `LogComponent`, `LogLevel`
`Sink` Type: `LogSink`	The logging interface that the driver uses to log messages. The `LogSink` type is an interface that you can implement to provide a custom sink or integrate a third-party logger for the driver's logs. If you don't set this property, the driver uses the standard logging library. To learn more, see the Use a Custom Logger and Integrate Third-Party Loggers sections of this guide.	`SetSink()` Parameter: `LogSink`
`MaxDocumentLength` Type: `uint` Default: `1000`	The maximum length in bytes of each log message that the driver emits. If the message is larger than this value, the driver truncates it and appends ellipses to the partial log message.	`SetMaxDocumentLength()` Parameter: `uint`

Dica

Gravar registros em um arquivo específico

Por padrão, o registrador padrão registra mensagens no seu console (stderr). Você pode especificar um destino de registro configurando a variável de ambiente do MONGODB_LOG_PATH para stdout ou um caminho de arquivo.

Componentes de registro e níveis de gravidade

Para especificar os componentes que o driver registra, defina o tipo LogComponent . A tabela a seguir descreve especificações integradas para LogComponent:

Contexto	Descrição	Valor de enumeração
`LogComponentAll`	Habilita o registro de todos os componentes	`0`
`LogComponentCommand`	Habilita o registro do monitor de comando	`1`
`LogComponentTopology`	Habilita o registro de topologia	`2`
`LogComponentServerSelection`	Habilita o registro de seleção de servidor	`3`
`LogComponentConnection`	Habilita o registro de serviços de conexão	`4`

Você pode especificar o componente de registro usando o nome da configuração ou seu valor de enumeração. O código a seguir mostra maneiras equivalentes de habilitar o monitoramento de comandos:

// Using named value
comp := options.LogComponentCommand
// Using enumeration
comp := options.LogComponent(1)

Para especificar o nível de gravidade do registro, defina o tipo LogLevel. O seguinte código mostra como habilitar o registro no nível LevelDebug:

lvl := options.LogLevelDebug

Importante

Atualmente, o driver Go emite apenas LevelDebug mensagens de nível , mas é compatível com outras especificações para LogLevel. Para saber mais, consulte o LogLevel Documentação da API.

Exemplo

Este exemplo mostra como configurar o registrador padrão com as seguintes especificações:

O comprimento máximo do documento é de 25 bytes.
O componente de registro é LogComponentCommand.
O nível de severidade do registro é LevelDebug.

loggerOptions := options.
	Logger().
	SetMaxDocumentLength(25).
	SetComponentLevel(options.LogComponentCommand, options.LogLevelDebug)
// Creates options that include the logger specification
clientOptions := options.
	Client().
	ApplyURI(uri).
	SetLoggerOptions(loggerOptions)

O seguinte código executa uma operação de inserção, que gera mensagens de registro:

type Item struct {
	Name string
}
coll := client.Database("db").Collection("testColl")
_, err = coll.InsertOne(context.TODO(), Item{Name: "grapefruit"})

{"command":"{\"insert\": \"testColl\",\"or...","commandName":"insert","databaseName":"db","driverConnectionId":1,"message":"Command started","operationId":0,"requestId":13,"serverConnectionId":97377,"serverHost":"...","serverPort":27017,"timestamp":...}
{"commandName":"insert","driverConnectionId":1,"durationMS":19,"message":"Command succeeded","operationId":0,"reply":"{\"n\": {\"$numberInt\":\"1\"},...","requestId":13,"serverConnectionId":97377,"serverHost":"...","serverPort":27017,"timestamp":...}

Usar um registrador personalizado

Se a biblioteca de registro padrão não atender às suas necessidades, você poderá implementar um registrador personalizado. Ao personalizar a configuração de registro, você tem mais controle sobre o conteúdo, o formato e a frequência das mensagens de registro.

Para usar um registrador personalizado, defina uma estrutura de registrador e implemente os métodos Info() e Error() para o struct. Em seguida, defina o registrador como o LogSink para o Client chamando o método SetSink() em sua instância LoggerOptions.

Exemplo

Este exemplo demonstra como definir e implementar um registrador customizado.

Defina a `CustomLogger` estrutura .

type CustomLogger struct {
	io.Writer
	mu sync.Mutex
}

Observação

O exemplo de código anterior usa um tipo Mutex na estrutura CustomLogger para garantir gravações atômicas e evitar condições de corrida. Definir um Mutex torna seu logger seguro para uso simultâneo por vários goroutines.

Implemente os `Info()` `Error()` métodos e com formatação de mensagem de registro personalizada.

func (logger *CustomLogger) Info(level int, msg string, _ ...interface{}) {
	logger.mu.Lock()
	defer logger.mu.Unlock()
	if options.LogLevel(level+1) == options.LogLevelDebug {
		fmt.Fprintf(logger, "level: %d DEBUG, message: %s\n", level, msg)
	} else {
		fmt.Fprintf(logger, "level: %d INFO, message: %s\n", level, msg)
	}
}
func (logger *CustomLogger) Error(err error, msg string, _ ...interface{}) {
	logger.mu.Lock()
	defer logger.mu.Unlock()
	fmt.Fprintf(logger, "error: %v, message: %s\n", err, msg)
}

Atribua um `Writer` ao seu registrador e defina-o como `Sink` para `Client` seu.

Neste exemplo, o logger registra comandos e eventos de conexão no nível LevelDebug :

buf := bytes.NewBuffer(nil)
sink := &CustomLogger{Writer: buf}
loggerOptions := options.
	Logger().
	SetSink(sink).
	SetComponentLevel(options.LogComponentCommand, options.LogLevelDebug).
	SetComponentLevel(options.LogComponentConnection, options.LogLevelDebug)
// Creates options that include the logger specification
clientOptions := options.
	Client().
	ApplyURI(uri).
	SetLoggerOptions(loggerOptions)

Realizar uma operação.

O seguinte código executa uma operação de inserção, que gera mensagens de registro:

type Item struct {
	Name string
}
coll := client.Database("db").Collection("testColl")
_, err = coll.InsertOne(context.TODO(), Item{Name: "grapefruit"})

level: 1 DEBUG, message: Connection pool created
level: 1 DEBUG, message: Connection pool ready
level: 1 DEBUG, message: Connection pool created
level: 1 DEBUG, message: Connection pool ready
level: 1 DEBUG, message: Connection pool created
level: 1 DEBUG, message: Connection pool ready
level: 1 DEBUG, message: Connection checkout started
level: 1 DEBUG, message: Connection created
level: 1 DEBUG, message: Connection ready
level: 1 DEBUG, message: Connection checked out
level: 1 DEBUG, message: Command started
level: 1 DEBUG, message: Command succeeded
level: 1 DEBUG, message: Connection checked in

Integrar registradores de terceiros

Existem muitos pacotes de registro de terceiros disponíveis no Go. Para usar um registrador de terceiros em seu aplicativo, crie um registrador e atribua-o como coletor na sua instância do LoggerOptions .

Exemplo

Este exemplo demonstra como integrar o logrus, um pacote de registro de terceiros, em seu aplicativo.

Instale os pacotes necessários.

Execute os seguintes comandos do go get no seu terminal para baixar os pacotes do logrus exigidos para este exemplo:

go get github.com/bombsimon/logrusr/v4
go get github.com/sirupsen/logrus

Defina o `logrus` registrador .

O seguinte código cria um registrador logrus com estas especificações:

O logger registra mensagens no console.
O registrador registra mensagens no nível DebugLevel .
O registrador formata mensagens usando o formatador JSONFormatter .

myLogger := &logrus.Logger{
	Out:   os.Stderr,
	Level: logrus.DebugLevel,
	Formatter: &logrus.JSONFormatter{
		TimestampFormat: "2006-01-02 15:04:05",
		PrettyPrint:     true,
	},
}

Defina o registrador como `Sink` para `Client` seu.

No exemplo de código a seguir, o logger está configurado para registrar comandos no nível LevelDebug .

sink := logrusr.New(myLogger).GetSink()
// Sets options when configuring the logrus logger
loggerOptions := options.
	Logger().
	SetSink(sink).
	SetComponentLevel(options.LogComponentCommand, options.LogLevelDebug)
// Creates options that include the logger specification
clientOptions := options.
	Client().
	ApplyURI(uri).
	SetLoggerOptions(loggerOptions)

Execute operações.

O seguinte código executa algumas operações CRUD, que geram mensagens de registro:

type Item struct {
	Name string
}
coll := client.Database("db").Collection("testColl")
docs := []interface{}{
	Item{Name: "starfruit"},
	Item{Name: "kiwi"},
	Item{Name: "cantaloupe"},
}
_, err = coll.InsertMany(context.TODO(), docs)
if err != nil {
	panic(err)
}
_, err = coll.DeleteOne(context.TODO(), Item{Name: "kiwi"})
if err != nil {
	panic(err)
}

{
  "command": "{\"insert\": \"testColl\", ...}",
  "commandName": "insert",
  "databaseName": "db",
  ...
  "level": "debug",
  "message": "Command started",
  "msg": "Command started",
  ...
  "time": "2023-07-06 10:23:42"
}
{
  "commandName": "insert",
  ...
  "level": "debug",
  "message": "Command succeeded",
  "msg": "Command succeeded",
  ...
  "time": "2023-07-06 10:23:42"
}
{
  "command": "{\"delete\": \"testColl\", ...}",
  "commandName": "delete",
  "databaseName": "db",
  ...
  "level": "debug",
  "message": "Command started",
  "msg": "Command started",
  ...
  "time": "2023-07-06 10:23:42"
}
{
  "commandName": "delete",
  ...
  "level": "debug",
  "message": "Command succeeded",
  "msg": "Command succeeded",
  ...
  "time": "2023-07-06 10:23:42"
}

Dica

pacote de registro

Você pode encontrar mais informações sobre pacote de registro de terceiros em seus respectivos repositórios do Github:

Para ver exemplos de código completos que integram esses registradores, consulte os testes de registro no repositório do Github do driver Go.

Informações adicionais

Para obter mais informações sobre como configurar as opções do cliente, consulte o Guia de conexão.

Dica

Monitoramento

Além do registro, você pode habilitar a seleção de servidor e o monitoramento da topologia em seu aplicativo. Para saber mais, consulte o guia Noções básicas de monitoramento .

Documentação da API

Para saber mais sobre qualquer um dos tipos ou métodos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Transações

Execute um comando

Visão geral

Dica

Habilitar registros

Configurar um registrador

Dica

Gravar registros em um arquivo específico

Componentes de registro e níveis de gravidade

Importante

Exemplo

Usar um registrador personalizado

Exemplo

Defina a CustomLogger estrutura .

Observação

Implemente os Info() Error() métodos e com formatação de mensagem de registro personalizada.

Atribua um Writer ao seu registrador e defina-o como Sink para Client seu.

Realizar uma operação.

Integrar registradores de terceiros

Exemplo

Instale os pacotes necessários.

Defina o logrus registrador .

Defina o registrador como Sink para Client seu.

Execute operações.

Dica

pacote de registro

Informações adicionais

Dica

Monitoramento

Documentação da API

Defina a `CustomLogger` estrutura .

Implemente os `Info()` `Error()` métodos e com formatação de mensagem de registro personalizada.

Atribua um `Writer` ao seu registrador e defina-o como `Sink` para `Client` seu.

Defina o `logrus` registrador .

Defina o registrador como `Sink` para `Client` seu.