Esse asset é um repositório que apresenta uma implementação de observabilidade em uma aplicação NestJS, utilizando o OpenTelemetry como padrão para a coleta de dados.
Visão Geral do Projeto
O projeto consiste em uma API construída com o framework NestJS, que gerencia usuários e transações para um blog fictício. A aplicação utiliza um banco de dados PostgreSQL para persistência de dados. O foco principal do repositório é demonstrar a integração de uma stack de observabilidade completa, utilizando ferramentas de código aberto.
Stack de Observabilidade
A solução de observabilidade é totalmente containerizada e orquestrada com o Docker Compose. A tabela abaixo descreve os principais componentes da stack:
|
Serviço
|
Imagem
|
Finalidade
|
|
postgres
|
postgres:16-alpine
|
Banco de dados da aplicação.
|
|
app
|
(build local)
|
A aplicação NestJS instrumentada com OpenTelemetry.
|
|
otel-collector
|
otel/opentelemetry-collector-contrib
|
Recebe dados de telemetria (traces e logs) da aplicação e os exporta para os backends de armazenamento.
|
|
tempo
|
grafana/tempo
|
Armazena os traces distribuídos.
|
|
loki
|
grafana/loki
|
Agrega e armazena os logs da aplicação.
|
|
grafana
|
grafana/grafana
|
Interface de visualização para os dados de telemetria, com dashboards para Tempo e Loki.
|
Estratégia de Instrumentação
A instrumentação da aplicação é realizada de forma automática, utilizando a biblioteca @opentelemetry/auto-instrumentations-node. Essa abordagem permite a coleta de traces de diversas bibliotecas e frameworks (como Express.js, usado por baixo dos panos no NestJS) sem a necessidade de instrumentação manual do código.
Correlação de Traces e Logs
Para facilitar a depuração e análise de problemas, a implementação inclui um logger customizado que correlaciona traces e logs. O arquivo src/trace.logger.ts define a classe TraceLogger, que estende o ConsoleLogger do NestJS.
A principal funcionalidade do TraceLogger é a injeção do traceId do span ativo em cada mensagem de log. Isso é feito através da função getTraceId( ), que utiliza a API do OpenTelemetry (@opentelemetry/api) para obter o traceId do span atual. O resultado é um log formatado que inclui o trace_id, permitindo a fácil correlação entre um log específico e o trace completo da requisição que o gerou.
