Pular para conteúdo

Acervo original preservado

Este conteúdo histórico pode conter propostas ou instruções anteriores ao checkout atual. Consulte Arquitetura para o comportamento documentado e Tutoriais para as ressalvas operacionais.

Ambiente e limites da evidência histórica

Configurações e medições locais não comprovam ambientes corporativos. Propostas e menções históricas a produção não foram verificadas em DEV, STAGING ou PROD. Consulte Ambientes corporativos para o que está confirmado.

Arquitetura de Billing e Consumo do Gateway

Objetivo

Implementar uma arquitetura para coleta, armazenamento e agregação de métricas de consumo do Gateway com foco em:

  • Billing por tenant
  • Relatórios de utilização
  • Métricas operacionais
  • Evolução futura para modelos de cobrança baseados em consumo

Fluxo de Execução

Cliente
    ↓
Broker
    ↓
Builder (monta request)
    ↓
Broker
    ↓
Router
    ↓
API Destino
    ↓
Router
    ↓
Broker
    ↓
Builder (transformações de resposta)
    ↓
Broker
    ↓
Cliente

Ponto de Geração do UsageEvent

Decisão

O UsageEvent será gerado pelo Broker após receber a resposta final processada pelo Builder e imediatamente antes da devolução ao cliente.

Builder
 ↓
Broker
 ↓
Publica UsageEvent
 ↓
Cliente

arquitetura_billing_usage_collect

Justificativa

Billing deve representar o consumo real do Gateway e não apenas a chamada realizada ao backend.

O Broker é o único componente que possui visão completa da execução da requisição.

Ele possui conhecimento sobre:

  • Tenant responsável pela chamada
  • Gateway utilizado
  • Rota utilizada
  • Tempo total de processamento
  • Transformações aplicadas na requisição
  • Transformações aplicadas na resposta
  • Status final entregue ao consumidor
  • Payload final entregue ao consumidor

Gerar o evento neste ponto garante que os dados de consumo representem exatamente o comportamento observado pelo cliente.

Responsabilidades dos Componentes

Router

Responsável por:

  • Executar a chamada HTTP
  • Medir tempo do backend
  • Capturar status original
  • Capturar tamanho da resposta original

Exemplos:

backendStatusCode
backendDurationMs
backendResponseBytes

Builder

Responsável por:

  • Transformações de request
  • Transformações de response
  • Alterações de headers
  • Alterações de status
  • Alterações de payload

Broker

Responsável por:

  • Orquestração completa da execução
  • Consolidação das informações
  • Cálculo do tempo total da operação
  • Publicação do UsageEvent

Fluxo de Billing

Broker
 ↓
RabbitMQ
 ↓
gateway-usage-collector
 ↓
ClickHouse

Estrutura Recomendada do Evento

{
  "eventId": "uuid",
  "timestamp": "2026-06-01T13:30:00Z",

  "tenantId": "tenant-123",
  "gatewayId": "gw-abc",
  "routeId": "route-xyz",

  "method": "GET",
  "pathTemplate": "/customers/{id}",

  "backendStatusCode": 200,
  "finalStatusCode": 200,

  "backendDurationMs": 87,
  "totalDurationMs": 124,

  "requestBytes": 512,
  "backendResponseBytes": 2048,
  "finalResponseBytes": 1800,

  "requestTransformApplied": true,
  "responseTransformApplied": true
}

Serviço gateway-usage-collector

Responsabilidades:

  • Consumir eventos do RabbitMQ
  • Validar payload
  • Persistir eventos
  • Alimentar estruturas analíticas
  • Realizar enriquecimentos futuros
  • Implementar deduplicação quando necessário

Persistência

Decisão

Utilizar ClickHouse como banco oficial para armazenamento dos eventos de consumo.

MongoDB continuará sendo utilizado para armazenamento operacional do Gateway.

MongoDB

Responsável por:

  • Gateways
  • Rotas
  • Políticas
  • Configurações
  • Planos de billing
  • Regras de cobrança

Representa:

O que o gateway é.

ClickHouse

Responsável por:

  • Eventos de consumo
  • Billing
  • Analytics
  • Métricas
  • Relatórios

Representa:

Como o gateway foi utilizado.

Justificativa para Utilização do ClickHouse

Os eventos de billing possuem características muito específicas:

  • Alto volume de escrita
  • Dados imutáveis
  • Modelo append-only
  • Consultas analíticas
  • Agregações por período

Exemplos de consultas esperadas:

  • Quantidade de chamadas por tenant
  • Quantidade de chamadas por gateway
  • Quantidade de chamadas por rota
  • Consumo por dia
  • Consumo por mês
  • Latência média
  • Percentis de latência
  • Volume trafegado

Essas consultas são executadas através de:

COUNT
SUM
AVG
GROUP BY
FILTER BY TIME RANGE

O ClickHouse foi projetado exatamente para esse tipo de workload.

Benefícios:

  • Excelente compressão
  • Baixo custo de armazenamento
  • Consultas extremamente rápidas
  • Materialized Views nativas
  • Escalabilidade para bilhões, trilhões, quadrilhões... de eventos
  • Excelente desempenho em agregações

Billing é um problema analítico e não transacional.

Por esse motivo ClickHouse se encaixa melhor que MongoDB para essa necessidade.

Por que não utilizar OpenTelemetry como Base de Billing

Decisão

OpenTelemetry continuará sendo utilizado para observabilidade da plataforma, mas não será utilizado como fonte oficial de billing.

Motivos

Objetivo diferente

OpenTelemetry foi criado para:

  • Tracing distribuído
  • Métricas operacionais
  • Observabilidade
  • Troubleshooting

Billing possui requisitos diferentes:

  • Persistência de longo prazo
  • Auditoria
  • Rastreabilidade financeira
  • Consistência dos dados

Dados podem ser amostrados

Em muitas implementações de OpenTelemetry são aplicadas estratégias de sampling.

Exemplo:

1 em cada 10 requisições
1 em cada 100 requisições

Isso é aceitável para observabilidade.

Não é aceitável para cobrança.

Acoplamento indevido

Misturar billing e observabilidade cria dependência entre domínios distintos.

Problemas em tracing não devem impactar cobrança.

Problemas em cobrança não devem impactar observabilidade.

Estratégia de Falha

Fase 1

Broker
 ↓
RabbitMQ
 ↓
Usage Collector
 ↓
ClickHouse

Utilizando:

  • Fail-Open
  • Eventos brutos
  • Sem buffer persistente

Evoluções Futuras

Fase 2

Implementar Fail-Buffered:

Broker
 ↓
billing_pending_events
 ↓
Retry Worker
 ↓
RabbitMQ

Fase 3

Adicionar:

  • Retry automático
  • Dead Letter Queue
  • Observabilidade
  • Métricas de perda de eventos
  • Deduplicação avançada

Agregação

Utilizar Materialized Views do ClickHouse.

gateway_usage_events
        ↓
Materialized View
        ↓
gateway_usage_hourly

O gateway-usage-collector será responsável apenas pela gravação dos eventos brutos.

Conclusão

A solução proposta mantém separação clara entre responsabilidades:

Gateway

Responsável por:

  • Processamento da requisição
  • Consolidação dos dados de consumo
  • Publicação dos eventos

Usage Collector

Responsável por:

  • Persistência
  • Processamento analítico
  • Evolução futura de billing

ClickHouse

Responsável por:

  • Armazenamento dos eventos
  • Agregações
  • Consultas analíticas
  • Relatórios

OpenTelemetry

Responsável por:

  • Observabilidade
  • Tracing
  • Troubleshooting

A separação entre billing e observabilidade reduz acoplamento, aumenta a confiabilidade da cobrança e permite que cada tecnologia seja utilizada para o problema para o qual foi projetada.

Spike comparativo

Minha posição técnica continua sendo: OpenTelemetry pode transportar um evento estruturado, mas não deveria ser o mecanismo oficial de publicação de eventos financeiros. O próprio projeto define OTel como um framework para geração, coleta e exportação de telemetria — traces, métricas e logs. Os chamados Events do OTel são representados pelo modelo de logs, não como mensagens de domínio com garantia financeira