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

Découvrez des solutions aux problèmes ClickHouse les plus courants, notamment les requêtes lentes, les erreurs de mémoire, les problèmes de connexion et les problèmes de configuration.

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.

​

Tables système essentielles

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

​

system.errors

Affiche toutes les erreurs actives sur votre instance ClickHouse.

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

​

system.replicas

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;

​

system.replication_queue

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;

​

system.merges

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;

​

system.parts

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;

​

Problèmes courants en production

​

Problèmes d’espace disque

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.

​

Erreur « Too many parts »

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.

​

Problèmes liés à des timestamps invalides

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.

​

Risques liés aux opérations ALTER

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.

​

Mémoire et performances

​

Agrégation externe

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

​

Détails sur async insert

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

​

Configuration des tables distribuées

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

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

​

Référence rapide

Problème	Détection	Solution
Espace disque	Vérifiez le nombre total d’octets dans system.parts	Surveillez l’utilisation, anticipez la mise à l’échelle
Too Many Parts	Comptez le nombre de parts par table	Effectuez des insertions par lots, activez async_insert
Retard de réplication	Vérifiez le délai dans system.replicas	Surveillez le réseau, redémarrez les répliques
Données erronées	Validez les dates de partition	Mettez en place une validation des timestamps
Mutations bloquées	Vérifiez l’état de system.mutations	Testez d’abord sur un petit volume de données

​

Vidéos

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