Lições - insights de depuração

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.

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

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;

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;

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;

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;

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;

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.

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.

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.

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.

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; -- 1GB threshold

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

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 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

• 10 lições ao operar o ClickHouse
• INSERTS assíncronos rápidos, concorrentes e consistentes no ClickHouse