Logs e métricas locais

Primeiros passos com dados e métricas locais e do sistema no ClickStack

Este guia de introdução permite coletar logs e métricas locais do seu sistema e enviá-los ao ClickStack para visualização e análise.

Este exemplo funciona apenas em sistemas OSX e Linux

Managed ClickStack

Este guia pressupõe que você concluiu o Guia de Primeiros Passos do Managed ClickStack e tem as credenciais de conexão anotadas.

1. ​

   Crie uma configuração personalizada do OpenTelemetry

   Crie o arquivo custom-local-config.yaml com o seguinte conteúdo:

   receivers:
     filelog:
       include:
         - /host/var/log/**/*.log        # Logs do Linux do host
         - /host/var/log/syslog
         - /host/var/log/messages
         - /host/private/var/log/*.log   # Logs do macOS do host
       start_at: beginning
       resource:
         service.name: "system-logs"
   
     hostmetrics:
       collection_interval: 1s
       scrapers:
         cpu:
           metrics:
             system.cpu.time:
               enabled: true
             system.cpu.utilization:
               enabled: true
         memory:
           metrics:
             system.memory.usage:
               enabled: true
             system.memory.utilization:
               enabled: true
         filesystem:
           metrics:
             system.filesystem.usage:
               enabled: true
             system.filesystem.utilization:
               enabled: true
         paging:
           metrics:
             system.paging.usage:
               enabled: true
             system.paging.utilization:
               enabled: true
             system.paging.faults:
               enabled: true
         disk:
         load:
         network:
         processes:
   
   service:
     pipelines:
       logs/local:
         receivers: [filelog]
         processors:
           - memory_limiter
           - batch
         exporters:
           - clickhouse
       metrics/hostmetrics:
         receivers: [hostmetrics]
         processors:
           - memory_limiter
           - batch
         exporters:
           - clickhouse
   

   Esta configuração coleta logs e métricas do sistema em sistemas OSX e Linux, enviando os resultados para o ClickStack. Ela estende o ClickStack collector com a adição de novos receivers e pipelines — você faz referência ao exporter clickhouse e aos processors (memory_limiter, batch) já configurados no ClickStack collector base.

   Timestamps de ingestão

   Esta configuração ajusta os timestamps na ingestão, atribuindo um valor de tempo atualizado a cada evento. O ideal é pré-processar ou fazer o parse dos timestamps usando processors ou operators do OTel nos arquivos de log para garantir que o horário exato do evento seja preservado.

   Com esta configuração de exemplo, se o receiver ou o processor de arquivos estiver configurado para iniciar no começo do arquivo, todas as entradas de log existentes receberão o mesmo timestamp ajustado — o horário do processamento, em vez do horário original do evento. Quaisquer novos eventos acrescentados ao arquivo receberão timestamps que se aproximam do momento real em que foram gerados.

   Para evitar esse comportamento, você pode definir a posição inicial como end na configuração do receiver. Isso garante que apenas novas entradas sejam ingeridas e recebam timestamps próximos do horário real de chegada.

   Para mais detalhes sobre a estrutura de configuração do OpenTelemetry (OTel), recomendamos o guia oficial.

2. ​

   Inicie o coletor OpenTelemetry

   Execute um coletor autônomo com o seguinte comando:

   docker run -d \
     -p 4317:4317 -p 4318:4318 \
     --user 0:0 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
     -e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
     -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
     -v "$(pwd)/custom-local-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v /var/log:/host/var/log:ro \
     -v /private/var/log:/host/private/var/log:ro \
     clickhouse/clickstack-otel-collector:latest
   

   O coletor começará imediatamente a coletar os logs e as métricas do sistema local.

3. ​

   Selecione seu serviço

   Selecione o serviço Managed ClickStack na página inicial do ClickHouse Cloud.

4. ​

   Explore os logs do sistema

   Selecione ClickStack no menu à esquerda para acessar a UI do ClickStack, onde você será autenticado automaticamente.

   A UI de pesquisa deve ser preenchida com logs locais do sistema. Expanda os filtros para selecionar system.log:

5. ​

   Explore as métricas do sistema

   Podemos explorar nossas métricas usando gráficos.

   Navegue até o Chart Explorer pelo menu à esquerda. Selecione a fonte Metrics e Maximum como tipo de agregação.

   No menu Select a Metric, basta digitar memory antes de selecionar system.memory.utilization (Gauge).

   Pressione o botão de execução para visualizar a utilização de memória ao longo do tempo.

   Observe que o valor é retornado como uma porcentagem (%) em ponto flutuante. Para exibi-lo com mais clareza, selecione Set number format.

   No menu seguinte, você pode selecionar Percentage no menu suspenso Output format antes de clicar em Apply.

ClickStack Open Source

​

Criar uma configuração personalizada do OpenTelemetry

Crie um arquivo custom-local-config.yaml com o seguinte conteúdo:

receivers:
  filelog:
    include:
      - /host/var/log/**/*.log        # Logs do Linux do host
      - /host/var/log/syslog
      - /host/var/log/messages
      - /host/private/var/log/*.log   # Logs do macOS do host
    start_at: beginning
    resource:
      service.name: "system-logs"

  hostmetrics:
    collection_interval: 1s
    scrapers:
      cpu:
        metrics:
          system.cpu.time:
            enabled: true
          system.cpu.utilization:
            enabled: true
      memory:
        metrics:
          system.memory.usage:
            enabled: true
          system.memory.utilization:
            enabled: true
      filesystem:
        metrics:
          system.filesystem.usage:
            enabled: true
          system.filesystem.utilization:
            enabled: true
      paging:
        metrics:
          system.paging.usage:
            enabled: true
          system.paging.utilization:
            enabled: true
          system.paging.faults:
            enabled: true
      disk:
      load:
      network:
      processes:

service:
  pipelines:
    logs/local:
      receivers: [filelog]
      processors:
        - memory_limiter
        - batch
      exporters:
        - clickhouse
    metrics/hostmetrics:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - batch
      exporters:
        - clickhouse

Esta configuração coleta logs e métricas do sistema para OSX e Linux, enviando os resultados ao ClickStack. A configuração estende o collector do ClickStack adicionando novos receivers e pipelines — você referencia o exporter clickhouse existente e os processors (memory_limiter, batch) já configurados no collector base do ClickStack.

Timestamps de ingestão

Esta configuração ajusta os timestamps durante a ingestão, atribuindo um valor de tempo atualizado a cada evento. O ideal é pré-processar ou interpretar timestamps usando processadores ou operadores do OTel nos arquivos de log para garantir que o horário correto do evento seja preservado.

Com esta configuração de exemplo, se o receiver ou o processador de arquivo estiver configurado para começar no início do arquivo, todas as entradas de log existentes receberão o mesmo timestamp ajustado: o horário do processamento, em vez do horário original do evento. Quaisquer novos eventos acrescentados ao arquivo receberão timestamps próximos do horário real em que foram gerados.

Para evitar esse comportamento, você pode definir a posição inicial como end na configuração do receiver. Isso garante que apenas novas entradas sejam ingeridas e recebam timestamps próximos do seu horário real de chegada.

Para mais detalhes sobre a estrutura de configuração do OpenTelemetry (OTel), recomendamos o guia oficial.

​

Iniciar o ClickStack com configuração personalizada

Execute o seguinte comando docker para iniciar o contêiner all-in-one com sua configuração personalizada:

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

Usuário root

Executamos o collector como usuário root para acessar todos os logs do sistema — isso é necessário para capturar logs em caminhos protegidos em sistemas baseados em Linux. No entanto, essa abordagem não é recomendada para produção. Em ambientes de produção, o OpenTelemetry Collector deve ser implantado como um agent local, com apenas as permissões mínimas necessárias para acessar as fontes de logs desejadas.

Observe que montamos o /var/log do host em /host/var/log dentro do contêiner para evitar conflitos com os arquivos de log do próprio contêiner.

​

Explorar logs do sistema

Acesse http://localhost:8080 para acessar a UI do ClickStack caso esteja fazendo a implantação localmente.

As fontes de dados devem ser pré-criadas automaticamente. A UI de pesquisa deve estar preenchida com logs do sistema local. Expanda os filtros para selecionar o system.log:

​

Explorar métricas do sistema

Podemos explorar nossas métricas usando gráficos.

Navegue até o Chart Explorer pelo menu lateral esquerdo. Selecione a source Metrics e Maximum como tipo de agregação.

No menu Select a Metric, digite memory e selecione system.memory.utilization (Gauge).

Pressione o botão de execução para visualizar o uso de memória ao longo do tempo.

Observe que o número é retornado como ponto flutuante %. Para exibi-lo de forma mais clara, selecione Set number format.

No menu seguinte, selecione Percentage no menu suspenso Output format e clique em Apply.