Passer au contenu principal
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

Les données d’observabilité sont principalement composées d’attributs, notamment les attributs de ressource, de scope, de span et de log. Ces ensembles sont généralement volumineux, à forte cardinalité, et ingérés avec un haut débit. Le schéma que vous choisissez pour ces attributs est le principal facteur du coût d’ingestion et de l’organisation du stockage. 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

Le type 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

Le type JSON peut être un bon choix si toutes les conditions suivantes sont réunies :
  • 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.

​
Statut bêta

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.
ClickStack prend en charge le type JSON en bêta à partir de la version 2.0.4.

​
Activation de la prise en charge de JSON

Pour utiliser des schémas de type JSON au lieu des schémas par défaut basés sur Map, définissez les variables d’environnement suivantes.

​
Managed ClickStack

Pour activer la prise en charge de JSON dans Managed ClickStack, contactez support@clickhouse.com avant de configurer le collector. La fonctionnalité doit également être activée dans la ClickStack UI (HyperDX) de ClickHouse Cloud. Définissez OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' sur le collector. Par exemple :

​
ClickStack open source

Définissez 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 :

​
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.
Pour migrer depuis les schémas basés sur Map par défaut, suivez ces étapes :
1

​
Arrêter l’OTel collector

2

​
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 :
3

​
Déployer le collector

Déployez le collector en définissant OTEL_AGENT_FEATURE_GATE_ARG.
4

​
Redémarrer le conteneur HyperDX avec le support du schéma JSON

5

​
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)

Pour déplacer les anciennes données dans les nouvelles tables JSON :
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.
Dernière modification le 2 juillet 2026