SigNoz — Observabilidade OpenTelemetry-nativa

SigNoz reúne traces, métricas e logs num único produto, com ClickHouse como armazenamento e OTLP como única porta de entrada. A aplicação nunca fala com o SigNoz: exporta para o collector, e o collector escreve no ClickHouse. Use quando a pergunta “o tempo foi no banco ou no PSP?” precisa de resposta sem pagar APM por host.

passos: 6
arquivos: 12
testes: 0
tecnologias: 8

Infraestrutura realTypeScriptBunElysiaPostgreSQLClickHouseOpenTelemetrySigNozDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um serviço de liquidação PIX de banco digital. Cada transferência debita uma conta, credita outra, grava o registro e chama o PSP. Quando o p99 sobe, o trace responde onde foi o tempo, porque cada comando SQL e a chamada ao PSP são spans separados. O demo gera quatro formas de tráfego:

Planta

Fluxo

8/8

8 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num nó para focar
Outras plantas de fluxo

Como funciona

6 passos

Traces, métricas e logs num painel.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

UPDATE+5

COMMIT+5

service.name+3

@elysiajs/opentelemetry+3

BEGIN+3

INSERT+3

instrumentation.ts+2

trace_id+2

01
instrumentation.ts sobe por --preload o NodeSDK com resource (service.name, versão, as duas chaves de ambiente), exportadores OTLP para o collector e a instrumentação do pg
02
O plugin @elysiajs/opentelemetry abre o span da requisição; cada BEGIN, UPDATE, INSERT, COMMIT vira span filho
03
api_settlement.ts abre o span de negócio pix.transfer com os atributos (pix.end_to_end_id, pix.amount_cents) e psp.settle para o PSP — nome é operação, id é atributo
04
log_pix.ts emite log dentro do span ativo: o SDK carimba trace_id e span_id, o salto trace → logs
05
O collector deriva métricas RED das spans (signozspanmetrics) e grava nas três bases; o schema-migrator criou as tabelas antes
06
clickhouse_signoz.ts lê de volta o que o SigNoz mostra: trace por atributo de negócio, árvore de spans e logs do trace

Trade-offs

O que se ganha, o que se paga

Vantagem	Custo
Um produto para os três sinais, sem costurar Jaeger + Prometheus + Loki	ClickHouse e ZooKeeper são infraestrutura a operar
OTLP puro: trocar o backend não mexe na aplicação	O collector vira dependência no caminho da telemetria
Métricas RED derivadas das spans, sem instrumentação extra	Cardinalidade das dimensões precisa ser vigiada
ClickHouse aguenta alto volume de trace com retenção barata	Consulta mal filtrada em janela larga é cara

apps/observability/signoz

12 arquivos

src/

instrumentation.tsSDK OpenTelemetry: resource, exportadores OTLP, instrumentação pg, flush no SIGTERM
api_settlement.tsAPI Elysia: atributos de negócio, span manual do PSP, estorno em timeout
ledger_pix.tsDébito condicional, crédito e estorno em transação
log_pix.tsLog OTel dentro do span ativo, espelhado no stdout
metrics_pix.tsContadores de negócio por desfecho e valor liquidado
clickhouse_signoz.tsConsultas ao ClickHouse: trace por atributo, spans e logs
config_signoz.tsConfiguração validada do ambiente
demo.tsdemoGera o tráfego e imprime a árvore do trace lento e os logs do estorno

otel-collector-config.yamlinfraReceiver OTLP, signozspanmetrics e os três exportadores ClickHouse
docker-compose.ymlinfraZooKeeper, ClickHouse, migrator, collector, SigNoz e PostgreSQL

clickhouse/

config.xmlCluster cluster com 1 shard e 1 réplica, ZooKeeper e macros

sql/

01_schema.sqlschemaContas e transferências em centavos

Executar · com Docker

$ docker compose up -d --wait# sobe PostgreSQL · ClickHouse · SigNoz
$ cp .env.example .env# variáveis de ambiente
$ bun install# dependências
$ bun run demo# roda o cenário
$ bun run test# integração contra o serviço real
$

UI em http://localhost:8080 (o primeiro acesso cria a conta de admin). As métricas de span saem a cada 60 s: a tela Services leva cerca de um minuto para preencher. O teste sobe a própria stack de ingestão (ZooKeeper, ClickHouse, migrator, collector) com portas aleatórias.

Requisitos: BunDocker
Sobe junto: PostgreSQLClickHouseSigNoz

Relações

Onde ele se encaixa

Mapa