Pular para o conteúdo
thiagoetipadrões

Contatos

apps/observability/sidecar

129 · Observabilidade & Operações · ≈ 7 min de estudo

Sidecar (Observabilidade)

Container auxiliar implantado no mesmo pod da aplicação, compartilhando volume, rede e ciclo de vida, para assumir uma responsabilidade transversal sem tocar no código dela. Aqui o sidecar é o Fluent Bit: a API de pagamentos só escreve linhas JSON num arquivo, e o sidecar lê, enriquece com os metadados do pod e envia ao Elasticsearch. Use quando a aplicação não pode (ou não deve) carregar cliente, endereço e retry do backend de logs.

passos
6
arquivos
10
testes
0
tecnologias
6
Infraestrutura realTypeScriptBunElysiaElasticsearchFluent BitDocker
CenárioRelaçõesComparar
Baixar cartão

Cenário

A API de pagamentos liquida três PIX: um liquidado, um bloqueado pelo limite noturno e um revertido por timeout no BACEN. Ela grava cada evento no arquivo com correlationId igual ao pixId e não sabe que o Elasticsearch existe. No Elasticsearch, a história do PIX-8003 aparece campo a campo, com o horário escrito pela aplicação e com pod e namespace — dados que só a plataforma conhece. Se o sidecar reinicia, ele retoma do offset gravado e envia só as linhas novas, sem duplicar o arquivo.

Planta

Fluxo
4/4
pod payments-api-7f9c4API de pagamentosescreve JSON em arquivovolume compartilhado/var/log/appFluent Bit sidecartail + parser + modifyElasticsearchpayments-logsbusca por correlationIdcontagem por nível e podappendtail com offsetsbulk: pod enamespaceadicionados
4

4 passos — reproduza para seguir o fluxo

Como funciona

6 passos

Contêiner auxiliar ao lado da aplicação.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

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

    loggerFile grava uma linha JSON completa por evento no arquivo do volume compartilhado; o envelope (timestamp, level, service, correlationId, message) nunca é sobrescrito por um campo

  2. 02

    O Fluent Bit roda como segundo container do pod (network_mode: service:app e o mesmo volume) e faz tail do arquivo

  3. 03

    O parser payments_json extrai os campos e usa o timestamp da linha como horário do evento, não o horário da leitura

  4. 04

    O filtro modify adiciona pod e namespace, que no Kubernetes vêm da downward API

  5. 05

    O output es envia ao índice payments-logs, com mapping strict aplicado por template antes da primeira linha

  6. 06

    O DB do tail guarda o offset: reiniciado, o sidecar continua de onde parou; trocar o backend é mudar só fluent-bit.conf

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

  • A aplicação não conhece backend, cliente nem retry de log

  • Trocar Elasticsearch por Loki muda só a config do sidecar

  • Metadados do pod adicionados fora do código

  • Offsets evitam reenvio após restart do sidecar

Custos

  • Um container a mais por pod: CPU e memória multiplicados pelas réplicas

  • Arquivo em disco é mais um ponto de falha que o stdout

  • Aplicação e sidecar precisam concordar no formato da linha

  • Linha escrita com o sidecar fora chega com atraso

apps/observability/sidecar

10 arquivos

src/

  • payments_api.tsAPI de pagamentos (Elysia): liquida PIX e grava o log em arquivo
  • logger_file.tsEnvelope da linha e escrita por append
  • pix_settlement.tsFluxo do PIX com marcos de início e fim e erro detalhado
  • elasticsearch_logs.tsTemplate do índice, busca por correlationId e agregações
  • config_sidecar.tsConfiguração validada do ambiente
  • demo.tsdemoEnvia PIX à API e consulta o que o sidecar entregou

sidecar/

  • fluent-bit.confTail com offsets, enriquecimento e output para o Elasticsearch
  • parsers.confParser JSON com o horário da própria linha

elasticsearch/

  • payments-logs-template.jsoninfraMapping strict do índice de logs

./

  • docker-compose.ymlinfraPod (API + sidecar) e Elasticsearch

Executar · com Docker

  1. cp .env.example .env# variáveis de ambiente
  2. bun install# dependências
  3. docker compose up -d --wait# sobe Elasticsearch · Fluent Bit
  4. bun run demo# roda o cenário
  5. bun run test# integração contra o serviço real
Requisitos
BunDocker
Sobe junto
ElasticsearchFluent Bit

Relações

Onde ele se encaixa

Mapa
  1. Sidecar
  • Combina com3
  • Alternativa a1

Também implementado em

Por que se relacionam

Combina com

Alternativa a

Teste rápido

Qual destes combina com Sidecar?

Próximo projeto · Observabilidade & OperaçõesAmbassador
Esc

↑ ↓ navegarEnter abrir191 resultados