Logs do mongot e FTDC

Destinos de log

Onde mongot grava logs depende do seu tipo de implantação:

Verbosidade do registro

A opção logging.verbosity especificada no arquivo de configuração mongot aceita os seguintes níveis:

mongot lê o detalhamento na inicialização. Para alterá-lo, reinicie mongot.

Formato de registro

mongot emite logs JSON estruturados, com um objeto JSON por linha. Este formato alinha os logs mongot com o formato de log estruturado mongod.

Cada entrada de log mongot inclui campos como t, s, svc, ctx, n, msg e attr opcional. Por exemplo:

{"t":"2026-06-22T14:03:41.582+0000","s":"INFO","svc":"MONGOT","ctx":"indexing-lifecycle-0","n":"com.xgen.mongot.replication.mongodb.initialsync.BufferlessInitialSyncManager","msg":"Beginning initial sync.","attr":{"startTime":"2026-06-22T14:03:41.582+0000","indexGenerationId":"6857f3b6e4b04c2a9d1f0a12-f6-u0-a0"}}

Cada objeto de log contém os seguintes campos:

O que procurar na inicialização

Uma inicialização mongot saudável emite uma sequência de eventos identificáveis no detalhamento INFO padrão. Procure esses eventos em vez de strings literais específicas:

Linhas informativas adicionais existem na inicialização. Os eventos anteriores são os que suportam a verificação.

Os seguintes indicadores mostram que a inicialização não foi concluída:

O que procurar em estado estacionário

Em estado estável, os logs saudáveis são principalmente silenciosos. Espere mensagens informativas periódicas de tarefas em segundo plano, como fusões e ticks FTDC, e entradas WARN ocasionais para comportamento transitório do cliente. Não espere entradas ERROR ou Exception.

Os seguintes padrões de log de estado estável exigem atenção:

Para mapear esses padrões para procedimentos de remediação, consulte Solucionar problemas de implantações mongot autogerenciadas.

Pesquisar logs

Como o log mongot é JSON, jq é a ferramenta mais natural para pesquisá-lo. Os exemplos a seguir mostram queries comuns:

# All errors
jq 'select(.s == "ERROR")' mongot.log
# Initial sync activity
jq 'select(.msg | startswith("Beginning initial sync"))' mongot.log
# Replication or sync from specific loggers
jq 'select(.n | test("BufferlessInitialSyncManager|InitialSyncQueue|InitialSyncManager"))' mongot.log
# Resync events
jq 'select(.msg | test("requiring resync|InitialSyncException|SteadyStateException"))' mongot.log
# Connection-pool churn
jq 'select(.msg | test("Dropping all pooled connections|ShutdownInProgress"))' mongot.log
# Embedding-related entries
jq 'select(.msg | test("embedding|voyage"; "i"))' mongot.log

Como o JSON é de linha única, grep também funciona:

grep '"s":"ERROR"' mongot.log
grep '"msg":"Beginning initial sync\.' mongot.log
grep -E '"n":"[^"]*(BufferlessInitialSyncManager|InitialSyncQueue)' mongot.log

Para plataformas de log como Elasticsearch, Splunk e DataDog, filtre em s:ERROR, n:<logger> ou attr.<key> em vez de texto. Os campos são estáveis, mas os padrões de texto completo podem mudar entre as versões.

Para implantações que executam várias instâncias mongot, inclua o identificador da instância nas tags de encaminhamento de log para que você possa filtrar por instância.

Dicas de análise de log

Tenha em mente os seguintes pontos ao analisar os logs mongot:

• Os logs nem sempre incluem o nome do índice na mensagem. Para falhas de indexação, a linha de log relevante pode aparecer várias linhas antes ou depois no mesmo contexto de logger. Capture uma janela, não uma única linha.

• Faça referência cruzada aos logs mongot com os logs mongod na mesma janela de tempo. Muitos erros mongot estão a jusante dos eventos mongod.

• Se você abrir um caso de suporte do MongoDB, envie o arquivo de log completo ou uma janela de tempo ampla, em vez de um conjunto filtrado de ERROR linhas.

O que o FTDC contém

As amostras FTDC incluem dados nas mesmas categorias que as métricas do Prometheus, além do estado interno que mongot não expõe externamente:

• Estado do processo e da JVM, incluindo heap, coleta de lixo e threads

• Estatísticas de indexação por índice

• Latências de query por operador

• Estado de replicação e posição do oplog

• Estado do pool de executores

• Estado de mesclagem e cache do Lucene

• Configuração e eventos de ciclo de vida

• Estado do pool de conexões

Localização do arquivo FTDC

Por padrão, mongot grava arquivos FTDC em <storage.dataPath>/diagnostic.data/, a mesma convenção que mongod usa com <storage.dbPath>/diagnostic.data/.

Para uma instância mongot com storage.dataPath definido como /var/lib/mongot, os arquivos FTDC estão em /var/lib/mongot/diagnostic.data/.

mongot nomeia arquivos com carimbos de data/hora e os gira automaticamente. Os tamanhos dos arquivos são normalmente:

• Algumas centenas de KB por arquivo

• Vários arquivos por hora sob carga

• Aproximadamente 1 GB por dia por instância mongot, dependendo da carga

O tamanho total do diretório de arquivo FTDC no disco é limitado por advancedConfigs.ftdc.directorySizeMb.

Configurar FTDC

O FTDC está habilitado por padrão. Para substituir os padrões, defina as seguintes opções no bloco advancedConfigs.ftdc na configuração YAML mongot:

Para a maioria das implantações, os padrões são apropriados. Substitua-os somente se tiver um requisito específico de uso de disco. Para saber mais sobre essas configurações, consulte Configurações avançadas do FTDC.

Capturar FTDC para suporte

Ao abrir um caso com o suporte do MongoDB, envie todo o diretório diagnostic.data/ da instância mongot afetada, cobrindo o período do problema. Agrupe e compacte o diretório.

Para uma implantação de tarball do Linux, agrupe o diretório:

tar -czf mongot-ftdc-$(hostname)-$(date -u +%Y%m%dT%H%M%S).tar.gz <dataPath>/diagnostic.data/

Para uma implantação de contêiner, copie o diretório para fora do contêiner primeiro:

docker cp <container>:/<dataPath>/diagnostic.data ./mongot-ftdc
tar -czf mongot-ftdc.tar.gz ./mongot-ftdc

Para uma implantação do Kubernetes operador, copie o diretório para fora do pod primeiro:

kubectl cp <namespace>/<pod>:<dataPath>/diagnostic.data ./mongot-ftdc
tar -czf mongot-ftdc.tar.gz ./mongot-ftdc

Inclua o seguinte no caso de suporte:

• O pacote FTDC.

• O arquivo de log mongot que cobre a mesma janela de tempo, mais um buffer de uma hora antes.

• O arquivo de log mongod no primário cobrindo a mesma janela.

• A versão mongot, a versão mongod e a versão do operador Kubernetes, se aplicável.

• Um carimbo de data/hora de quando você observou o problema pela primeira vez.

• Uma descrição do que mudou na implantação por volta dessa época, como configuração, tráfego ou atualizações.

Dados confidenciais no FTDC

O FTDC contém métricas operacionais e estado interno, não dados de documentos brutos ou strings de query do usuário. Geralmente, o FTDC é seguro para enviar ao suporte do MongoDB sem higienização. Se sua política de compliance for mais rigorosa, revise os campos capturados com sua equipe de segurança antes de enviá-los.

O mesmo não é verdade para logs. As linhas de log podem incluir texto de query, identificadores de documento ou outros dados de nível de aplicativo, dependendo do nível de log. Revise os arquivos de log antes de enviá-los em ambientes de compliance restritivos.