Resposta-modelo do ADR de migração

Observação: Esta é uma resposta razoável, considerando as restrições específicas do laboratório. Seu ADR pode ser diferente — o importante é que sua justificativa se baseie no estado do ES documentado no Exercício 2A.

ADR: Estratégia de migração de observabilidade (Elasticsearch → ClickHouse)

Autor: Equipe de migração Data: 2026-04-21 Status: Proposto

Contexto

Nossa stack de observabilidade executa Elasticsearch 8.15 + Kibana + Filebeat, com duas cargas de trabalho:

• Carga de trabalho 1 — Logs coletados por agente (Filebeat): 3 fluxos de dados (logs-web_access-lab, logs-application-lab, logs-infrastructure-lab), ~62 milhões de documentos e ~16 GB de armazenamento em shards primários ao longo de 5 dias. Quatro pipelines de ingestão realizam consulta GeoIP, análise de user-agent e syslog com grok e derivação de severidade.
• Carga de trabalho 2 — Microsserviços instrumentados com OTel: 16 serviços da OpenTelemetry Demo, instrumentados com SDKs OTel em 10 linguagens, emitindo traces / métricas / logs OTLP pelo Elastic APM Server para os índices traces-apm-* / logs-apm.* / metrics-apm.*.

Principais dificuldades:

• O custo de armazenamento cresce linearmente — o fluxo hot → warm → delete do ILM é operacionalmente complexo, mas não reduz o custo de fato até a camada cold (que não usamos aqui). Há pressão sobre o heap da JVM pelos índices invertidos em todos os campos.
• Dois caminhos de coleta (Filebeat + agentes do Elastic APM) usam dois esquemas proprietários (ECS vs. OTel) — o dobro da manutenção de esquemas.
• Os alertas do Kibana têm expressividade SQL limitada — sem joins, funções de janela ou agregações profundas.
• Não há controle de custo integrado para campos de alta cardinalidade (remote_addr, trace_id), que são sempre indexados.

Destino: ClickHouse Cloud + HyperDX como interface de observabilidade.

Decisão 1: Abordagem de migração

Escolha: Execução paralela por 2 semanas, seguida de transição em fases por fluxo de dados.

Justificativa:

Uma transição abrupta é arriscada demais — temos 2 regras de alerta ativas que não podem regredir, e nossos dashboards são usados pela equipe de plantão. Uma execução paralela (gravação dupla no ES e no ClickHouse) permite comparar contagens de documentos, executar diariamente verificações de paridade de consultas e testar o destino com tráfego real. Após 7 dias de paridade sem problemas, transferimos um fluxo de dados por vez (logs-infrastructure-lab primeiro — menor volume de consultas e reversão mais fácil), mantendo os dashboards antigos do ES somente para leitura por mais 2 semanas como proteção.

Estratégia de reversão: Falha no destino durante a execução paralela → redirecionar o exportador otlphttp do coletor de volta ao Elastic APM Server; o ES continua recebendo gravações. Falha no destino após a transição, dentro da janela de 2 semanas somente para leitura → trocar a fonte de dados do HyperDX/Grafana do ClickHouse de volta para o ES no fluxo afetado.

Decisão 2: Estratégia de agentes

Escolha: OTel Collector direto para a Carga de trabalho 2 (já nativa); ponte Filebeat → Vector → OTel Collector para a Carga de trabalho 1.

Justificativa:

• A Carga de trabalho 2 já emite OTLP. Basta redirecionar o otelcol-demo da demonstração para um novo pipeline de exportação do ClickHouse — nenhuma reconfiguração de agente.
• Os três geradores de logs da Carga de trabalho 1 já usam Filebeat. Substituir todas as instâncias do Filebeat pelo OTel Collector agora seria uma mudança de alto risco em um pipeline ativo. O Vector é o intermediário seguro: o Filebeat continua enviando ao Vector pela entrada Beats, o Vector transforma os nomes de atributos ECS nas convenções semânticas do OTel (host.hostname → host.name, service → service.name etc.) e emite OTLP adiante. Isso também oferece um ponto para armazenar em buffer e bifurcar o tráfego durante a execução paralela.
• Após a transição completa, podemos desativar o Vector e substituir o Filebeat por um receptor filelog enxuto do OTel Collector em cada host. É uma troca de uma linha e baixo risco após a transição.
• Carga de trabalho 2 (OTel Demo): nenhuma alteração — o otelcol-demo existente recebe um segundo exportador apontando para o ClickHouse (pelo componente contrib clickhouseexporter), além daquele que aponta para o APM Server.

Decisão 3: Estratégia de esquema

Justificativa geral:

Evitamos intencionalmente o padrão de tabela Null + MV aqui. Ele adiciona uma camada de indireção e custo de CPU durante a ingestão, justificáveis apenas ao duplicar um fluxo bruto em vários destinos agregados. Nesta migração, gravamos diretamente no MergeTree de destino; derivações caras (consulta geográfica, regex de user-agent) ficam em colunas materializadas para serem calculadas na inserção e reutilizadas em todas as consultas.

Etapa obrigatória após a criação de otel_traces: o esquema padrão do clickhouseexporter não inclui um índice de salto em TraceId. Sem ele, as buscas por ID de trace (Consulta 5 do Exercício 2B) fariam uma varredura completa. Execute uma vez depois que o exportador criar a tabela:

ALTER TABLE otel_traces ADD INDEX trace_id_bf TraceId TYPE bloom_filter(0.01) GRANULARITY 4;
ALTER TABLE otel_traces MATERIALIZE INDEX trace_id_bf;    -- backfill the index on existing granules

Fazemos o mesmo para SpanId caso as buscas entre spans se tornem um caminho muito acessado.

Evolução do esquema — nossa escolha: Híbrida — Map por padrão, promoção de campos mais usados por revisão periódica.

Por padrão, todos os atributos desconhecidos chegam ao Map LogAttributes / SpanAttributes (comportamento do exportador). Uma vez por sprint, a equipe de plataforma executa a consulta a seguir nos dados da última semana:

SELECT mapKeys(LogAttributes) AS keys, count() AS n
FROM otel_logs ARRAY JOIN mapKeys(LogAttributes) AS key
WHERE Timestamp > now() - INTERVAL 7 DAY
GROUP BY keys
ORDER BY n DESC
LIMIT 50;

Toda chave que (a) aparece em ≥ 30 % das linhas E (b) é referenciada em ≥ 2 dashboards ou alertas é promovida com:

ALTER TABLE otel_logs ADD COLUMN <NewCol> String MATERIALIZED LogAttributes['<key>'];

A promoção é uma decisão da equipe de plataforma (não de cada serviço), para manter o esquema pequeno e consistente.

Por que não promover automaticamente por um gerador de DDL? Executar ALTERs em resposta a sinais da ingestão é arriscado — um atributo ruidoso classificado incorretamente (request_id, UUIDs semelhantes a IDs de trace) vira uma coluna de alta cardinalidade e prejudica a compactação. A cadência com análise humana é uma proteção barata e evita o crescimento involuntário do esquema.

Por que não usar o tipo de coluna JSON? Map(LowCardinality(String), String) é a opção mais antiga e amplamente implantada, com comportamento previsível para os padrões de acesso mapContains / LogAttributes['key']. O tipo JSON pode ter melhor desempenho em escala, mas ainda não o avaliamos nesta carga de trabalho específica. Reconsidere caso o espaço de chaves do Map ultrapasse ~200 chaves distintas, o que começaria a afetar a eficiência do dicionário LowCardinality.

O que isso significa para a Carga de trabalho 2 (OTel Demo): o clickhouseexporter processa atributos dinâmicos de forma nativa — novos atributos de span emitidos por um serviço aparecem em SpanAttributes na primeira vez em que são vistos, sem necessidade de alterar o coletor ou o esquema. O fluxo de promoção é idêntico ao caso dos logs.

Decisão 4: Tradução do pipeline de ingestão

Quais processadores podem ser eliminados por completo? O processador dissect é peso morto. O pipeline set event.ingested é redundante quando usamos uma coluna DEFAULT now(). Isso elimina 2 pipelines da migração.

Decisão 5: Ciclo de vida dos dados

Política ILM atual do ES (lab-observability-policy):

• Hot: rollover aos 5 GB ou 1 dia, prioridade 100
• Warm (aos 2 dias): shrink para 1 shard, forcemerge para 1 segmento, prioridade 50
• Delete: aos 30 dias

Veredito por fase:

Período de retenção: 30 dias (igual ao ES atual).

Cláusula TTL (por tabela):

TTL toDateTime(Timestamp) + INTERVAL 30 DAY DELETE

Justificativa:

Cinco das seis ações do ILM desaparecem. Esta é a maior simplificação operacional da migração — o ILM tinha mais de 200 linhas de política + monitoramento das transições de fase + dashboards do estado dos índices, tudo substituído por uma cláusula TTL por tabela. Acabam os chamados perguntando "por que este índice está preso na fase warm?".

Decisão 6: Migração de alertas

Escolha da ferramenta: Grafana Alerting com a fonte de dados do ClickHouse para ambas as regras.

Justificativa:

• O Grafana tem uma fonte de dados de primeira classe para ClickHouse e um mecanismo de alertas maduro (agendamento, desduplicação, silêncios e roteamento para Slack/PagerDuty). Não precisamos criar um próprio.
• O HyperDX oferece alertas, mas eles têm menos recursos que o Grafana Alerting para regras de limite numérico + janela de tempo.
• MVs pré-calculadas são uma alternativa válida para consultas de alerta caras; nestas duas regras, a consulta é barata, portanto SQL no lado do Grafana é suficiente.

Alta taxa de erros — implementação:

-- Returns a single row IFF 5xx rate exceeded 5% in the last 5 minutes.
SELECT
    countIf(Status >= 500)                     AS errors,
    count()                                     AS total,
    (errors / total) * 100                      AS error_rate_pct
FROM otel_logs_web_access
WHERE Timestamp >= now() - INTERVAL 5 MINUTE
HAVING total > 100                              -- suppress false alerts on low volume
   AND error_rate_pct > 5.0;

Agendamento: Avaliar a cada 1 minuto, aguardando 2 avaliações consecutivas antes de disparar (evita avisos por picos isolados).

Heartbeat do serviço — implementação:

-- Returns one row per service that has emitted no logs in the last 3 minutes.
WITH known_services AS (
    SELECT DISTINCT ServiceName FROM otel_logs_application
    WHERE Timestamp >= now() - INTERVAL 1 DAY
)
SELECT ks.ServiceName AS service
FROM known_services ks
LEFT JOIN (
    SELECT ServiceName, max(Timestamp) AS last_seen
    FROM otel_logs_application
    WHERE Timestamp >= now() - INTERVAL 10 MINUTE
    GROUP BY ServiceName
) recent ON recent.ServiceName = ks.ServiceName
WHERE recent.last_seen IS NULL
   OR recent.last_seen < now() - INTERVAL 3 MINUTE;

Agendamento: Avaliar a cada 1 minuto. Cada linha emitida aciona uma instância de alerta separada, roteada pelo nome do serviço.

Novos recursos possibilitados pelo ClickHouse:

• Joins em consultas de alerta (o Kibana não faz isso). A regra de heartbeat acima une um conjunto de "serviços conhecidos" a um conjunto de "vistos recentemente". No ES, precisaríamos manter a lista de serviços conhecidos separadamente.
• Funções de janela e sequenceMatch para detecção de anomalias complexas — "avisos disparados quando um serviço tem 3 picos consecutivos de 5xx em 10 minutos".
• CTEs + subconsultas — condições de alerta mais sofisticadas sem recorrer a scripts do Watcher.

Decisão 7: Estratégia para dados históricos

Escolha: Começar do zero. O ClickHouse recebe apenas dados novos; o ES permanece somente para leitura por 90 dias, depois é capturado em snapshot e desativado.

Justificativa:

• O valor do histórico de tendências é limitado para esta carga. Logs e traces são usados principalmente na resposta a incidentes (últimas 24 h) e na revisão semanal de tendências. Uma retenção de 30 d é suficiente; 90 d de ES somente para leitura atendem a qualquer necessidade de "consultar o último trimestre" durante a transição.
• O risco das ferramentas de backfill é real. O elasticdump ou um script da API de scroll pode mover ~62 milhões de documentos, mas a desduplicação é frágil — qualquer nova tentativa ou falha parcial introduz duplicatas em otel_logs. Usar ReplacingMergeTree para desduplicar é possível, mas adia o problema e complica a semântica das consultas durante a janela de replay.
• O custo de armazenamento da duplicação de ~62 milhões de documentos é significativo durante a janela de transição e não agrega valor operacional depois que o ES fica somente para leitura.
• A janela de 90 dias com o ES somente para leitura é uma proteção barata. Se descobrirmos uma regressão em um dashboard ou precisarmos de um histórico maior em uma investigação, o ES continuará consultável. O HyperDX aceita várias fontes de dados, permitindo rotear os "últimos 30 dias" ao ClickHouse e consultas mais antigas ao ES de modo transparente.

Plano para o ES somente para leitura:

Se o backfill se tornar necessário mais tarde (plano de contingência):

Reutilize a ponte do Vector da Decisão 2:

elasticdump \
  --input=http://es:9200/logs-web_access-lab \
  --output=http://vector:8686/_bulk \
  --type=data \
  --limit=10000

• Taxa esperada: ~50 mil documentos/s de forma sustentada (o Vector envia lotes ao exportador do ClickHouse).

• Tempo estimado do replay completo: ~62 milhões de documentos ≈ 20 minutos de ponta a ponta.

• Estratégia de desduplicação: ingerir o replay do ES em uma tabela de staging (mesmo esquema de otel_logs) e depois mesclar na tabela ativa com SELECT DISTINCT ON para consolidar linhas de novas tentativas. Simples, sem alterar o mecanismo:

  -- 1. Staging table with the live table's schema
  CREATE TABLE otel_logs_staging AS otel_logs;
  
  -- 2. Re-point Vector at otel_logs_staging and run the elasticdump replay.
  
  -- 3. Merge, keeping one row per identifying tuple
  INSERT INTO otel_logs
  SELECT DISTINCT ON (ServiceName, Timestamp, Body) *
  FROM otel_logs_staging;
  
  DROP TABLE otel_logs_staging;

  Para um replay único de ~62 milhões de linhas em 20 minutos, isso supera um mecanismo de staging ReplacingMergeTree: menos componentes, nenhum momento de mesclagem em segundo plano para coordenar e a chave de desduplicação fica explícita no local do DISTINCT ON.

• Para backfills incrementais ou de maior duração (por exemplo, replay progressivo de meses de dados), uma tabela de staging ReplacingMergeTree com uma coluna de versão MATERIALIZED ContentHash no ORDER BY é a ferramenta adequada — consulte a documentação do ClickHouse sobre ReplacingMergeTree; essa DDL está fora do escopo deste laboratório.

• Verificação de completude: compare as contagens diárias de documentos entre ES (_count com consulta range) e CH (count() WHERE toDate(Timestamp) = ...). Espere uma discrepância ≤ 0,01 % decorrente do momento da ingestão.

Riscos e questões em aberto

• Vector como ponte adiciona um salto e um domínio de falha durante a execução paralela. É aceitável por 2 semanas; queremos desativá-lo antes de declarar a transição completa.
• Cadência de atualização do dicionário GeoIP — o MaxMind GeoLite2 é atualizado semanalmente; precisamos de um job cron/Airflow para obter o CSV mais recente e executar SYSTEM RELOAD DICTIONARY todas as noites.
• Campos de alta cardinalidade (por exemplo, trace.id, remote_addr) — precisamos confirmar o desempenho do filtro de Bloom + índice de salto em uma janela móvel de 30 dias. Planejamos realizar teste de carga com clickhouse-benchmark usando 30× o volume diário atual antes da transição.
• Migração dos dashboards do Kibana → HyperDX/Grafana — o HyperDX ingere esquemas nativos do OTel sem problemas, mas teremos de reconstruir os 6 dashboards manualmente. Orçamento: 1 dia de engenharia por dashboard.
• Modelo de custos no ClickHouse Cloud — precisamos de uma estimativa de dimensionamento baseada no volume após a compactação (redução esperada de ~10×), QPS das consultas e camada de expansão da computação.