Registro JSON e Datadog

Por que você deve usar JSON para registro de logs

Se você não está usando o registro de logs em JSON hoje, provavelmente está dependendo de logs em texto simples e expressões regulares para interpretá-los. Isso pode funcionar no início, mas começará a falhar, perderá a estrutura e piorará cada vez mais à medida que os sistemas crescerem. O registro em JSON é o padrão. Em aplicações modernas, ter registros estruturados e facilmente analisáveis deixou de ser opcional. Isso proporciona um nível de consistência entre os serviços, ao mesmo tempo que oferece flexibilidade.

A Datadog recomenda o registro em JSON por um motivo. Quando os registros são emitidos como JSON válido, o pré-processador do Datadog analisa automaticamente os registros e os mapeia para uma série de atributos reservados que reduzem a sobrecarga e garantem a extração consistente dos campos. Nenhuma configuração adicional é necessária, pois esses atributos reservados fornecem os campos mais relevantes, facilitando a integração com outros sistemas, a filtragem de logs, a busca eficiente e a configuração de alertas. Os atributos reservados cruciais incluem host, serviço, status, ID de rastreamento, ID do span e outros, que são essenciais para observabilidade e solução de problemas.

Como configurar

Na minha experiência, havia uma abundância de recursos sobre a melhor forma de configurar o registro de logs em JSON. A principal referência que usei foi a documentação do Datadog: https://docs.datadoghq.com/logs/log_collection/java/?tab=logback. Achei melhor porque o Datadog era a principal ferramenta de observabilidade que usávamos e eles seriam capazes de solucionar problemas mais facilmente se algum problema ocorresse.

Usando a documentação do Datadog como guia, comecei criando o arquivo de configuração logback-spring.xml . É aqui que a maior parte do trabalho acontece. Inicialmente, experimentei vários codificadores JSON e adicionei campos que achei que poderiam ser úteis. Com o tempo, percebi o poder da simplicidade: uma configuração limpa e minimalista é mais fácil de manter e menos propensa a apresentar problemas.

<springProfile name="json-logs">

        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="net.logstash.logback.encoder.LogstashEncoder" />
        </appender>

        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>

Após adicionar as dependências necessárias do Logback e inserir este código no meu arquivo logback-spring.xml, o último passo importante é definir 'json-logs' como o perfil Spring ativo no meu arquivo YAML da aplicação. Isso garante que o registro em JSON esteja habilitado em todo o seu ambiente e funcione de forma consistente em todos os serviços.

Se esses passos foram seguidos corretamente, você poderá acompanhar os registros (logs) e ver os resultados. Eles devem estar em um registro de chave-valor semelhante a este:

{"@timestamp":"2025-1-13T13:02:27.512333-02:00","@version":"1","message":"Tomcat initialized with port 8080(http)",
"logger_name":"org.springframework.boot.web.embedded.tomcat.TomcatWebServer","thread_name":"main","level":"INFO",
"level_value":20000,"appName":"json-logs"}  

Neste ponto, seus registros no Datadog devem estar estruturados, a correlação de rastreamento deve funcionar para registros com IDs de rastreamento e você deve ver atributos mais detalhados e consistentes.

Erros comuns e conselhos

• Utilize um agregador de arquivos se isso funcionar melhor para o seu sistema. Para o nosso ambiente, o appender de console se adequou melhor às nossas necessidades.
• Não se deixe levar pela variedade de opções de codificação JSON; geralmente, o mais simples é melhor, pelo menos inicialmente.
• Verifique se já existem regras de processamento de logs no seu agente Datadog. Essas regras podem interferir nos registros JSON e impedir que sejam analisados ou entregues corretamente. Certifique-se de que os registradores legados não estejam em conflito com sua configuração.
• Para maior controle, considere criar vários perfis do Spring. Isso permite alternar entre níveis ou formatos de registro em diferentes ambientes sem alterar o código do aplicativo.
• Se o rastreamento não estiver funcionando para muitos dos seus registros no Datadog, isso ocorre porque eles amostram automaticamente o rastreamento para muitos dos seus registros. O JSON está funcionando, não se preocupe, mas você pode configurá-lo para uma taxa diferente.

Com a configuração correta, o registro em JSON no Datadog torna-se confiável e muito mais fácil de manter. Ao eliminar pressupostos antigos e manter sua configuração simples, você obtém logs estruturados, campos consistentes, correlação de rastreamento e filtragem e alertas mais fáceis. O registro em JSON não é apenas uma boa prática; é essencial para melhorar a observabilidade em aplicações modernas.

Sobre o autor

Gostou do que ouviu? Tem dúvidas sobre o que é certo para você? Adoraríamos conversar! Entre em contato conosco.

Artigos relacionados