Le schéma par défaut de ClickStack stocke les attributs resource, scope, log et span dans des colonnes Map(LowCardinality(String), String). ClickHouse prend également en charge le type JSON, et ClickStack offre une prise en charge bêta permettant de l’utiliser à la place de Map.
Pour les workloads d’observabilité typiques, nous recommandons de conserver le schéma par défaut basé sur Map. Le type JSON est disponible pour les utilisateurs qui souhaitent l’évaluer sur des workloads présentant un ensemble restreint et stable de clés d’attributs, mais ce n’est pas le schéma recommandé pour un usage général.
Pourquoi Map est le choix recommandé par défaut
Map(LowCardinality(String), String) stocke les clés et les valeurs dans une seule structure. Historiquement, l’inconvénient de Map était que la lecture d’une seule clé nécessitait de lire toute la colonne Map. Ce n’est plus le cas : ClickHouse prend désormais en charge la sérialisation de map par buckets, qui découpe la map en buckets afin que les requêtes ne lisent que ceux dont elles ont besoin. Combiné à des index textuels sur les clés et les valeurs de la map — comme dans le schéma par défaut de ClickStack — cela rend Map sélectif et rapide en lecture, sans pénalité d’ingestion lorsque de nouvelles clés apparaissent.
En pratique, cela signifie :
- Un coût d’ingestion stable à mesure que le nombre de clés augmente. L’ajout d’une nouvelle clé d’attribut ne modifie pas la disposition des colonnes sur disque et ne crée pas de nouveaux fichiers de colonnes. Le coût d’ingestion est limité par le volume de données, et non par la cardinalité des clés.
- Pas d’explosion des métadonnées. Le nombre de fichiers de colonnes sur disque ne suit pas le nombre de clés d’attribut uniques.
- Recherches sélectives via les index. Les index textuels sur les clés et les valeurs de la map permettent des recherches ciblées sans analyser chaque ligne.
- Un comportement prévisible à haut débit.
Map gère les ensembles d’attributs en rafales et sans schéma, courants dans le tracing et les logs, sans surcoût par clé.
Pourquoi ne pas utiliser JSON par défaut
JSON adopte une approche différente : à l’insertion, ClickHouse crée dynamiquement une sous-colonne dédiée, avec typage fort, pour chaque chemin rencontré. À la lecture, c’est intéressant, car seules les sous-colonnes demandées sont lues, les types sont préservés et aucune conversion de type au moment de la requête n’est nécessaire.
Le revers de la médaille se situe à l’ingestion. La création et la gestion d’un grand nombre de sous-colonnes dynamiques ajoutent une surcharge à l’écriture ainsi qu’une complexité supplémentaire au niveau des métadonnées. Pour les charges de travail d’observabilité, qui comportent souvent des ensembles d’attributs très volumineux ou très dynamiques, ainsi qu’un débit d’ingestion élevé, cette surcharge est importante. La limite max_dynamic_paths peut en limiter l’impact en redirigeant les chemins supplémentaires vers une colonne partagée, mais l’accès à cette colonne partagée est plus lent qu’à des sous-colonnes dédiées, ce qui réduit l’avantage en lecture qui motivait au départ l’utilisation de JSON.
La sérialisation compartimentée de Map supprimant l’essentiel de la surcharge historique à la lecture, l’avantage en lecture de JSON ne compense plus son coût à l’ingestion pour les charges de travail d’observabilité typiques.
Dans quels cas envisager encore JSON
- Votre jeu de clés d’attributs est petit et stable : vous n’avez pas des milliers de clés uniques et de nouvelles clés apparaissent rarement.
- Le débit d’ingestion est modéré par rapport à la cardinalité des attributs.
- Vous voulez un accès typé de manière stricte aux attributs, sans conversions de type au moment de la requête (les nombres restent des nombres, les booléens restent des booléens).
- Vous êtes prêt à utiliser une fonctionnalité bêta dans ClickStack et acceptez que l’intégration puisse évoluer.
Si toutes ces conditions ne sont pas réunies, restez sur le schéma par défaut basé sur Map.
Fonctionnalité bêta, non prête pour la productionLa prise en charge du type JSON dans ClickStack est une fonctionnalité bêta. Bien que le type JSON lui-même soit prêt pour la production dans ClickHouse 25.3+, son intégration à ClickStack est toujours en cours de développement et peut présenter des limitations, évoluer à l’avenir ou contenir des bogues.
2.0.4.
Activation de la prise en charge de JSON
Map, définissez les variables d’environnement suivantes.
| Variable | À définir sur | Objectif |
|---|
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' | OTel collector | Crée des schémas dans ClickHouse à l’aide du type JSON. |
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true | HyperDX (ClickStack UI) | Permet à la couche applicative d’interroger des schémas de type JSON. ClickStack Open Source uniquement. |
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' sur le collector. Par exemple :
docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' dans tout déploiement incluant le collector, ainsi que BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true dans la couche applicative HyperDX afin qu’elle puisse interroger les schémas de type JSON.
Par exemple :
docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest
Migrer d’un schéma basé sur Map vers JSON
RétrocompatibilitéLe type JSON n’est pas rétrocompatible avec les schémas Map existants. L’activation de cette fonctionnalité crée de nouvelles tables avec le type JSON et nécessite une migration manuelle des données. Renommer les tables existantes et mettre à jour les sources
Renommez les tables existantes et mettez à jour les sources de données dans HyperDX.Par exemple :RENAME TABLE otel_logs TO otel_logs_map;
RENAME TABLE otel_metrics TO otel_metrics_map;
Déployer le collector
Déployez le collector en définissant OTEL_AGENT_FEATURE_GATE_ARG.Redémarrer le conteneur HyperDX avec le support du schéma JSON
export BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true
Créer de nouvelles sources de données
Créez de nouvelles sources de données dans HyperDX pointant vers les tables JSON.Migration des données existantes (facultative)
INSERT INTO otel_logs SELECT * FROM otel_logs_map;
INSERT INTO otel_metrics SELECT * FROM otel_metrics_map;
Recommandé uniquement pour les jeux de données de moins de ~10 milliards de lignes. Les données auparavant stockées avec le type Map ne conservaient pas la précision des types (toutes les valeurs étaient des chaînes). Par conséquent, ces anciennes données apparaîtront comme des chaînes dans le nouveau schéma jusqu’à leur expiration, ce qui nécessitera quelques conversions de type côté frontend. Le type des nouvelles données sera conservé avec le type JSON.
