Monitorando logs do MongoDB com ClickStack

Integração com MongoDB existente

Esta seção explica como configurar sua instalação existente do MongoDB para enviar logs para o ClickStack, modificando a configuração do OTel collector do ClickStack. Se você quiser testar a integração com MongoDB antes de configurar sua própria instalação, poderá testá-la com nossa configuração pré-configurada e dados de exemplo na seção "Dataset de demonstração".

Pré-requisitos

Instância do ClickStack em execução
Instalação existente do MongoDB autogerenciado (versão 4.4 ou superior)
Acesso aos arquivos de log do MongoDB

Verifique a configuração de logging do MongoDB

O MongoDB 4.4+ gera logs estruturados em JSON por padrão. Verifique o local do arquivo de log:

cat /etc/mongod.conf | grep -A 5 systemLog

Locais comuns dos logs do MongoDB:

Linux (apt/yum): /var/log/mongodb/mongod.log
macOS (Homebrew): /usr/local/var/log/mongodb/mongo.log
Docker: Geralmente é registrado em stdout, mas pode ser configurado para gravar em /var/log/mongodb/mongod.log

Se o MongoDB estiver registrando em stdout, configure-o para gravar em um arquivo atualizando o mongod.conf:

systemLog:
  destination: file
  path: /var/log/mongodb/mongod.log
  logAppend: true

Após alterar a configuração, reinicie o MongoDB:

# For systemd
sudo systemctl restart mongod

# For Docker
docker restart <mongodb-container>

Criar uma configuração personalizada do OTel collector para MongoDB

O ClickStack permite estender a configuração base do OpenTelemetry Collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente. A configuração personalizada é mesclada à configuração base gerenciada pelo HyperDX via OpAMP.

Crie um arquivo chamado mongodb-monitoring.yaml com a seguinte configuração:

receivers:
  filelog/mongodb:
    include:
      - /var/log/mongodb/mongod.log
    start_at: beginning
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.t.$$date
          layout: '2006-01-02T15:04:05.000-07:00'
          layout_type: gotime
        severity:
          parse_from: attributes.s
          overwrite_text: true
          mapping:
            fatal: F
            error: E
            warn: W
            info: I
            debug:
              - D1
              - D2
              - D3
              - D4
              - D5

      - type: move
        from: attributes.msg
        to: body

      - type: add
        field: attributes.source
        value: "mongodb"

      - type: add
        field: resource["service.name"]
        value: "mongodb-production"

service:
  pipelines:
    logs/mongodb:
      receivers: [filelog/mongodb]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Configure o ClickStack para carregar configuração personalizada

Para habilitar a configuração personalizada do collector na implantação existente do ClickStack, você deve:

Montar o arquivo de configuração personalizado em /etc/otelcol-contrib/custom.config.yaml
Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar o diretório de logs do MongoDB para que o collector possa lê-los

Atualize a configuração da implantação do ClickStack:

services:
  clickstack:
    # ... configuração existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... outras variáveis de ambiente ...
    volumes:
      - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mongodb:/var/log/mongodb:ro
      # ... outros volumes ...

Se você estiver usando a imagem all-in-one com Docker, execute:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/mongodb:/var/log/mongodb:ro \
  clickhouse/clickstack-all-in-one:latest

Verifique os logs no HyperDX

Após a configuração, faça login no HyperDX e verifique se os logs estão chegando:

Visualização de pesquisa dos logs do MongoDB

Visualização detalhada dos logs do MongoDB

Dataset de demonstração

Teste a integração com MongoDB usando um dataset de exemplo pré-gerado antes de configurar seus sistemas de produção.

Baixe o dataset de exemplo

Baixe o arquivo de log de exemplo:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mongodb/mongod.log

Crie a configuração de teste do collector

Crie um arquivo chamado mongodb-demo.yaml com a configuração a seguir:

cat > mongodb-demo.yaml << 'EOF'
receivers:
  filelog/mongodb:
    include:
      - /tmp/mongodb-demo/mongod.log
    start_at: beginning
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.t.$$date
          layout: '2006-01-02T15:04:05.000-07:00'
          layout_type: gotime
        severity:
          parse_from: attributes.s
          overwrite_text: true
          mapping:
            fatal: F
            error: E
            warn: W
            info: I
            debug:
              - D1
              - D2
              - D3
              - D4
              - D5

      - type: move
        from: attributes.msg
        to: body

      - type: add
        field: attributes.source
        value: "mongodb-demo"

      - type: add
        field: resource["service.name"]
        value: "mongodb-demo"

service:
  pipelines:
    logs/mongodb-demo:
      receivers: [filelog/mongodb]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Execute o ClickStack com a configuração de demonstração

Execute o ClickStack com os logs e a configuração de demonstração:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/mongodb-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/mongod.log:/tmp/mongodb-demo/mongod.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verifique os logs no HyperDX

Depois que o ClickStack estiver em execução:

Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
Acesse a Search view e defina a source como Logs
Defina o intervalo de tempo para incluir 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

Visualização de pesquisa de logs do MongoDB

Visualização detalhada do log do MongoDB

Dashboards e visualizações

Baixar a configuração do dashboard

Baixar o arquivo de configuração do dashboard.

Importar dashboard pré-configurado

Abra o HyperDX e navegue até a seção Dashboards.
Clique em "Import Dashboard" no canto superior direito, no menu de reticências.

Faça upload do arquivo mongodb-logs-dashboard.json e clique em "Finish Import".

Concluir importação do dashboard de logs do MongoDB

O dashboard será criado com todas as visualizações pré-configuradas

Para o dataset de demonstração, defina o intervalo de tempo para abranger 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

Solução de problemas

Nenhum log aparece no HyperDX

Verifique se a configuração efetiva inclui o receiver filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Verifique se há erros nos logs do collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log

Logs não estão sendo interpretados corretamente

Verifique se o MongoDB está gerando logs em JSON (4.4+):

tail -1 /var/log/mongodb/mongod.log | python3 -m json.tool

Se a saída não for um JSON válido, sua versão do MongoDB pode estar usando o formato de log de texto legado (anterior à 4.4). Será necessário substituir o operador json_parser por regex_parser ou atualizar para o MongoDB 4.4+.

Próximos passos

Configure alertas para eventos críticos (picos de erro, limites para consultas lentas)
Crie dashboards adicionais para casos de uso específicos (monitoramento do conjunto de réplicas, rastreamento de conexões)

Preparando para produção

Este guia usa o OpenTelemetry Collector integrado do ClickStack para uma configuração rápida. Para implantações em produção, recomendamos executar seu próprio OTel collector e enviar dados para o endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para a configuração de produção.