Verificação somente leitura do disco do ClickHouse® dentro do Langfuse, SigNoz e ClickStack auto-hospedados

O disco enche, mas os seus dados ocupam pouco. Normalmente o espaço vai para as próprias tabelas de log do sistema (system log tables) do ClickHouse, que por padrão não têm limite de tamanho. O diskvet mostra o que está ocupando o disco e imprime os comandos exatos para resolver o problema. Ele não executa nada por conta própria: quem executa cada comando é você.

Início rápido Resolver manualmente: o guia GitHub

Gratuito, Apache-2.0, sem cadastro. São dois arquivos curtos que você pode ler antes de executar. O script se comunica apenas com o seu ClickHouse; nada é enviado para nenhum outro lugar.

A história de sempre

66,86 GiB em system.trace_log contra cerca de 51 MiB nas tabelas do Langfuse (langfuse#13123);
mais de 80 GB em tabelas de log do sistema contra menos de 500 MB de telemetria (SigNoz#12050);
um volume de 10 Gi que encheu em 10 dias (ClickStack-helm-charts#275).

A correção principal é conhecida: fazer TRUNCATE das tabelas de log e adicionar um TTL. O relatório também cobre as armadilhas que aparecem ao aplicar essa correção na prática: o limite de 50 GB para TRUNCATE, as cópias antigas *_log_N que ficam após uma reinicialização, a configuração especial da opentelemetry_span_log, os logs do Docker sem rotação e as linhas excluídas que continuam ocupando espaço.

Início rápido: Langfuse com docker compose (30 segundos)

Na máquina em que o docker-compose.yml do Langfuse é executado:

cd langfuse                     # a pasta com o docker-compose.yml do Langfuse
curl -fsSLO https://github.com/Protemir/diskvet/releases/latest/download/diskvet.sh
curl -fsSLO https://github.com/Protemir/diskvet/releases/latest/download/checks.sql
curl -fsSLO https://github.com/Protemir/diskvet/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS         # opcional: confirma que os dois arquivos correspondem à versão publicada
less checks.sql                 # leia primeiro: apenas SELECTs em system.*

sh diskvet.sh report --docker auto > report.md

--docker auto encontra sozinho o contêiner do ClickHouse e executa o clickhouse-client dentro dele, então você não precisa de um cliente no host nem de uma porta aberta. Sem --user, ele usa as variáveis CLICKHOUSE_USER / CLICKHOUSE_PASSWORD do próprio contêiner, e a senha nunca sai do contêiner.

Outras formas de conectar:

sh diskvet.sh report --docker signoz-clickhouse                          # um contêiner pelo nome
sh diskvet.sh report --host 127.0.0.1 --user diskvet --password '...'   # clickhouse-client local

Requer sh POSIX, awk, sed, od e date, além de docker ou clickhouse-client. Não precisa de jq nem de Python. O script gera o relatório em inglês. A versão mais recente está na página GitHub Releases.

O que o diskvet verifica

#	Verificação	Fontes	Correção típica no relatório
1	Tabelas de log do sistema sem TTL	`system.tables`, `system.parts`	`TRUNCATE` (com a flag de uso único para tabelas acima de 50 GB), um arquivo de TTL pronto para `config.d`, cópias antigas `*_log_N` para remover
2	Espaço em disco fora das partes (parts) das tabelas do ClickHouse	`system.disks` versus todas as partes	rotação dos logs do Docker e onde mais procurar
3	Uso do disco e previsão aproximada	`system.disks`, `system.asynchronous_metric_log`	o que liberar primeiro
4	Crescimento por dia	`system.part_log`	qual tabela gravou mais dados em 24 h
5	Partes demais	`system.parts`, `system.merge_tree_settings`, `system.events`	quanto falta para os limites de inserção da tabela
6	Partes inativas e partes desanexadas (detached)	`system.parts`, `system.detached_parts`	partes travadas, `DROP DETACHED PART`
7	Linhas excluídas e mutações travadas	`system.parts`, `system.mutations`	`APPLY DELETED MASK` para as partições específicas, `KILL MUTATION`

Cada verificação retorna OK, INFO, WARN ou CRITICAL; os limiares estão no README. Cada correção informa o quão segura ela é e se exige reinicialização. Se a consulta de uma verificação falhar, essa verificação mostra NOT_RUN com o motivo; as demais são executadas normalmente.

O que o script lê e o que ele nunca lê

Lê

metadados de system.tables, system.parts, system.disks, system.detached_parts, system.merge_tree_settings, system.mutations, system.part_log, system.asynchronous_metric_log, system.asynchronous_metrics, system.events;
se tiver permissão, system.server_settings (apenas max_table_size_to_drop);
uma consulta de teste, SELECT getSetting('readonly'), para confirmar que a sessão é somente leitura.

Nunca lê

linhas das suas próprias tabelas: nenhum FROM ou JOIN nelas, nenhuma função de tabela, nenhum dictGet; a suíte de testes garante isso;
system.query_log, o texto das consultas, os comandos das mutações ou os textos de erro.

O relatório local mostra os nomes reais dos bancos de dados e das tabelas, porque você precisa deles para aplicar as correções. Ele não sai da sua máquina.

Duas formas seguras de executar

Com um usuário existente. As consultas são executadas com readonly=2 e limites (30 s, 10.000 linhas, 2 threads, 500 MB). Se o servidor recusar o modo somente leitura para esse usuário, o script é interrompido sem executar nada.
Com um usuário dedicado, para auditorias de segurança: permissões restritas às tabelas do sistema listadas acima e nenhum acesso aos dados do produto. O SQL exato está no README.

Testado nas imagens padrão clickhouse/clickhouse-server 24.1, 24.8, 25.12 e 26.9, em instalações parecidas com as do Langfuse e do SigNoz. Ainda não testado: clusters replicados, Kubernetes, discos em armazenamento de objetos, macOS.

Prefere resolver manualmente?

Por que o disco do ClickHouse fica cheio no Langfuse e no SigNoz auto-hospedados e como resolver

Uma consulta somente leitura para confirmar o problema, como liberar o espaço agora e como evitar que o problema volte sem cair nas armadilhas conhecidas. Todos os comandos do guia foram executados no ClickHouse 24.8, 25.12 e 26.9. Você não precisa do diskvet para seguir o guia.

Verificações de hora em hora: beta gratuito em outubro

O script é gratuito e vai continuar gratuito. Mas uma única execução não consegue dizer quando o disco vai realmente ficar sem espaço. É essa a parte que estou desenvolvendo agora:

um snapshot a cada hora: exatamente o JSON que sh diskvet.sh --print-payload imprime, nada mais;
um e-mail antes de o disco encher, só quando algum estado muda;
um alerta quando os snapshots param de chegar;
um relatório curto toda segunda-feira.

Você não precisa hospedar nada nem abrir nenhuma porta: o seu servidor envia um pequeno snapshot assinado, e nada de fora se conecta a ele. Nomes de host, IPs, usuários, textos de consultas e erros nunca são enviados; os nomes das suas próprias tabelas só saem do seu servidor como hashes com salt.

Quer participar? Comente no tópico “Early access” (discussão #1) contando em que ambiente o seu ClickHouse é executado e qual é, mais ou menos, o tamanho do disco. Você pode escrever em português, mas a resposta pode vir em inglês. Quando o beta abrir, você vai receber uma resposta lá mesmo. Por favor, não publique ali nomes de empresas nem de hosts: é um tópico público.

O beta dura 30 dias; depois disso, as verificações de hora em hora passam a ser um plano pago, e o script continua gratuito e de código aberto. Servidores no Cazaquistão: por enquanto, só o relatório local.

Encontrou um problema que o script não detecta, ou uma correção errada? Abra uma issue: é a coisa mais útil que você pode fazer. Você pode escrever em português, mas a resposta pode vir em inglês.