RousselTMLEARNING

Observabilité

La télémétrie dans ClickHouse : schéma, SQL, vues matérialisées et rétention

La télémétrie dans ClickHouse : tables otel_logs, otel_traces, otel_metrics_* et hyperdx_sessions, clés de tri, partitions, codecs, colonnes Map, index de saut, recettes SQL (taux d'erreurs, traces, jointures logs et traces), vues matérialisées, TTL et stockage par niveaux.

1. Les tables #

Ce que le collecteur crée.

Vue d'ensemble #

Disponible dans : ✓ Open source ✓ Managed ClickStack

TableContenuColonnes clés
otel_logslogsTimestamp, ServiceName, SeverityText, Body, TraceId, LogAttributes, ResourceAttributes
otel_tracesspansTraceId, SpanId, ParentSpanId, SpanName, SpanKind, Duration (ns), StatusCode, SpanAttributes, Events.*, Links.*
otel_metrics_gauge, _sum, _histogram, _exponential_histogram, _summarymétriques, une table par typeMetricName, Attributes, TimeUnix, Value (ou buckets)
hyperdx_sessionssessions navigateurévénements de rejeu rattachés à une session

La définition d'une table #

-- Voir la définition réelle d'une table créée par le collecteur
SHOW CREATE TABLE otel_logs;
-- Extrait typique (les versions de l'exportateur font évoluer le détail)
CREATE TABLE otel_logs (
    Timestamp          DateTime64(9) CODEC(Delta(8), ZSTD(1)),
    TimestampTime      DateTime DEFAULT toDateTime(Timestamp),
    TraceId            String CODEC(ZSTD(1)),
    SpanId             String CODEC(ZSTD(1)),
    SeverityText       LowCardinality(String) CODEC(ZSTD(1)),
    ServiceName        LowCardinality(String) CODEC(ZSTD(1)),
    Body               String CODEC(ZSTD(1)),
    ResourceAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1)),
    LogAttributes      Map(LowCardinality(String), String) CODEC(ZSTD(1)),
    INDEX idx_trace_id TraceId TYPE bloom_filter(0.001) GRANULARITY 1,
    INDEX idx_body Body TYPE tokenbf_v1(32768, 3, 0) GRANULARITY 8
) ENGINE = MergeTree
PARTITION BY toDate(TimestampTime)
ORDER BY (ServiceName, TimestampTime, Timestamp)
TTL TimestampTime + INTERVAL 30 DAY;
  • ORDER BY (ServiceName, temps) : filtrer par service et période lit très peu de données. Les requêtes qui ne filtrent ni par service ni par temps sont les plus coûteuses.
  • PARTITION BY jour : la rétention supprime des partitions entières, très rapidement.
  • Codecs (Delta, ZSTD) et LowCardinality : la compression qui rend la télémétrie économique.
  • Index de saut : un filtre de Bloom sur TraceId et un index de jetons sur Body évitent de lire les blocs qui ne contiennent pas la valeur cherchée.

2. Interroger en SQL #

Des recettes à réutiliser.

Lire les attributs #

Les attributs sont dans des colonnes Map : LogAttributes['http.route'], SpanAttributes['db.system'], ResourceAttributes['k8s.pod.name']. Une clé absente renvoie une chaîne vide ; convertissez les nombres avec toUInt16OrZero() ou toFloat64OrNull().

Recettes #

-- 1. Taux d'erreurs par service et par minute (logs)
SELECT toStartOfMinute(Timestamp) AS minute, ServiceName,
       countIf(SeverityText ILIKE 'err%') / count() AS taux_erreur
FROM otel_logs WHERE Timestamp > now() - INTERVAL 1 HOUR
GROUP BY minute, ServiceName ORDER BY minute;

-- 2. Reconstituer une trace dans l'ordre
SELECT SpanName, ServiceName, Duration / 1e6 AS ms, StatusCode, ParentSpanId
FROM otel_traces WHERE TraceId = '4bf92f3577b34da6a3ce929d0e0e4736' ORDER BY Timestamp;

-- 3. Logs d'erreur rattachés aux traces lentes (jointure logs et traces)
SELECT l.Timestamp, l.ServiceName, l.Body
FROM otel_logs AS l
INNER JOIN (SELECT TraceId FROM otel_traces
            WHERE Duration > 2e9 AND Timestamp > now() - INTERVAL 1 HOUR) AS slow USING (TraceId)
WHERE l.SeverityText ILIKE 'err%' AND l.Timestamp > now() - INTERVAL 1 HOUR LIMIT 50;

-- 4. Top 10 des messages d'erreur, en regroupant les variantes
SELECT replaceRegexpAll(Body, '[0-9a-f]{8,}|\\d+', '?') AS motif, count() AS n
FROM otel_logs WHERE SeverityText ILIKE 'err%' AND Timestamp > now() - INTERVAL 1 DAY
GROUP BY motif ORDER BY n DESC LIMIT 10;
Bonne Pratique : Ajoutez toujours un filtre de temps (Timestamp > now() - INTERVAL …) et, si possible, de service : ce sont les colonnes de la clé de tri.

3. Accélérer et conserver #

Vues matérialisées, TTL, stockage froid.

Vues matérialisées #

-- Pré-agréger les métriques RED par minute : les dashboards lisent une petite table
CREATE TABLE red_1m (
    minute DateTime, ServiceName LowCardinality(String), route String,
    appels UInt64, erreurs UInt64, duree AggregateFunction(quantiles(0.5, 0.95, 0.99), UInt64)
) ENGINE = AggregatingMergeTree ORDER BY (ServiceName, route, minute)
TTL minute + INTERVAL 180 DAY;

CREATE MATERIALIZED VIEW red_1m_mv TO red_1m AS
SELECT toStartOfMinute(Timestamp) AS minute, ServiceName, SpanAttributes['http.route'] AS route,
       count() AS appels, countIf(StatusCode = 'Error') AS erreurs, quantilesState(0.5, 0.95, 0.99)(Duration) AS duree
FROM otel_traces WHERE SpanKind = 'Server'
GROUP BY minute, ServiceName, route;

-- Lecture
SELECT minute, ServiceName, sum(appels) AS appels, quantilesMerge(0.5, 0.95, 0.99)(duree) AS q
FROM red_1m WHERE minute > now() - INTERVAL 1 DAY GROUP BY minute, ServiceName ORDER BY minute;

La vue calcule l'agrégat à chaque insertion : les dashboards de long terme lisent quelques milliers de lignes au lieu de milliards de spans, et l'agrégat peut être conservé bien plus longtemps que les données brutes.

Rétention et stockage par niveaux #

-- Rétention différente par table
ALTER TABLE otel_logs   MODIFY TTL TimestampTime + INTERVAL 14 DAY;
ALTER TABLE otel_traces MODIFY TTL toDateTime(Timestamp) + INTERVAL 7 DAY;

-- Déplacer les données de plus de 3 jours vers un volume froid (stockage objet), supprimer après 90 jours
ALTER TABLE otel_logs MODIFY TTL
    TimestampTime + INTERVAL 3 DAY TO VOLUME 'froid',
    TimestampTime + INTERVAL 90 DAY DELETE;  -- nécessite une storage_policy avec un volume « froid »

-- Place occupée et taux de compression par table
SELECT table, formatReadableSize(sum(data_compressed_bytes)) AS compresse,
       round(sum(data_uncompressed_bytes) / sum(data_compressed_bytes), 1) AS ratio
FROM system.parts WHERE active AND database = currentDatabase() GROUP BY table ORDER BY sum(data_compressed_bytes) DESC;
Attention : Modifier un TTL déclenche une réécriture en arrière-plan sur les données existantes : faites-le hors des heures de pointe sur de gros volumes.

Commandes à connaître #

Commandes à connaître
  • SHOW CREATE TABLE otel_logs : définition réelle d'une table
  • LogAttributes['clé'] : lire un attribut
  • ALTER TABLE … MODIFY TTL … : changer la rétention
  • CREATE MATERIALIZED VIEW … TO … : pré-agréger à l'insertion
  • SELECT … FROM system.parts WHERE active : taille et compression des tables

Sources #

Vérifié en novembre 2026 : ClickStack évolue vite (Managed ClickStack est en bêta), consultez la documentation de ClickHouse avant de vous appuyer sur un détail.

Articles liés

Le trilemme de l'observabilité : coût, exhaustivité et performance, et comment les solutions le résolvent

Comprendre le trilemme de l'observabilité (coût, exhaustivité des données, performance des requêtes), ses tro…

Installer et déployer ClickStack : tout-en-un, Docker Compose, Helm et Managed ClickStack

Déployer ClickStack selon le besoin : conteneur tout-en-un avec persistance, Docker Compose et ses variables,…

Envoyer la télémétrie à ClickStack : SDK OpenTelemetry, collecteurs, logs, Kubernetes et sessions navigateur

Alimenter ClickStack : clé d'ingestion, variables OpenTelemetry des SDK, relais par un collecteur existant, l…

Pour aller plus loin

Soutenir

♥ SOUTENIR

Soutenez RousselTM Learning

Les formations, articles, TP et attestations restent gratuits et sans publicité intrusive. Une contribution libre, du montant de votre choix, finance l’hébergement, les environnements de TP et l’écriture de nouveaux contenus.

Contribuer avec PayPal Montant libre · carte bancaire ou compte PayPalEn savoir plus
QR code PayPal
Ou scannez ce QR code avec votre téléphone

Merci, chaque contribution compte !