1. Les tables #
Ce que le collecteur crée.
Vue d'ensemble #
Disponible dans : ✓ Open source ✓ Managed ClickStack
| Table | Contenu | Colonnes clés |
|---|---|---|
otel_logs | logs | Timestamp, ServiceName, SeverityText, Body, TraceId, LogAttributes, ResourceAttributes |
otel_traces | spans | TraceId, SpanId, ParentSpanId, SpanName, SpanKind, Duration (ns), StatusCode, SpanAttributes, Events.*, Links.* |
otel_metrics_gauge, _sum, _histogram, _exponential_histogram, _summary | métriques, une table par type | MetricName, Attributes, TimeUnix, Value (ou buckets) |
hyperdx_sessions | sessions 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
TraceIdet un index de jetons surBodyé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 tableLogAttributes['clé']: lire un attributALTER TABLE … MODIFY TTL …: changer la rétentionCREATE MATERIALIZED VIEW … TO …: pré-agréger à l'insertionSELECT … 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.
