Utiliser Grafana et ClickHouse pour l’observabilité

Grafana est l’outil de visualisation privilégié pour les données d’observabilité dans ClickHouse. Cela est rendu possible grâce au plugin ClickHouse officiel pour Grafana. Vous pouvez suivre les instructions d’installation disponibles ici.

La v4 du plugin place les logs et les traces au premier plan grâce à une nouvelle expérience de générateur de requêtes. Cela réduit le besoin, pour les SRE, d’écrire des requêtes SQL et simplifie l’observabilité basée sur SQL, faisant ainsi progresser ce paradigme émergent. Cela passe notamment par le positionnement d’OpenTelemetry (OTel) au cœur du plugin, car nous pensons qu’il constituera le socle de l’observabilité basée sur SQL dans les années à venir, ainsi que de la manière dont les données seront collectées.

Lors de la configuration d'une source de données ClickHouse dans Grafana, le plugin permet de spécifier une base de données et une table par défaut pour les logs et les traces, ainsi que d'indiquer si ces tables sont conformes au schéma OTel. Cela permet au plugin de renvoyer les colonnes nécessaires pour un affichage correct des logs et des traces dans Grafana. Si vous avez modifié le schéma OTel par défaut et préférez utiliser vos propres noms de colonnes, vous pouvez les spécifier. L'utilisation des noms de colonnes OTel par défaut pour des colonnes telles que l'heure (Timestamp), le niveau de log (SeverityText) ou le corps du message (Body) signifie qu'aucune modification n'est nécessaire.

La configuration des logs nécessite une colonne de temps, une colonne de niveau de log et une colonne de message pour que les logs s'affichent correctement.

La configuration des traces est légèrement plus complexe (liste complète ici). Ces colonnes sont requises afin d'abstraire les requêtes ultérieures qui reconstituent un profil de trace complet. Ces requêtes supposent que les données sont structurées de manière similaire à OTel ; les utilisateurs qui s'écartent sensiblement du schéma standard devront donc utiliser des vues pour bénéficier de cette fonctionnalité.

Une fois la configuration terminée, vous pouvez accéder à Grafana Explore et commencer à rechercher des logs et des traces.

Si vous suivez les exigences de Grafana concernant les logs, vous pouvez sélectionner Query Type: Log dans le générateur de requêtes, puis cliquer sur Run Query. Le générateur de requêtes créera une requête pour lister les logs et veillera à ce qu'ils soient affichés, par ex.

SELECT Timestamp as timestamp, Body as body, SeverityText as level, TraceId as traceID FROM "default"."otel_logs" WHERE ( timestamp >= $__fromTime AND timestamp <= $__toTime ) ORDER BY timestamp DESC LIMIT 1000

Le générateur de requêtes permet de modifier facilement la requête, sans avoir à écrire de SQL. Le filtrage, y compris la recherche de logs contenant des mots-clés, peut s’effectuer depuis le générateur de requêtes. Les utilisateurs qui souhaitent écrire des requêtes plus complexes peuvent passer à l’éditeur SQL. Si les colonnes appropriées sont renvoyées et que logs est sélectionné comme type de requête, les résultats s’afficheront sous forme de logs. Les colonnes requises pour l’affichage des logs sont répertoriées ici.

Si les logs contiennent des identifiants de trace, vous pouvez naviguer jusqu’à la trace correspondant à une ligne de log donnée.

À l’instar de la section de journalisation ci-dessus, si les colonnes requises par Grafana pour afficher les traces sont bien présentes (par exemple, avec le schéma OTel), le générateur de requêtes peut formuler automatiquement les requêtes nécessaires. En sélectionnant Query Type: Traces puis en cliquant sur Run Query, une requête semblable à la suivante sera générée et exécutée (selon les colonnes configurées ; l’exemple ci-dessous suppose l’utilisation d’OTel) :

SELECT "TraceId" as traceID,
  "ServiceName" as serviceName,
  "SpanName" as operationName,
  "Timestamp" as startTime,
  multiply("Duration", 0.000001) as duration
FROM "default"."otel_traces"
WHERE ( Timestamp >= $__fromTime AND Timestamp <= $__toTime )
  AND ( ParentSpanId = '' )
  AND ( Duration > 0 )
  ORDER BY Timestamp DESC, Duration DESC LIMIT 1000

Cette requête renvoie les noms de colonnes attendus par Grafana et affiche un tableau de traces, comme indiqué ci-dessous. Il est possible de filtrer sur la durée ou d’autres colonnes sans avoir à écrire de SQL.

Les utilisateurs qui souhaitent écrire des requêtes plus complexes peuvent basculer vers le éditeur SQL.

Comme indiqué ci-dessus, les identifiants de trace s’affichent sous forme de liens cliquables. En cliquant sur un identifiant de trace, l’utilisateur peut choisir d’afficher les spans associés via le lien View Trace. Cela exécute la requête suivante (en supposant des colonnes OTel) pour récupérer les spans dans la structure requise et afficher les résultats sous forme de cascade.

WITH '<trace_id>' AS trace_id,
  (SELECT min(Start) FROM "default"."otel_traces_trace_id_ts"
    WHERE TraceId = trace_id) AS trace_start,
  (SELECT max(End) + 1 FROM "default"."otel_traces_trace_id_ts"
    WHERE TraceId = trace_id) AS trace_end
SELECT "TraceId" AS traceID,
  "SpanId" AS spanID,
  "ParentSpanId" AS parentSpanID,
  "ServiceName" AS serviceName,
  "SpanName" AS operationName,
  "Timestamp" AS startTime,
  multiply("Duration", 0.000001) AS duration,
  arrayMap(key -> map('key', key, 'value',"SpanAttributes"[key]),
  mapKeys("SpanAttributes")) AS tags,
  arrayMap(key -> map('key', key, 'value',"ResourceAttributes"[key]),
  mapKeys("ResourceAttributes")) AS serviceTags
FROM "default"."otel_traces"
WHERE traceID = trace_id
  AND startTime >= trace_start
  AND startTime <= trace_end
LIMIT 1000

Si les logs contiennent des identifiants de trace, vous pouvez passer d’une trace aux logs associés. Pour afficher les logs, cliquez sur un identifiant de trace et sélectionnez View Logs. Cela exécute la requête suivante, en supposant les colonnes OTel par défaut.

SELECT Timestamp AS "timestamp",
  Body AS "body", SeverityText AS "level",
  TraceId AS "traceID" FROM "default"."otel_logs"
WHERE ( traceID = '<trace_id>' )
ORDER BY timestamp ASC LIMIT 1000

Vous pouvez créer des tableaux de bord dans Grafana à l’aide de la source de données ClickHouse. Pour plus de détails, nous vous recommandons de consulter la documentation de Grafana et celle de la source de données ClickHouse, en particulier le concept de macros et les variables.

Le plugin fournit plusieurs tableaux de bord prêts à l’emploi, dont un exemple, « Simple ClickHouse OTel dashboarding », pour les données de logs et de traces conformes à la spécification OTel. Pour l’utiliser, les utilisateurs doivent respecter les noms de colonne OTel par défaut, et il peut être installé depuis la configuration de la source de données.

Vous trouverez ci-dessous quelques conseils simples pour créer des visualisations.

Avec les statistiques, les graphiques linéaires sont la forme de visualisation la plus courante dans les cas d’usage liés à l’observabilité. Le plugin ClickHouse affichera automatiquement un graphique linéaire si une requête renvoie un datetime nommé time et une colonne numérique. Par exemple :

SELECT
 $__timeInterval(Timestamp) as time,
 quantile(0.99)(Duration)/1000000 AS p99
FROM otel_traces
WHERE
 $__timeFilter(Timestamp)
 AND ( Timestamp  >= $__fromTime AND Timestamp <= $__toTime )
GROUP BY time
ORDER BY time ASC
LIMIT 100000

Les graphiques multilignes seront automatiquement affichés pour une requête, à condition que les conditions suivantes soient remplies :

• champ 1 : champ DateTime avec l’alias time
• champ 2 : valeur de regroupement. Cela doit être une String.
• champ 3+ : les valeurs des métriques

Par exemple :

SELECT
  $__timeInterval(Timestamp) as time,
  ServiceName,
  quantile(0.99)(Duration)/1000000 AS p99
FROM otel_traces
WHERE $__timeFilter(Timestamp)
AND ( Timestamp  >= $__fromTime AND Timestamp <= $__toTime )
GROUP BY ServiceName, time
ORDER BY time ASC
LIMIT 100000

Dans les sections précédentes, nous avons vu comment enrichir les données d’observabilité avec des coordonnées géographiques à l’aide de dictionnaires IP. Si vous disposez des colonnes latitude et longitude, vous pouvez visualiser ces données d’observabilité à l’aide de la fonction geohashEncode. Celle-ci génère des geohash compatibles avec le graphique Geo Map de Grafana. Un exemple de requête et de visualisation est présenté ci-dessous :

WITH coords AS
        (
        SELECT
                Latitude,
                Longitude,
                geohashEncode(Longitude, Latitude, 4) AS hash
        FROM otel_logs_v2
        WHERE (Longitude != 0) AND (Latitude != 0)
        )
SELECT
        hash,
        count() AS heat,
        round(log10(heat), 2) AS adj_heat
FROM coords
GROUP BY hash