Leçons - retours d’expérience en débogage

Ce guide fait partie d’une série de retours d’expérience issus des meetups de la communauté. Pour découvrir d’autres solutions et enseignements concrets, vous pouvez parcourir les contenus par type de problème. Vos coûts d’exploitation sont trop élevés ? Consultez le guide communautaire sur l’optimisation des coûts.

Ces tables système sont indispensables au débogage en production :

Affiche toutes les erreurs actives sur votre instance ClickHouse.

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

Contient des informations sur le retard de réplication et le statut, pour surveiller la santé du 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;

Fournit des informations détaillées pour le diagnostic des problèmes de réplication.

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

Affiche les opérations de fusion en cours et permet d’identifier les processus bloqués.

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

Indispensable pour surveiller le nombre de parts et repérer les problèmes de fragmentation.

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

L’épuisement de l’espace disque dans des configurations répliquées entraîne des problèmes en cascade. Lorsqu’un nœud manque d’espace, les autres continuent d’essayer de se synchroniser avec lui, ce qui provoque des pics de trafic réseau et des symptômes trompeurs. Un membre de la communauté a passé 4 heures en débogage alors qu’il s’agissait simplement d’un manque d’espace disque. Consultez cette requête pour surveiller votre stockage sur disque sur un cluster donné.

Si vous utilisez AWS, sachez que les volumes EBS à usage général par défaut ont une limite de 16 To.

De petites insertions fréquentes entraînent des problèmes de performances. La communauté a constaté que des taux d'insertion supérieurs à 10 par seconde déclenchent souvent des erreurs « Too many parts », car ClickHouse ne peut pas fusionner les parts assez rapidement.

Solutions :

• Regroupez les données en lots avec des seuils de 30 secondes ou 200 Mo
• Activez async_insert pour le batching automatique
• Utilisez des tables Buffer pour le batching côté serveur
• Configurez Kafka pour maîtriser la taille des lots

Recommandation officielle : minimum 1 000 lignes par insertion, idéalement de 10 000 à 100 000.

Les applications qui envoient des données avec des timestamps arbitraires créent des problèmes de partitionnement. Cela entraîne la création de partitions contenant des données associées à des dates irréalistes (comme 1998 ou 2050), ce qui provoque un comportement de stockage inattendu.

Les opérations ALTER volumineuses sur des tables de plusieurs téraoctets peuvent consommer beaucoup de ressources et potentiellement verrouiller des bases de données. Dans un exemple partagé par la communauté, le remplacement d’un Integer par un Float sur 14 To de données a verrouillé l’ensemble de la base de données et nécessité une reconstruction à partir de sauvegardes.

Surveillez les mutations coûteuses :

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

Commencez par tester les modifications de schéma sur des jeux de données plus petits.

Activez l’agrégation externe pour les opérations gourmandes en mémoire. Elle est plus lente, mais évite les plantages liés à un manque de mémoire en écrivant les données sur disque. Pour cela, utilisez max_bytes_before_external_group_by, ce qui permet d’éviter les plantages dus à un manque de mémoire lors d’opérations GROUP BY volumineuses. Vous pouvez en savoir plus sur ce paramètre ici.

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

async insert regroupe automatiquement côté serveur les petites insertions afin d’améliorer les performances. Vous pouvez indiquer s’il faut attendre que les données soient écrites sur le disque avant de renvoyer l’accusé de réception — un retour immédiat est plus rapide, mais offre moins de garanties de durabilité. Les versions récentes prennent en charge la déduplication pour gérer les doublons au sein des lots.

Documentation connexe

• Sélectionner une stratégie d’insertion

Par défaut, les tables distribuées utilisent des insertions sur un seul thread. Activez insert_distributed_sync pour permettre un traitement en parallèle et un envoi immédiat des données vers les shards.

Surveillez l’accumulation de données temporaires lors de l’utilisation de tables distribuées.

Seuils de monitoring recommandés par la communauté :

• Nombre de parts par partition : de préférence inférieur à 100
• Insertions retardées : doivent rester à zéro
• Taux d'insertion : à limiter à environ 1 par seconde pour des performances optimales

Documentation associée

• Clé de partitionnement personnalisée

• 10 leçons tirées de l’exploitation de ClickHouse
• INSERTIONS asynchrones rapides, concurrents et cohérents dans ClickHouse