Surveillance et alertes ClickHouse
ClickHouse lui-même et son sidecar de sauvegarde exposent chacun des métriques Prometheus, désactivées par défaut. Le sidecar de sauvegarde mérite l'attention plus approfondie ci-dessous : sa boucle de surveillance réessaie une sauvegarde échouée au prochain tick planifié au lieu de s'arrêter, de sorte qu'un échec persistant ne fait jamais planter le conteneur et n'apparaît pas dans le statut du pod (voir Fraîcheur des sauvegardes).
Le ServiceMonitor propre à ClickHouse et celui du sidecar de sauvegarde génèrent chacun une ressource ServiceMonitor. Si les CRD de Prometheus Operator ne sont pas installés dans le cluster, activer l'un ou l'autre fait échouer l'installation de la release : laissez les deux à false jusqu'à ce qu'ils le soient.
Métriques du serveur ClickHouse
Les métriques propres à ClickHouse (performances des requêtes, utilisation des ressources) sont exposées sur le port standard http-metrics. Deux paramètres contrôlent cela, tous deux à false par défaut :
clickhouse:
metrics:
enabled: true
serviceMonitor:
enabled: true
metrics.enabled active le endpoint des métriques lui-même ; metrics.serviceMonitor.enabled fournit en plus un ServiceMonitor correspondant : les deux sont requis pour obtenir une cible scrapée.
Métriques clés
ClickHouse expose de multiples métriques ; celles ci-dessous sont celles qui correspondent directement à un garde-fou que ce chart configure par défaut (voir Planification et fiabilité et Autres garde-fous), de sorte qu'un dépassement ici signifie qu'un seuil spécifique et connu a été atteint, et non un symptôme à interpréter de zéro.
| Métrique | Type | Signification |
|---|---|---|
ClickHouseErrorMetric_TOO_MANY_SIMULTANEOUS_QUERIES | Counter | Une requête a été rejetée d'emblée pour avoir dépassé clickhouse.serverConfig.maxConcurrentQueries (32 par défaut). ClickHouseMetrics_Query (gauge) suit le nombre actuel de requêtes concurrentes si vous souhaitez surveiller la tendance avant d'y arriver. |
ClickHouseErrorMetric_TIMEOUT_EXCEEDED | Counter | Une requête a été interrompue pour avoir dépassé clickhouse.serverConfig.maxExecutionTime (55 secondes par défaut). |
ClickHouseMetrics_MemoryTracking / ClickHouseErrorMetric_MEMORY_LIMIT_EXCEEDED | Gauge (octets) / Counter | Mémoire actuellement suivie à l'échelle du serveur, et nombre de fois où une requête a été interrompue pour avoir dépassé clickhouse.serverConfig.maxServerMemoryUsageToRamRatio (0.9 de la limite mémoire du pod par défaut). |
ClickHouseAsyncMetrics_MaxPartCountForPartition | Gauge | Le nombre de parts actives de la pire partition parmi toutes les tables. clickhouse.serverConfig.partsToDelayInsert/partsToThrowInsert (1000/3000 par défaut) le vérifient avant d'accepter une insertion dans cette partition. Recommandation propre à ClickHouse : des valeurs au-dessus de 300 indiquent déjà une surcharge. |
ClickHouseProfileEvents_DelayedInserts / ClickHouseProfileEvents_RejectedInserts | Counter | Avertissement précoce (une insertion a été artificiellement ralentie) vs échec dur (une insertion a été rejetée avec Too many parts) pour les mêmes garde-fous parts-par-partition ci-dessus. |
ClickHouseProfileEvents_ExternalAggregationCompressedBytes / ExternalSortCompressedBytes | Counter (octets) | Données cumulées déversées sur disque parce que le GROUP BY/ORDER BY d'une requête a franchi clickhouse.serverConfig.maxBytesRatioBeforeExternalGroupBy/_Sort (0.4 par défaut). Un taux croissant signifie que les requêtes basculent de plus en plus vers le chemin plus lent de déversement sur disque. |
ClickHouseAsyncMetrics_DiskAvailable_default | Gauge (octets) | Espace libre sur le volume de métadonnées. Contrairement au cache du système de fichiers, ce volume ne se dégrade pas gracieusement s'il se remplit (voir Ce qui se passe si ce volume se remplit). |
Traité séparément dans Cache du système de fichiers : ClickHouseProfileEvents_CachedReadBufferReadFromCacheHits/...Misses (les mêmes compteurs derrière la requête SQL de cette page) et ClickHouseMetrics_FilesystemCacheSize/...SizeLimit pour connaître le niveau de remplissage actuel du cache.
Une croissance soutenue de ExternalAggregationCompressedBytes/...SortCompressedBytes ou des augmentations de MEMORY_LIMIT_EXCEEDED indiquent toutes deux que la RAM, et non le CPU, est le véritable goulot d'étranglement de votre charge d'agrégation. Voir Recommandations matérielles pour savoir quand passer du ratio RAM/cœur à usage général de ClickHouse à leur ratio pour entrepôt de données.
Seuils clés
Ceux-ci supposent les valeurs de garde-fous par défaut du chart ci-dessus ; ajustez les nombres littéraux si vous avez personnalisé clickhouse.serverConfig. Critical signifie qu'une requête ou une insertion a déjà échoué à cause de cela ; warning signifie que vous tendez vers un tel échec.
| Condition | Basé sur | Seuil suggéré | Gravité |
|---|---|---|---|
| Une requête a été rejetée pour trop de requêtes concurrentes | ClickHouseErrorMetric_TOO_MANY_SIMULTANEOUS_QUERIES | Toute augmentation | Critical |
| Une requête a été interrompue pour une durée d'exécution trop longue | ClickHouseErrorMetric_TIMEOUT_EXCEEDED | Toute augmentation | Critical |
| Une requête a été interrompue pour avoir dépassé sa limite mémoire | ClickHouseErrorMetric_MEMORY_LIMIT_EXCEEDED | Toute augmentation | Critical |
Une insertion a été rejetée d'emblée (Too many parts) | ClickHouseProfileEvents_RejectedInserts | Toute augmentation | Critical |
| Une insertion est throttlée, mais pas encore rejetée | ClickHouseProfileEvents_DelayedInserts | Toute augmentation | Warning |
| Une partition approche du seuil de délai d'insertion | ClickHouseAsyncMetrics_MaxPartCountForPartition | Au-dessus de 80 % de partsToDelayInsert (800 par défaut) pendant 15 minutes | Warning |
| Les requêtes se déversent de plus en plus sur disque | Taux de ExternalAggregationCompressedBytes + ExternalSortCompressedBytes | Taux non nul soutenu pendant 30 minutes | Warning |
| Le volume de métadonnées devrait se remplir | ClickHouseAsyncMetrics_DiskAvailable_default | predict_linear(...[1d]) < 0 (projection d'atteinte de zéro sous 24 h) | Critical |
Alertes recommandées
Un exemple implémentant les seuils ci-dessus sous forme de PrometheusRule de Prometheus Operator :
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
name: clickhouse
namespace: <namespace>
labels:
release: <your-prometheus-operator-release-label>
spec:
groups:
- name: clickhouse
rules:
- alert: ClickHouseTooManyConcurrentQueries
expr: increase(ClickHouseErrorMetric_TOO_MANY_SIMULTANEOUS_QUERIES[5m]) > 0
for: 1m
labels:
severity: critical
annotations:
summary: 'A query was rejected for exceeding the concurrent query limit'
description: 'clickhouse.serverConfig.maxConcurrentQueries (32 by default) was hit. ClickHouseMetrics_Query shows the current concurrent count if you want to confirm the trend.'
- alert: ClickHouseQueryTimeout
expr: increase(ClickHouseErrorMetric_TIMEOUT_EXCEEDED[5m]) > 0
for: 1m
labels:
severity: critical
annotations:
summary: 'A query was killed for exceeding maxExecutionTime'
description: 'clickhouse.serverConfig.maxExecutionTime is 55 seconds by default. Check slow query logs for what ran long.'
- alert: ClickHouseQueryMemoryLimitExceeded
expr: increase(ClickHouseErrorMetric_MEMORY_LIMIT_EXCEEDED[5m]) > 0
for: 1m
labels:
severity: critical
annotations:
summary: 'A query was killed for exceeding the server memory limit'
description: 'clickhouse.serverConfig.maxServerMemoryUsageToRamRatio is 0.9 by default. ClickHouseMetrics_MemoryTracking shows the server-wide trend leading up to this.'
- alert: ClickHouseInsertRejected
expr: increase(ClickHouseProfileEvents_RejectedInserts[5m]) > 0
for: 1m
labels:
severity: critical
annotations:
summary: "An insert was rejected with 'Too many parts'"
description: 'clickhouse.serverConfig.partsToThrowInsert (3000 by default) was hit for at least one partition. ClickHouseAsyncMetrics_MaxPartCountForPartition shows the worst-case partition if you want to confirm which one.'
- alert: ClickHouseInsertDelayed
expr: increase(ClickHouseProfileEvents_DelayedInserts[5m]) > 0
for: 5m
labels:
severity: warning
annotations:
summary: 'Inserts are being throttled due to a high part count'
description: 'clickhouse.serverConfig.partsToDelayInsert (1000 by default) was hit for at least one partition. Not yet a rejection, but merges are falling behind inserts. Left unaddressed, this trends toward ClickHouseInsertRejected.'
- alert: ClickHouseMaxPartCountApproachingLimit
expr: ClickHouseAsyncMetrics_MaxPartCountForPartition > 800
for: 15m
labels:
severity: warning
annotations:
summary: 'A partition is approaching the insert-delay threshold'
description: 'Above 80% of clickhouse.serverConfig.partsToDelayInsert (1000 by default). Sustained high insert rate outpacing background merges. Consider batching inserts at the source.'
- alert: ClickHouseExternalSpillIncreasing
expr: rate(ClickHouseProfileEvents_ExternalAggregationCompressedBytes[30m]) > 0 or rate(ClickHouseProfileEvents_ExternalSortCompressedBytes[30m]) > 0
for: 30m
labels:
severity: warning
annotations:
summary: 'Queries are spilling GROUP BY/ORDER BY to disk'
description: 'clickhouse.serverConfig.maxBytesRatioBeforeExternalGroupBy/_Sort (0.4 by default) is being crossed repeatedly, a sign these queries are memory-constrained relative to their data volume.'
- alert: ClickHouseMetadataDiskWillFillUp
expr: predict_linear(ClickHouseAsyncMetrics_DiskAvailable_default[1d], 86400) < 0
for: 10m
labels:
severity: critical
annotations:
summary: 'The metadata volume is projected to fill up within 24 hours'
description: 'Unlike the filesystem cache, this volume does not degrade gracefully when full: inserts and merges fail outright. See Metadata volume in the sizing guide.'
ClickHouseInsertRejected et ses choix de seuils reflètent les règles d'alerte de référence propres à clickhouse-operator d'Altinity (ClickHouseRejectedInsert/ClickHouseDelayedInsertThrottling/ClickHouseMaxPartCountForPartition), et le motif predict_linear de ClickHouseMetadataDiskWillFillUp reflète leur règle ClickHouseDiskUsage. Les deux sont ici restreints aux paramètres que ce chart configure réellement. La plupart des autres règles d'Altinity (retard de réplica, sessions ZooKeeper/Keeper, Kafka, tables Distributed) ne s'appliquent pas : ce chart exécute ClickHouse en mono-nœud, sans réplication, Kafka ni sharding.
Métriques du sidecar de sauvegarde
Une sauvegarde échouée ne fait pas planter le conteneur, ne redémarre pas le pod et ne met au rouge aucun indicateur de santé au niveau Kubernetes. Le pod clickhouse peut afficher Running/Ready avec 0 redémarrage alors que les sauvegardes échouent depuis des jours. Le seul moyen fiable de le savoir est de construire des alertes sur les métriques Prometheus ci-dessous.
Endpoint des métriques
Le sidecar de sauvegarde expose des métriques au format Prometheus sur sa propre API REST, sur le port backup-rest (7171), à /metrics. Comme toutes les autres routes de cette API, elle nécessite les mêmes identifiants HTTP Basic Auth que le reste de l'API de sauvegarde (API_USERNAME/API_PASSWORD, voir Prérequis) : un scrape non authentifié obtient un 401.
Pour le vérifier manuellement avant de brancher Prometheus : API_USERNAME/API_PASSWORD sont déjà injectés dans le conteneur clickhouse-backup lui-même (il en a besoin pour appliquer cette même authentification aux requêtes entrantes), il n'est donc pas nécessaire de les extraire séparément du secret :
kubectl exec -n <namespace> <clickhouse-pod> -c clickhouse-backup -- \
sh -c 'curl -s -u "$API_USERNAME:$API_PASSWORD" http://localhost:7171/metrics'
Scraping avec Prometheus Operator
Définissez clickhouse.backup.metrics.enabled: true pour que le chart fournisse automatiquement un ServiceMonitor correspondant au port backup-rest : il source à la fois le nom d'utilisateur et le mot de passe depuis le même secret clickhouse-credentials déjà utilisé ailleurs (voir Prérequis) :
clickhouse:
backup:
metrics:
enabled: true
Métriques clés
Chaque tick planifié (complet ou incrémentiel) s'exécute comme une opération create_remote, que la sauvegarde complète de ce jour déclenche aussi ou non un rebase (voir Comprendre le planning de sauvegarde) :
| Métrique | Type | Signification |
|---|---|---|
clickhouse_backup_last_create_remote_status | Gauge | 0=échec, 1=succès, 2=inconnu. Le résultat de la dernière tentative de sauvegarde planifiée, complète ou incrémentielle. |
clickhouse_backup_last_create_remote_finish | Gauge (timestamp unix) | Timestamp de la dernière tentative, succès ou échec. Devenir obsolète signifie que la boucle de surveillance elle-même a cessé de ticker, et pas seulement qu'une sauvegarde a échoué. |
clickhouse_backup_successful_create_remotes / clickhouse_backup_failed_create_remotes | Counter | Compteurs cumulés, utiles pour une alerte de taux d'échec sur une fenêtre glissante. |
clickhouse_backup_last_rebase_status / clickhouse_backup_last_rebase_finish | Gauge | Même forme, pour l'étape hebdomadaire rebase qui s'exécute après une sauvegarde complète une fois qu'une chaîne précédente existe déjà. Reste non défini pendant environ les 2 premières semaines après une installation fraîche, car full_type: rebase ne s'applique qu'à partir du deuxième cycle complet. |
clickhouse_backup_in_progress_commands | Gauge | Nombre d'opérations de sauvegarde actuellement en cours. Rester au-dessus de 0 bien plus longtemps qu'une sauvegarde ne prend normalement signifie généralement une opération bloquée. |
clickhouse_backup_number_backups_remote / clickhouse_backup_last_backup_size_remote | Gauge | Nombre de chaînes et taille actuellement sur le stockage distant, une vérification de cohérence basique que le nombre/la taille de la chaîne ne s'est pas effondré de façon inattendue. |
Seuils clés
Ces seuils sont agnostiques des métriques : ils s'appliquent quelle que soit la façon dont les métriques ci-dessus sont collectées, que ce soit Prometheus, Datadog, Grafana Cloud ou toute autre solution de surveillance. Ils supposent le planning par défaut du chart (create_remote quotidien, rebase hebdomadaire) ; ajustez-les si vous avez personnalisé WATCH_SCHEDULES.
| Condition | Basé sur | Seuil suggéré | Gravité |
|---|---|---|---|
| Aucune tentative de sauvegarde (complète ou incrémentielle) récemment | Temps écoulé depuis clickhouse_backup_last_create_remote_finish | Plus de 36 heures (1,5x la cadence quotidienne par défaut) | Critical |
| La dernière tentative de sauvegarde a échoué | clickhouse_backup_last_create_remote_status | Égal à 0 (échec) pendant 15 minutes d'affilée | Critical |
| Aucun rebase de sauvegarde complète hebdomadaire récemment | Temps écoulé depuis clickhouse_backup_last_rebase_finish | Plus de 10 jours (pertinent uniquement une fois qu'un deuxième cycle complet a eu lieu, attendez-vous à ce que ce soit obsolète pendant les deux premières semaines après une installation fraîche) | Warning |
| Une opération de sauvegarde s'exécute depuis trop longtemps | clickhouse_backup_in_progress_commands | Supérieur à 0 pendant 2 heures d'affilée | Warning |
| La sauvegarde distante la plus récente indique une taille nulle | clickhouse_backup_last_backup_size_remote et clickhouse_backup_number_backups_remote | Taille égale à 0 alors qu'au moins une sauvegarde existe déjà à distance | Critical |
Alertes recommandées
Un exemple implémentant les seuils ci-dessus sous forme de PrometheusRule de Prometheus Operator :
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
name: clickhouse-backup
namespace: <namespace>
labels:
release: <your-prometheus-operator-release-label>
spec:
groups:
- name: clickhouse-backup
rules:
- alert: ClickHouseBackupStalled
expr: time() - clickhouse_backup_last_create_remote_finish > 36 * 3600
for: 10m
labels:
severity: critical
annotations:
summary: 'No backup attempt (full or incremental) in over 36 hours'
description: 'The clickhouse-backup sidecar has not attempted a backup in more than 36 hours (1.5x the default daily cadence). The watch loop may have stopped, or its config may be invalid. Pod status will not show this: check the sidecar logs directly.'
- alert: ClickHouseBackupFailing
expr: clickhouse_backup_last_create_remote_status == 0
for: 15m
labels:
severity: critical
annotations:
summary: 'The last backup attempt failed'
description: 'clickhouse_backup_last_create_remote_status is 0 (failed). Check the sidecar logs for the error; clickhouse-backup retries on the next scheduled tick, it does not stop or crash on its own.'
- alert: ClickHouseFullBackupStalled
expr: time() - clickhouse_backup_last_rebase_finish > 10 * 24 * 3600
for: 10m
labels:
severity: warning
annotations:
summary: 'No weekly full-backup rebase in over 10 days'
description: 'Only meaningful once a second full cycle has run. Expect this to be stale for the first two weeks after a fresh install, since full_type: rebase only applies from the second full backup onward.'
- alert: ClickHouseBackupStuck
expr: clickhouse_backup_in_progress_commands > 0
for: 2h
labels:
severity: warning
annotations:
summary: 'A backup operation has been running for over 2 hours'
description: 'clickhouse_backup_in_progress_commands has stayed above 0 for 2 hours straight, longer than a scheduled full or incremental backup normally takes. Check the sidecar logs for a hung operation. Raise the threshold if your data volume makes 2 hours a normal backup duration.'
- alert: ClickHouseBackupSizeZero
expr: clickhouse_backup_last_backup_size_remote == 0 and clickhouse_backup_number_backups_remote > 0
for: 10m
labels:
severity: critical
annotations:
summary: 'The most recent remote backup reports a size of zero'
description: 'At least one backup exists on remote storage, but the most recent one reports 0 bytes, likely a broken or empty backup rather than a real one. Check the sidecar logs and verify the backup with `clickhouse-backup list remote`.'
La fenêtre de 36 heures de ClickHouseBackupStalled est délibérément généreuse (1,5x la cadence par défaut de 24 heures) pour éviter le flapping sur un seul tick retardé, ce qui correspond à la convention que les mainteneurs de clickhouse-backup eux-mêmes utilisent dans leurs règles d'alerte de référence pour le ClickHouse Operator. ClickHouseBackupSizeZero reflète la règle ClickHouseRemoteBackupSizeZero du même ensemble de règles de référence.