Lições - insights de depuração - ClickHouse Documentation

Este guia faz parte de uma coleção de aprendizados obtidos em encontros da comunidade. Para ver mais soluções e insights práticos, você pode navegar por problema específico. Sofrendo com altos custos operacionais? Confira o guia de insights da comunidade sobre Otimização de Custos.

Tabelas de sistema essenciais

Estas tabelas de sistema são fundamentais para a depuração de problemas em produção:

system.errors

Exibe todos os erros ativos na sua instância do ClickHouse.

SELECT name, value, changed 
FROM system.errors 
WHERE value > 0 
ORDER BY value DESC;

system.replicas

Contém informações sobre atraso de replicação e status para monitorar a integridade do cluster.

SELECT database, table, replica_name, absolute_delay, queue_size, inserts_in_queue
FROM system.replicas 
WHERE absolute_delay > 60
ORDER BY absolute_delay DESC;

system.replication_queue

Fornece informações detalhadas para ajudar a diagnosticar problemas de replicação.

SELECT database, table, replica_name, position, type, create_time, last_exception
FROM system.replication_queue 
WHERE last_exception != ''
ORDER BY create_time DESC;

system.merges

Mostra as operações de merge em andamento e pode ajudar a identificar processos travados.

SELECT database, table, elapsed, progress, is_mutation, total_size_bytes_compressed
FROM system.merges 
ORDER BY elapsed DESC;

system.parts

Essencial para monitorar a quantidade de partes e identificar problemas de fragmentação.

SELECT database, table, count() as part_count
FROM system.parts 
WHERE active = 1
GROUP BY database, table
ORDER BY count() DESC;

Problemas comuns em ambientes de produção

Problemas de espaço em disco

O esgotamento do espaço em disco em configurações replicadas gera problemas em cascata. Quando um nó fica sem espaço, os outros nós continuam tentando se sincronizar com ele, causando picos no tráfego de rede e sintomas confusos. Um membro da comunidade passou 4 horas depurando um problema que, na verdade, era apenas falta de espaço em disco. Confira esta consulta para monitorar o armazenamento em disco em um cluster específico. Se você estiver usando AWS, saiba que os volumes EBS de uso geral padrão têm um limite de 16 TB.

Erro “Too many partes”

Inserções pequenas e frequentes causam problemas de desempenho. A comunidade identificou que taxas de inserção acima de 10 por segundo frequentemente acionam erros “too many partes”, porque o ClickHouse não consegue mesclar as partes com rapidez suficiente. Soluções:

Agrupe os dados em lotes usando limites de 30 segundos ou 200 MB
Ative async_insert para agrupamento automático em lotes
Use tabelas de buffer para agrupamento em lotes no lado do servidor
Configure o Kafka para tamanhos de lote controlados

Recomendação oficial: no mínimo 1.000 linhas por inserção, idealmente entre 10.000 e 100.000.

Problemas com timestamps inválidos

Aplicações que enviam dados com timestamps arbitrários geram problemas de partição. Isso resulta em partições com dados de datas irreais (como 1998 ou 2050), causando comportamento inesperado no armazenamento.

Riscos da operação `ALTER`

Operações ALTER grandes em tabelas com vários terabytes podem consumir muitos recursos e até bloquear bancos de dados. Em um exemplo da comunidade, a mudança de um Integer para um Float em 14 TB de dados bloqueou todo o banco de dados e exigiu a reconstrução a partir de backups. Monitore mutações custosas:

SELECT database, table, mutation_id, command, parts_to_do, is_done
FROM system.mutations 
WHERE is_done = 0;

Teste primeiro as alterações de schema em conjuntos de dados menores.

Memória e desempenho

Agregação externa

Ative a agregação externa para operações com uso intensivo de memória. Ela é mais lenta, mas evita falhas por falta de memória ao gravar dados em disco. Você pode fazer isso usando max_bytes_before_external_group_by, o que ajuda a evitar falhas por falta de memória em operações GROUP BY de grande volume. Saiba mais sobre essa configuração aqui.

SELECT 
    column1,
    column2,
    COUNT(*) as count,
    SUM(value) as total
FROM large_table
GROUP BY column1, column2
SETTINGS max_bytes_before_external_group_by = 1000000000; -- limite de 1 GB

Detalhes do async insert

O async insert agrupa automaticamente pequenos inserts no servidor para melhorar o desempenho. Você pode configurar se deve esperar que os dados sejam gravados em disco antes de retornar a confirmação — o retorno imediato é mais rápido, mas menos durável. Versões mais recentes oferecem suporte à desduplicação para lidar com dados duplicados nos lotes. Documentação relacionada

Selecionar uma estratégia de insert

Configuração de tabela distribuída

Por padrão, tabelas distribuídas usam inserções em thread única. Habilite insert_distributed_sync para processamento paralelo e envio imediato de dados para os shards. Monitore o acúmulo temporário de dados ao usar tabelas distribuídas.

Limiares de monitoramento de desempenho

Limiares de monitoramento recomendados pela comunidade:

Partes por partição: de preferência, menos de 100
Inserções atrasadas: devem se manter em zero
Taxa de inserção: limite a cerca de 1 por segundo para um desempenho ideal

Documentação relacionada

Chave de particionamento personalizada

Referência rápida

Problema	Detecção	Solução
Espaço em disco	Verifique o total de bytes em `system.parts`	Monitore o uso e planeje a escalabilidade
Muitas partes	Conte as partes por tabela	Agrupe inserções em lote e habilite `async_insert`
Atraso de replicação	Verifique o atraso em `system.replicas`	Monitore a rede e reinicie as réplicas
Dados inválidos	Valide as datas da partição	Implemente a validação de timestamp
Mutações travadas	Verifique o status em `system.mutations`	Teste primeiro com poucos dados

​Tabelas de sistema essenciais

​system.errors

​system.replicas

​system.replication_queue

​system.merges

​system.parts

​Problemas comuns em ambientes de produção

​Problemas de espaço em disco

​Erro “Too many partes”

​Problemas com timestamps inválidos

​Riscos da operação ALTER

​Memória e desempenho

​Agregação externa

​Detalhes do async insert

​Configuração de tabela distribuída

​Limiares de monitoramento de desempenho

​Referência rápida

​Vídeos