ClickHouse + Grafana dashboards : tutoriel 2026

Une instance ClickHouse remplie d’événements applicatifs sans dashboard Grafana en façade reste invisible aux décideurs et opaque aux opérationnels. Construire les bons tableaux de bord transforme un datawarehouse columnar en outil de pilotage quotidien : suivi des conversions e-commerce en FCFA, surveillance de la santé du cluster, détection des anomalies de trafic. Ce tutoriel montre pas-à-pas comment connecter Grafana à ClickHouse via le plugin officiel, importer le dashboard de monitoring de référence, créer des panels métier sur mesure et activer l’alerting sur les indicateurs critiques.

Le parcours suppose une instance ClickHouse déjà fonctionnelle (en mono-noeud ou en cluster) et une instance Grafana accessible. À la fin, vous disposez d’un dashboard de supervision opérationnelle pour le cluster lui-même, d’un dashboard métier qui agrège les événements applicatifs en KPIs lisibles, et d’une règle d’alerte qui notifie l’équipe quand un indicateur dérive. Les commandes et configurations ont été vérifiées sur la documentation officielle Grafana et sur le plugin ClickHouse Datasource maintenu par Grafana Labs.

📍 Guide principal : ClickHouse 2026 : analytics columnar haute performance — pour les concepts MergeTree et materialized views avant de plonger dans le branchement Grafana.

Pourquoi Grafana plutôt que les outils ClickHouse natifs

ClickHouse expose nativement deux interfaces graphiques minimalistes : la console web Play sur le port 8123, utile pour exécuter des requêtes ad-hoc, et l’interface tabix.io maintenue par la communauté. Aucune des deux ne couvre les besoins d’un dashboard de supervision en production. Grafana apporte trois fonctionnalités absentes : la composition de panels qui combinent plusieurs sources de données (ClickHouse + Prometheus + logs Loki), le partage par lien public ou intégré, et l’alerting unifié qui route les notifications vers Slack, email ou un webhook custom.

La combinaison Grafana + ClickHouse est aujourd’hui standard pour les équipes data ouest-africaines qui veulent un outil de pilotage gratuit et auto-hébergeable. Le plugin officiel grafana-clickhouse-datasource, maintenu par Grafana Labs, supporte les requêtes SQL standards, les variables de dashboard, l’autocomplete des tables et les annotations. Il évolue plusieurs fois par an avec des releases publiées sur le marketplace Grafana, ce qui réduit la dette de maintenance par rapport à un connecteur communautaire.

Prérequis avant de commencer

• Une instance ClickHouse 24.x ou 25.x fonctionnelle, accessible en HTTP (port 8123) ou natif (port 9000) depuis Grafana.
• Un utilisateur ClickHouse dédié à Grafana, en lecture seule sur les bases métier — jamais le compte default avec ses droits étendus.
• Une instance Grafana 11.x ou 12.x récente, en mode self-hosted (Docker, paquet APT, ou via Coolify) ou Grafana Cloud.
• Connectivité réseau ClickHouse ↔ Grafana validée : si les deux sont sur le même VPS, communication via réseau Docker interne ; si Grafana est externe, tunnel SSH ou WireGuard recommandé pour ne pas exposer ClickHouse sur Internet.
• Un navigateur moderne pour la console Grafana et un accès admin pour installer le plugin.

Si l’instance ClickHouse n’est pas encore en place, démarrer par le tutoriel d’installation ClickHouse sur Coolify. Pour une topologie haute disponibilité multi-noeuds, voir le guide cluster ClickHouse + Keeper.

Étape 1 — Créer un utilisateur Grafana en lecture seule sur ClickHouse

Le principe de moindre privilège exige que Grafana ne dispose que des droits strictement nécessaires : lecture sur les bases métier, accès aux tables système d’inspection (system.metrics, system.replicas) pour le dashboard de supervision, aucune permission DDL ni écriture. Cela limite l’impact d’un compromis du compte Grafana sur l’instance ClickHouse.

CREATE USER grafana_ro
IDENTIFIED WITH sha256_password BY 'mot-de-passe-long-aleatoire'
HOST IP '10.0.0.0/8';

CREATE ROLE grafana_reader;

GRANT SELECT ON analytics.* TO grafana_reader;
GRANT SELECT ON system.metrics TO grafana_reader;
GRANT SELECT ON system.events TO grafana_reader;
GRANT SELECT ON system.asynchronous_metrics TO grafana_reader;
GRANT SELECT ON system.replicas TO grafana_reader;
GRANT SELECT ON system.parts TO grafana_reader;

GRANT grafana_reader TO grafana_ro;

Ajustez la base analytics selon votre nommage et la plage IP 10.0.0.0/8 selon votre réseau privé. Pour une instance Grafana derrière un reverse proxy public, restreindre encore davantage avec l’IP exacte du serveur Grafana. Vérifiez la création avec SHOW USERS et SHOW GRANTS FOR grafana_ro — la sortie doit lister les SELECT accordés. Si une erreur survient sur sha256_password, votre version ClickHouse est trop ancienne et ne supporte que plaintext_password ou double_sha1_password — les deux fonctionnent, ajustez la syntaxe.

Étape 2 — Installer le plugin grafana-clickhouse-datasource

Le plugin officiel se télécharge depuis le marketplace Grafana. Pour une installation Grafana en self-hosted, deux méthodes selon votre déploiement : la commande CLI grafana-cli sur une installation paquet, ou via la console web pour Grafana Cloud et les setups Docker récents. La méthode CLI reste la plus reproductible pour les playbooks Ansible et les déploiements automatisés.

sudo grafana-cli plugins install grafana-clickhouse-datasource
sudo systemctl restart grafana-server

Le plugin se télécharge depuis grafana.com, s’installe dans /var/lib/grafana/plugins/ et nécessite un redémarrage du service pour être chargé. Vérifiez l’installation en allant dans Connections → Data sources → Add data source dans la console Grafana : « ClickHouse » doit apparaître dans la liste avec un badge officiel. Si le plugin n’apparaît pas, vérifiez les logs Grafana avec journalctl -u grafana-server -f — un permission denied sur le répertoire plugins est le problème classique.

Étape 3 — Configurer la datasource ClickHouse dans Grafana

La datasource encapsule la connexion à votre instance ClickHouse : URL, port, identifiants, paramètres TLS. Plusieurs datasources peuvent coexister si vous avez plusieurs clusters (production, staging, analytics). Nommez chacune explicitement pour éviter les confusions lors de la création de panels.

Dans Connections → Data sources → ClickHouse, créez une nouvelle datasource ClickHouse Production. Renseignez :

• Server address : nom DNS interne ou IP du serveur ClickHouse (par exemple ch-main dans un setup Coolify, ou 10.0.0.5 en réseau privé)
• Server port : 9000 pour le protocole natif (recommandé pour la performance) ou 8123 pour le protocole HTTP
• Protocol : Native ou HTTP selon le port choisi
• TLS / SSL : activer si Grafana et ClickHouse communiquent via Internet ; désactiver si réseau privé
• User : grafana_ro créé à l’étape 1
• Password : le mot de passe long généré
• Default database : analytics ou la base principale

Cliquez Save & Test. Le plugin teste la connexion et exécute une requête de validation contre les tables système. Un succès affiche « Data source is working ». Les erreurs les plus fréquentes sont une mauvaise IP source autorisée par le HOST IP côté ClickHouse (Étape 1), un firewall qui bloque le port natif 9000, ou un mot de passe mal copié. Inspectez les logs journalctl -u clickhouse-server pour voir si la tentative de connexion arrive jusqu’au serveur.

Étape 4 — Importer le dashboard ClickHouse de référence (ID 14192)

Avant de construire vos propres panels, importez le dashboard officiel « ClickHouse internal exporter metrics » publié par Grafana Labs sous l’identifiant 14192. Il fournit immédiatement la supervision de base : QPS, latence des requêtes, occupation disque, files de réplication, mémoire, parts par table. C’est le bon point de départ pour ne pas réinventer la roue.

Dans Dashboards → New → Import, saisissez l’identifiant 14192 et cliquez Load. Grafana télécharge le JSON depuis grafana.com, vous demande de mapper la datasource sur le menu déroulant à votre nouvelle ClickHouse Production, puis crée le dashboard dans votre dossier par défaut. L’ouverture du dashboard charge les métriques en quelques secondes — toutes les visualisations doivent afficher des données. Si plusieurs panels sont vides, vérifiez que le rôle grafana_reader a bien les SELECT sur les tables système.

Ce dashboard utilise le datasource pour interroger directement les tables système ClickHouse, sans Prometheus intermédiaire. C’est plus simple à câbler mais moins flexible qu’une supervision via l’endpoint Prometheus de ClickHouse plus Grafana. Pour la corrélation logs-métriques-traces, voir le tutoriel sur la corrélation Grafana.

Étape 5 — Créer un panel métier sur les conversions e-commerce

Les dashboards de supervision livrent l’infra ; les dashboards métier livrent la valeur business. Construisons un panel qui agrège un funnel de conversion e-commerce sur 30 jours en FCFA, calculé sur la table analytics.events de votre application. Le SQL est strict ClickHouse — le plugin Grafana ne fait aucune traduction par-dessus.

SELECT
    toStartOfDay(event_time) AS day,
    countIf(event_type = 'product_view') AS views,
    countIf(event_type = 'add_to_cart') AS carts,
    countIf(event_type = 'purchase') AS purchases,
    sumIf(toUInt64OrZero(JSONExtractString(properties, 'amount')), event_type = 'purchase') AS revenue_xof
FROM analytics.events
WHERE event_time >= now() - INTERVAL 30 DAY
GROUP BY day
ORDER BY day;

Dans Dashboards → New → Add visualization, sélectionnez la datasource ClickHouse, collez la requête, choisissez le type « Time series » pour les 4 séries et « Stat » pour le total revenue. Donnez un nom explicite (Funnel conversion 30j FCFA) et sauvegardez. Le panel se rafraîchit automatiquement selon l’intervalle configuré au niveau dashboard. Pour rendre le panel interactif, ajoutez une variable de plage temporelle en haut du dashboard, ce qui évite de dupliquer le dashboard pour chaque période d’analyse.

Étape 6 — Activer l’alerting sur un indicateur critique

Un dashboard qu’on regarde une fois par mois ne sert pas à grand-chose. L’alerting transforme la supervision passive en pilotage actif : Grafana exécute périodiquement la requête, compare au seuil défini, et notifie les bons canaux quand le seuil est dépassé. Pour ClickHouse, deux alertes essentielles couvrent 80 % des incidents : retard de réplication anormal et erreur de requête en hausse.

Dans le panel « Replication delay » du dashboard 14192, cliquez sur le menu du panel puis Alert → New alert rule. Configurez :

• Name : ClickHouse replication delay haut
• Query : la même que le panel — sur system.replicas.absolute_delay
• Condition : when last() of A is above 60 (secondes)
• Evaluation : every 1m for 5m (déclenche après 5 minutes consécutives au-dessus du seuil)
• Notifications : route vers le contact point Slack ou email préalablement configuré dans Alerting → Contact points

Sauvegardez et faites un test manuel en déclenchant volontairement une bascule sur un noeud (arrêt du service ClickHouse pendant 5 minutes). L’alerte doit passer en état Firing, la notification arrive sur Slack, et la résolution se fait automatiquement quand le replica rattrape son retard. Documentez chaque alerte dans un runbook avec procédure de réponse — une alerte sans runbook finit ignorée.

Erreurs fréquentes et débuggage

Adaptation au contexte ouest-africain

Pour une équipe basée à Dakar, Abidjan ou Bamako qui consulte Grafana au quotidien, la latence de chargement des dashboards dépend de l’emplacement de Grafana. Une instance Grafana hébergée sur le même VPS Hetzner que ClickHouse charge en moins d’une seconde même via une 4G correcte. Une instance Grafana Cloud aux US ou en Asie ajoute 200 à 400 ms de latence sur chaque interaction — c’est sensible pour les utilisateurs qui ouvrent plusieurs dashboards par jour.

Le coût est marginal côté Grafana self-hosted : le service tient sur le même VPS que ClickHouse sans surcoût notable, soit sous les 7 EUR par mois (≈ 4 500 FCFA) sur Hetzner CX32. Grafana Cloud propose un free tier généreux qui suffit pour démarrer sans abonnement payant. Pour la stack data complète, le guide stack data 2026 détaille les choix de référence pour les PME.

Pour étoffer le tableau

Cette configuration couvre la supervision technique et le pilotage métier de base. Trois extensions naturelles selon les besoins : ajouter Prometheus pour la supervision OS et applicative en complément des métriques ClickHouse natives ; ajouter Loki pour centraliser les logs des serveurs et corréler avec les pics de trafic visibles dans ClickHouse ; ajouter un système d’embedding et de recherche sémantique pour les utilisateurs business qui formulent des questions en langage naturel sur les données. Pour comparer ClickHouse à d’autres moteurs avant de commiter, voir le comparatif ClickHouse vs PostgreSQL vs BigQuery.

Mots-clés associés : Grafana 12, plugin ClickHouse datasource, dashboard 14192, Grafana Labs, alerting unifié, system.replicas, materialized views, KPI FCFA, supervision PME.