Trace e Log

Esse tutorial mostra os principais passos para você adicionar uma ferramenta de trace chamada Jaeger e também uma ferramenta para consolidar logs chamada Graylog.

Jaeger

Inspirado no Dapper e no OpenZipkin, o Jaeger foi desenvolvido pela Uber e é uma ferramenta de trace distribuído que implementa a especificação OpenTelemetry. O trace é o registo de uma requisição de ponta a ponta em um sistema distribuído. Ele fornece visibilidade do fluxo de trabalho de um serviço (trace), permitindo que os desenvolvedores vejam o desempenho e o comportamento do serviço em tempo real.

O Jaeger opera por meio do rastreamento dos requests, registrando informações sobre cada solicitação à medida que ela passa pelos diferentes serviços do sistema. Esses registros são coletados e analisados pelo Jaeger, permitindo que os desenvolvedores vejam como as solicitações estão sendo processadas e onde ocorrem possíveis gargalos ou falhas.

Com o Jaeger, os desenvolvedores podem identificar rapidamente problemas de desempenho e depurar falhas em aplicativos distribuídos complexos, ajudando a melhorar a eficiência e a confiabilidade do sistema como um todo.

Entre as principais funcionalidades do Jaeger estão: Rastreamento de solicitações, visualização do fluxo de trabalho, análise de desempenho, alertas e notificações, armazenamento no longo prazo e integração com outras ferramentas.

Para executar o Jaeger utilize, por exemplo, o docker-compose.yml abaixo:

version: '3.9'
services:

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686" # Jaeger UI
      - "14268:14268" # Receive legacy OpenTracing traces, optional
      - "4317:4317"   # OTLP gRPC receiver
      - "4318:4318"   # OTLP HTTP receiver, not yet used by Quarkus, optional
      - "14250:14250" # Receive from external otel-collector, optional
    environment:
      - COLLECTOR_OTLP_ENABLED=true

Para executar um arquivo docker-compose.yml, siga os seguintes passos:

Certifique-se de ter o Docker e o Docker Compose instalados em sua máquina.
Navegue até o diretório onde o arquivo docker-compose.yml está localizado. Abra um terminal ou prompt de comando no diretório em questão.
Execute o comando docker-compose up -d para iniciar todos os contêineres definidos no arquivo docker-compose.yml. Este comando irá baixar as imagens necessárias do Docker Hub e executar os contêineres em questão.
Aguarde até que todos os contêineres sejam iniciados e estejam prontos para uso.
Cado deseje interromper e remover todos os contêineres definidos no arquivo docker-compose.yml, execute o comando docker-compose down.

Cabe ressaltar, que o Jaeger possui algumas desvantagens, são elas: impacto no desempenho do sistema (overhead), custo adicional, gerenciamento de dados, conhecimento especializado e integração com algumas ferramentas pode ser um desafio.

Para ver a interface do usuário do Jaeger, abra o navegador e acesse http://localhost:16686. A interface do usuário do Jaeger permite que você visualize os traces e analise o desempenho do sistema.

Jaeger com Quarkus

Vamos aos passos de configuração do Jaeger em um projeto Quarkus: Primeiro, instale a extensão quarkus-opentelemetry no seu projeto. Depois, configure o seu application.properties com as configurações do Jaeger:

quarkus.otel.service.name=myservice
quarkus.otel.exporter.otlp.traces.endpoint=http://localhost:4317
quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId}, parentId=%X{parentId}, spanId=%X{spanId}, sampled=%X{sampled} [%c{2.}] (%t) %s%e%n

🚨 A configuração acima mostra como configurar a integração do Jaeger com o Quarkus.

A primeira linha quarkus.otel.service.name define o nome do serviço que está sendo monitorado. Nesse caso, “myservice” é o nome do serviço.
A segunda linha quarkus.otel.exporter.otlp.traces.endpoint define o endpoint aonde informações de log serão armazenadas. Neste caso, o endpoint é http://localhost:4317.
A quarta linha quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId}, parentId=%X{parentId}, spanId=%X{spanId}, sampled=%X{sampled} [%c{2.}] (%t) %s%e%n define o formato de log que será usado.

GrayLog

O Graylog é uma ferramenta de gerenciamento e análise de logs que permite coletar, processar e analisar registros de várias fontes, como aplicativos, serviços, sistemas operacionais e dispositivos de rede.

O Graylog oferece uma interface da Web para pesquisar e analisar logs, bem como ferramentas de alerta para notificar as equipes quando ocorrem eventos importantes. Além disso, o Graylog oferece recursos de análise de log, como gráficos e métricas, que podem ajudar as equipes de operações e desenvolvimento a identificar tendências de desempenho e problemas recorrentes.

O Graylog é uma ferramenta de código aberto que oferece uma variedade de integrações com outras ferramentas populares, Kafka, Prometheus e outros, permitindo que os usuários personalizem a plataforma de acordo com suas necessidades.

Para colocar o GrayLog para rodar utilize, por exemplo, o docker-compose.yml abaixo:

version: '3.2'

services:
  elasticsearch:
    image: docker.io/elastic/elasticsearch:7.16.3
    ports:
      - "9200:9200"
    environment:
      ES_JAVA_OPTS: "-Xms512m -Xmx512m" # Use half of the available RAM
      discovery.type: "single-node" # Disable production mode
    networks:
      - graylog

  mongo:
    image: mongo:5.0
    networks:
      - graylog

  graylog:
    image: graylog/graylog:5.1
    ports:
      - "9000:9000" # HTTP
      - "12201:12201/udp" # GELF UDP
      - "1514:1514" # GELF TCP
    environment:
      GRAYLOG_HTTP_EXTERNAL_URI: "http://127.0.0.1:9000/"
      # CHANGE ME (must be at least 16 characters)!
      GRAYLOG_PASSWORD_SECRET: "forpasswordencryption"
      # Password: admin
      GRAYLOG_ROOT_PASSWORD_SHA2: "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
    networks:
      - graylog
    depends_on:
      - elasticsearch
      - mongo

networks:
  graylog:
    driver: bridge

Depois de executar o comando docker-compose up -d, você pode acessar o GrayLog por meio do navegador em http://localhost:9000. O nome de usuário padrão é admin e a senha padrão é admin.

Crie um “input” no GrayLog:

curl -H "Content-Type: application/json" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "X-Requested-By: curl" -X POST -v -d \
'{"title":"Application log input","configuration":{"recv_buffer_size":262144,"bind_address":"0.0.0.0","port":12201,"decompress_size_limit":8388608},"type":"org.graylog2.inputs.gelf.udp.GELFUDPInput","global":true}' \
http://localhost:9000/api/system/inputs

🚨 Um “input” também pode ser criado pelo console de administração do GrayLog(System → Inputs → Select GELF UDP).

Na prática, um input é uma fonte de dados que o Graylog pode monitorar e coletar informações. Por exemplo, se você tem um aplicativo executando em um servidor, é possível configurar um input para coletar os logs desse servidor.

GrayLog com Quarkus

Agora, vamos aos passos para configurar o GrayLog no Quarkus: Primeiro, instale a extensão quarkus-logging-gelf no seu projeto. Depois, configure o application.properties para permitir que as mensagens do seu projeto possam ser encaminhadas para o GrayLog.

quarkus.log.handler.gelf.enabled=true
quarkus.log.handler.gelf.host=localhost
quarkus.log.handler.gelf.port=12201

Esse código configura as propriedades de registro (logging) do Quarkus para enviar logs em formato GELF (Graylog Extended Log Format) para um servidor local hospedado em localhost na porta 12201.

O GELF é um formato de registro que permite a estruturação de dados adicionais nos logs, como campos adicionais, tags e outras informações importantes, além das mensagens padrão de registro. Essas informações adicionais podem ser usadas para melhorar a análise de logs e a depuração de problemas no sistema.

Ao configurar essas propriedades, o Quarkus enviará logs formatados em GELF para o servidor hospedado em localhost na porta 12201, permitindo que o servidor colete e analise os logs do aplicativo Quarkus.

Embora o Graylog seja uma plataforma de gerenciamento e análise de logs robusta e altamente escalável, há algumas desvantagens que devem ser consideradas:

Configuração complexa: A configuração inicial do Graylog pode ser complexa, principalmente se você tiver muitas fontes de dados diferentes ou se precisar criar filtros e alertas personalizados.
Requer habilidades técnicas: Para aproveitar ao máximo o Graylog, é necessário ter conhecimento técnico em sistemas operacionais, redes, bancos de dados, entre outras áreas, o que pode ser um desafio para equipes que não possuem essas habilidades internamente.
Alto consumo de recursos: O Graylog é uma plataforma de log que requer muitos recursos para executar de forma eficiente, o que pode ser um problema para organizações com limitações de recursos de hardware ou nuvem.

Referências 📚

Alex Soto Bueno; Jason Porter; Quarkus Cookbook: Kubernetes-Optimized Java Solutions. Editora: O’Reilly Media, 2020.
Using OpenTelemetry. Disponível em: https://quarkus.io/guides/opentelemetry
Centralized Log Management. Disponível em: https://quarkus.io/guides/centralized-log-management
Jaeger. Disponível em: https://www.jaegertracing.io
GrayLog. Disponível em: https://www.graylog.org

CC BY 4.0 DEED