Pular para o conteúdo
thiagoetipadrões

Contatos

apps/observability/log-aggregation

125 · Observabilidade & Operações · ≈ 6 min de estudo

Log Aggregation

Centraliza os logs de todos os serviços num lugar onde dá para buscar por campo. O serviço só escreve uma linha JSON por evento no stdout, num envelope fixo e já com PII mascarada; o runtime captura o stdout, o Promtail envia ao Loki, e uma consulta LogQL reconstrói a história de uma operação pelo correlationId. Use quando o que aconteceu com uma transação está espalhado em arquivos de várias máquinas.

passos
6
arquivos
8
testes
0
tecnologias
6
Infraestrutura realTypeScriptBunLokiPromtailGrafanaDocker
CenárioRelaçõesComparar
Baixar cartão

Cenário

O serviço de pagamentos processa três PIX: um liquidado, um bloqueado pelo limite noturno e um revertido por timeout no BACEN. Cada PIX loga início e fim sob o próprio pixId como correlationId, e o erro traz errorCode, attemptNumber e durationMs. No Loki, level="error" acha a falha na hora; correlationId="PIX-7002" devolve a história do PIX bloqueado; e nenhuma linha guardada contém o CPF ou a chave PIX do pagador.

Planta

Fluxo
5/5
svc-paymentsJSON no stdoutlogs/payments.logPromtaillabels: service, levelLokiGrafana ExploreLogQL: level=errorou correlationId=PIX-7002runtime capturatailpush
5

5 passos — reproduza para seguir o fluxo

Como funciona

6 passos

Logs de todos os serviços num lugar.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

correlationId+7
timestamp+1
level+1
service+1
message+1
  1. 01

    loggerCreate monta cada linha no envelope (timestamp, level, service, correlationId, message) e escreve no stdout sem bloquear

  2. 02

    fieldsMask mascara no logger, antes de serializar: chaves sensíveis pelo nome, CPF e cartão em qualquer texto — nunca caso a caso na chamada

  3. 03

    Linhas abaixo de LOG_LEVEL não são escritas: debug fica desligado fora de desenvolvimento

  4. 04

    O Promtail lê o arquivo, extrai o JSON e promove a label só service e level; o horário vem da própria linha

  5. 05

    correlationId fica dentro da linha: como label, criaria um stream por operação e sufocaria o índice

  6. 06

    lokiQuery usa LogQL: labels escolhem o stream, | json | correlationId="…" filtra dentro dele

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

  • Busca por qualquer campo, em todos os serviços

  • Uma consulta por correlationId conta a história inteira

  • PII mascarada antes de sair do processo

  • Labels poucas mantêm o Loki barato

Custos

  • JSON é mais volumoso que texto livre, e volume é custo

  • Todo serviço precisa propagar o mesmo correlationId

  • Padrões de máscara precisam acompanhar novos campos

  • Filtro por campo da linha é mais lento que por label

apps/observability/log-aggregation

8 arquivos

src/

  • logger_structured.tsEnvelope da linha, nível mínimo e escrita no stdout
  • log_mask.tsMáscara de PII por chave e por padrão de valor
  • payments_service.tsFluxo do PIX com marcos de início e fim e erro detalhado
  • loki_query.tsConsultas LogQL pela API HTTP do Loki
  • config_logging.tsConfiguração validada do ambiente
  • demo.tsdemoRoda o serviço, captura o stdout e consulta o Loki

collector/

  • promtail.ymlinfraTail do arquivo, parse do JSON, labels de baixa cardinalidade

./

  • docker-compose.ymlinfraLoki, Promtail e Grafana

Executar · com Docker

  1. docker compose up -d --wait# sobe Loki · Promtail · Grafana
  2. cp .env.example .env# variáveis de ambiente
  3. bun install# dependências
  4. bun run demo# roda o cenário
  5. bun run test# integração contra o serviço real

Grafana em http://localhost:8080 (Explore → Loki).

Requisitos
BunDocker
Sobe junto
LokiPromtailGrafana

Relações

Onde ele se encaixa

Mapa
  1. vem antesCorrelation ID
  2. Log Aggregation
  3. próximo passoDistributed Tracing
  • Vem antes1
  • Próximo passo1
  • Combina com3

L7Observabilidade· estação 3 de 6

← Correlation IDDistributed Tracing →

Por que se relacionam

Vem antes

Próximo passo

Combina com

Teste rápido

Qual é o próximo passo depois de Log Aggregation?

Próximo projeto · Observabilidade & OperaçõesCorrelation ID
Esc

↑ ↓ navegarEnter abrir191 resultados