Exemplo completo de implementação de Open Telemetry aplicação Node.js

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.

Vamos entender o próximo passo juntos?

Fale com um especialista da eximia.co sobre arquitetura, engenharia e tecnologia.

Mais ferramentas

Assessment de capital político para arquitetos de software e líderes de tecnologia

Esse checklist é um Assessment de Capital Político para arquitetos de software e lideres de tecnologia em geral. Uma ferramenta para você saber, com honestidade, como está sua capacidade real de influenciar. Ele separa o que quase ninguém mede, mas todo líder sente na pele: DepósitosAs atitudes que aumentam confiança e abrem portas. Saques As ações […]

Baixar ferramenta

Modelo de Governança para tratar itens urgentes

Aprenda a governar a urgência e evitar o colapso da engenharia. Descubra como repriorizações sem critérios destroem a produtividade e o fluxo técnico.