Options de configuration

Options de configuration pour ClickStack - la stack d’observabilité de ClickHouse

Les options de configuration suivantes sont disponibles pour chaque composant de ClickStack :

​

Paramètres pour les distributions open source

​

Docker

Si vous utilisez Tout-en-un, HyperDX uniquement ou le mode local, il suffit de définir le paramètre souhaité via une variable d’environnement, par exemple.

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

​

Docker Compose

Si vous utilisez le guide de déploiement Docker Compose, vous pouvez utiliser le fichier .env pour modifier les paramètres.

Vous pouvez également surcharger explicitement les paramètres dans le fichier docker-compose.yaml, par exemple :

Exemple :

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... other settings

​

Helm

​

Personnaliser les values (facultatif)

Vous pouvez personnaliser la configuration à l’aide des options --set, par exemple :

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

Vous pouvez aussi modifier le values.yaml. Pour récupérer les valeurs par défaut :

helm show values hyperdx/hdx-oss-v2 > values.yaml

Exemple de configuration :

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

​

Application ClickStack UI (HyperDX)

​

Paramètres de la source de données

La ClickStack UI nécessite que l’utilisateur définisse une source pour chacun des types/piliers de données d’observabilité :

• Logs
• Traces
• Metrics
• Sessions

Cette configuration peut être effectuée dans l’application depuis Team Settings -> Sources, comme illustré ci-dessous pour les logs :

Chacune de ces sources nécessite qu’au moins une table soit spécifiée lors de la création, ainsi qu’un ensemble de colonnes permettant à HyperDX d’interroger les données.

Si vous utilisez le schéma OpenTelemetry (OTel) par défaut fourni avec ClickStack, ces colonnes peuvent être déterminées automatiquement pour chacune des sources. Si vous modifiez le schéma ou utilisez un schéma personnalisé, vous devez spécifier et mettre à jour ces correspondances.

Le schéma ClickHouse par défaut fourni avec ClickStack est celui créé par le ClickHouse exporter for the OTel collector. Ces noms de colonnes correspondent à la spécification officielle d’OTel, documentée ici.

Les paramètres suivants sont disponibles pour chaque source :

​

Logs

Paramètre	Description	Obligatoire	Déduit dans le schéma par défaut	Valeur déduite
Name	Nom de la source.	Oui	Non	–
Section	Libellé facultatif permettant de regrouper les sources dans le sélecteur de sources. Les sources d’une même section apparaissent ensemble, et la recherche tient compte du nom de la section en plus de celui de la source.	Non	Non	–
Server Connection	Nom de la connexion au serveur.	Oui	Non	Default
Database	Nom de la base de données ClickHouse.	Oui	Oui	default
Table	Nom de la table cible. Définissez otel_logs si le schéma par défaut est utilisé.	Oui	Non
Timestamp Column	Colonne DateTime ou expression faisant partie de votre clé primaire.	Oui	Oui	TimestampTime
Default Select	Colonnes affichées dans les résultats de recherche par défaut.	Oui	Oui	Timestamp, ServiceName, SeverityText, Body
Service Name Expression	Expression ou colonne du nom du service.	Oui	Oui	ServiceName
Log Level Expression	Expression ou colonne du niveau de log.	Oui	Oui	SeverityText
Body Expression	Expression ou colonne du message du log.	Oui	Oui	Body
Log Attributes Expression	Expression ou colonne des attributs de log personnalisés.	Oui	Oui	LogAttributes
Resource Attributes Expression	Expression ou colonne des attributs de ressource.	Oui	Oui	ResourceAttributes
Displayed Timestamp Column	Colonne de timestamp utilisée pour l’affichage dans l’interface utilisateur.	Oui	Oui	ResourceAttributes
Correlated Metric Source	Source de métriques liée (par ex. métriques HyperDX).	Non	Non	–
Correlated Trace Source	Source de traces liée (par ex. traces HyperDX).	Non	Non	–
Trace Id Expression	Expression ou colonne utilisée pour extraire le trace ID.	Oui	Oui	TraceId
Span Id Expression	Expression ou colonne utilisée pour extraire le span ID.	Oui	Oui	SpanId
Implicit Column Expression	Colonne utilisée pour la recherche en texte intégral si aucun champ n’est spécifié (style Lucene). Il s’agit généralement du corps du log.	Oui	Oui	Body
Highlighted Attributes	Expressions ou colonnes affichées lors de l’ouverture des détails du log. Les expressions renvoyant des URL seront affichées sous forme de liens.	Non	Non	–
Highlighted Trace Attributes	Expressions ou colonnes extraites de chaque log d’une trace, affichées au-dessus du waterfall de la trace. Les expressions renvoyant des URL seront affichées sous forme de liens.	Non	Non	–

​

Traces

Paramètre	Description	Obligatoire	Déduit dans le schéma par défaut	Valeur déduite
Name	Nom de la source.	Oui	Non	–
Section	Libellé facultatif pour regrouper les sources dans le sélecteur de sources. Les sources qui partagent une même section apparaissent ensemble, et la recherche correspond au nom de la section en plus du nom de la source.	Non	Non	–
Server Connection	Nom de la connexion au serveur.	Oui	Non	Default
Database	Nom de la base de données ClickHouse.	Oui	Oui	default
Table	Nom de la table cible. Définissez otel_traces si vous utilisez le schéma par défaut.	Oui	Oui	-
Timestamp Column	Colonne DateTime ou expression faisant partie de votre clé primaire.	Oui	Oui	Timestamp
Timestamp	alias de Timestamp Column.	Oui	Oui	Timestamp
Default Select	Colonnes affichées dans les résultats de recherche par défaut.	Oui	Oui	Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName
Duration Expression	Expression utilisée pour calculer la durée du span.	Oui	Oui	Duration
Duration Precision	Précision de l’expression de durée (par ex. nanosecondes, microsecondes).	Oui	Oui	ns
Trace Id Expression	Expression ou colonne pour les trace ID.	Oui	Oui	TraceId
Span Id Expression	Expression ou colonne pour les ID de span.	Oui	Oui	SpanId
Parent Span Id Expression	Expression ou colonne pour les ID des spans parents.	Oui	Oui	ParentSpanId
Span Name Expression	Expression ou colonne pour les noms de span.	Oui	Oui	SpanName
Span Kind Expression	Expression ou colonne pour le type de span (par ex. client, server).	Oui	Oui	SpanKind
Correlated Log Source	Facultatif. Source de logs liée (par ex. logs HyperDX).	Non	Non	–
Correlated Session Source	Facultatif. Source de session liée.	Non	Non	–
Correlated Metric Source	Facultatif. Source de métriques liée (par ex. métriques HyperDX).	Non	Non	–
Status Code Expression	Expression du code de statut du span.	Oui	Oui	StatusCode
Status Message Expression	Expression du message de statut du span.	Oui	Oui	StatusMessage
Service Name Expression	Expression ou colonne pour le nom du service.	Oui	Oui	ServiceName
Resource Attributes Expression	Expression ou colonne pour les attributs au niveau de la ressource.	Oui	Oui	ResourceAttributes
Event Attributes Expression	Expression ou colonne pour les attributs d’événement.	Oui	Oui	SpanAttributes
Span Events Expression	Expression pour extraire les événements du span. Il s’agit généralement d’une colonne de type Nested. Cela permet d’afficher les stack traces d’exception avec les language SDKs pris en charge.	Oui	Oui	Events
Implicit Column Expression	Colonne utilisée pour la recherche en texte intégral si aucun champ n’est spécifié (style Lucene). Il s’agit généralement du corps du log.	Oui	Oui	SpanName
Highlighted Attributes	Expressions ou colonnes affichées à l’ouverture des détails d’un span. Les expressions qui renvoient des URL seront affichées sous forme de liens.	Non	Non	–
Highlighted Trace Attributes	Expressions ou colonnes extraites de chaque span d’une trace, affichées au-dessus du trace waterfall. Les expressions qui renvoient des URL seront affichées sous forme de liens.	Non	Non	–

​

Métriques

Paramètre	Description	Obligatoire	Inféré dans le schéma par défaut	Valeur inférée
Name	Nom de la source.	Oui	Non	–
Section	Libellé facultatif pour regrouper les sources dans le sélecteur de sources. Les sources qui partagent une même section apparaissent ensemble, et la recherche porte aussi sur le nom de la section, en plus du nom de la source.	Non	Non	–
Server Connection	Nom de la connexion au serveur.	Oui	Non	Default
Database	Nom de la base de données ClickHouse.	Oui	Oui	default
Gauge Table	Table stockant les métriques de type Gauge.	Oui	Non	otel_metrics_gauge
Histogram Table	Table stockant les métriques de type histogramme.	Oui	Non	otel_metrics_histogram
Sum Table	Table stockant les métriques de type somme (Counter).	Oui	Non	otel_metrics_sum
Correlated Log Source	Facultatif. Source de logs liée (par ex. logs HyperDX).	Non	Non	–

​

Sessions

Paramètre	Description	Obligatoire	Inféré dans le schéma par défaut	Valeur inférée
Name	Nom de la source.	Oui	Non	–
Section	Étiquette facultative pour regrouper les sources dans le sélecteur de sources. Les sources qui partagent une même section apparaissent ensemble, et la recherche tient compte du nom de la section en plus du nom de la source.	Non	Non	–
Server Connection	Nom de la connexion au serveur.	Oui	Non	Default
Database	Nom de la base de données ClickHouse.	Oui	Oui	default
Table	Table cible pour les données de session. Définissez hyperdx_sessions si vous utilisez le schéma par défaut.	Oui	Oui	-
Timestamp Column	Colonne DateTime ou expression faisant partie de la clé primaire.	Oui	Oui	TimestampTime
Log Attributes Expression	Expression permettant d’extraire les attributs de log à partir des données de session.	Oui	Oui	LogAttributes
LogAttributes	Alias ou référence de champ servant à stocker les attributs de log.	Oui	Oui	LogAttributes
Resource Attributes Expression	Expression permettant d’extraire les métadonnées associées à la ressource.	Oui	Oui	ResourceAttributes
Correlated Trace Source	Facultatif. Source de traces liée pour la corrélation des sessions.	Non	Non	–
Implicit Column Expression	Colonne utilisée pour la recherche en texte intégral lorsqu’aucun champ n’est spécifié (par ex. parsing de requêtes de type Lucene).	Oui	Oui	Body

​

Highlighted Attributes

Les Highlighted Attributes et les Highlighted Trace Attributes peuvent être configurés dans les sources de données Log et Trace.

• Les Highlighted Attributes sont des colonnes ou des expressions affichées pour chaque log ou span lors de l’affichage des détails du log ou du span.
• Les Highlighted Trace Attributes sont des colonnes ou des expressions récupérées pour chaque log ou span d’une trace, puis affichées au-dessus de la trace waterfall.

Ces attributs sont définis dans la configuration de la source et peuvent être des expressions SQL arbitraires. Si l’expression SQL renvoie une valeur au format URL, l’attribut sera affiché sous forme de lien. Les valeurs vides ne sont pas affichées.

Par exemple, cette source de trace a été configurée avec un Highlighted Attributes et un Highlighted Trace Attributes :

Ces attributs s’affichent dans le panneau latéral après avoir cliqué sur un log ou un span :

Cliquer sur un attribut permet d’utiliser cet attribut comme valeur de recherche. Si l’expression Lucene facultative est fournie dans la configuration de l’attribut, elle sera utilisée pour la recherche à la place de l’expression SQL.

​

Sources corrélées

Pour activer une corrélation complète entre les sources dans ClickStack, vous devez configurer des sources corrélées pour les logs, les traces, les métriques et les sessions. Cela permet à HyperDX d’associer les données liées et de fournir un contexte détaillé lors de l’affichage des événements.

• Logs : peuvent être corrélés avec les traces et les métriques.
• Traces : peuvent être corrélées avec les logs, les sessions et les métriques.
• Metrics : peuvent être corrélées avec les logs.
• Sessions : peuvent être corrélées avec les traces.

La configuration de ces corrélations active plusieurs fonctionnalités. Par exemple, HyperDX peut afficher les logs pertinents aux côtés d’une trace ou mettre en évidence des anomalies de métriques liées à une session.

Par exemple, ci-dessous, la source de logs est configurée avec des sources corrélées :

​

Paramètres de configuration de l’application

HyperDX dans ClickHouse Cloud

Ces paramètres ne peuvent pas être modifiés lorsque HyperDX est hébergé dans ClickHouse Cloud.

• HYPERDX_API_KEY

  • Par défaut : Aucune (obligatoire)
  • Description : Clé d’authentification pour l’API HyperDX.
  • Recommandations :
  • Obligatoire pour la télémétrie et la journalisation
  • En développement local, il peut s’agir de n’importe quelle valeur non vide
  • En production, utilisez une clé sûre et unique
  • Peut être obtenue sur la page Team Settings après la création du compte

• HYPERDX_LOG_LEVEL

  • Par défaut : info
  • Description : Définit le niveau de verbosité de la journalisation.
  • Options : debug, info, warn, error
  • Recommandations :
  • Utilisez debug pour un débogage détaillé
  • Utilisez info pour un fonctionnement normal
  • Utilisez warn ou error en production pour réduire le volume des logs

• HYPERDX_API_PORT

  • Par défaut : 8000
  • Description : Port du serveur API HyperDX.
  • Recommandations :
  • Assurez-vous que ce port est disponible sur votre hôte
  • Modifiez-le en cas de conflit de port
  • Il doit correspondre au port défini dans la configuration de vos clients API

• HYPERDX_APP_PORT

  • Par défaut : 8000
  • Description : Port de l’application frontale HyperDX.
  • Conseils :
  • Assurez-vous que ce port est disponible sur votre hôte.
  • Modifiez-le en cas de conflit de port.
  • Il doit être accessible depuis votre navigateur.

• HYPERDX_APP_URL

  • Par défaut : http://localhost
  • Description : URL de base de l’application.
  • Recommandations :
  • Définissez-la sur votre domaine en production
  • Incluez le protocole (http/https)
  • N’ajoutez pas de slash final

• MONGO_URI

  • Par défaut : mongodb://db:27017/hyperdx
  • Description : Chaîne de connexion à MongoDB.
  • Recommandations :
  • Utilisez la valeur par défaut pour le développement local avec Docker
  • En production, utilisez une chaîne de connexion sécurisée
  • Incluez l’authentification si nécessaire
  • Exemple : mongodb://user:pass@host:port/db

• MINER_API_URL

  • Par défaut : http://miner:5123
  • Description : URL du service d’analyse des motifs de logs.
  • Recommandations :
  • Utilisez la valeur par défaut pour le développement local avec Docker
  • Définissez l’URL de votre service miner en production
  • Doit être accessible depuis le service API

• FRONTEND_URL

  • Par défaut : http://localhost:3000
  • Description : URL de l’application frontale.
  • Recommandations :
  • Utilisez la valeur par défaut pour le développement local
  • Définissez votre domaine en production
  • Doit être accessible depuis le service API

• OTEL_SERVICE_NAME

  • Par défaut : hdx-oss-api
  • Description : Nom du service pour l’instrumentation OpenTelemetry.
  • Recommandation :
  • Utilisez un nom explicite pour votre service HyperDX. S’applique si HyperDX s’instrumente lui-même.
  • Permet d’identifier le service HyperDX dans les données de télémétrie

• NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT

  • Par défaut : http://localhost:4318
  • Description : endpoint du collecteur OpenTelemetry.
  • Recommandations :
  • Pertinent pour l’auto-instrumentation d’HyperDX.
  • Utilisez la valeur par défaut pour le développement local
  • Définissez l’URL de votre collecteur en production
  • Doit être accessible depuis votre service HyperDX

• USAGE_STATS_ENABLED

  • Par défaut : true
  • Description : Active ou désactive la collecte de statistiques d’utilisation.
  • Recommandation :
  • Définissez cette valeur sur false pour désactiver le suivi de l’utilisation
  • Utile pour les déploiements sensibles à la confidentialité
  • La valeur par défaut est true afin d’améliorer le produit

• IS_OSS

  • Par défaut : true
  • Description : Indique si l’application fonctionne en mode OSS.
  • Recommandation :
  • Conservez true pour les déploiements open-source
  • Définissez false pour les déploiements d’entreprise
  • Affecte la disponibilité des fonctionnalités

• IS_LOCAL_MODE

  • Par défaut : false
  • Description : Indique si l’application s’exécute en mode local.
  • Recommandations :
  • Définir sur true pour un développement local
  • Désactive certaines fonctionnalités de production
  • Utile pour les tests et le développement

• EXPRESS_SESSION_SECRET

  • Par défaut : hyperdx is cool 👋
  • Description : Secret pour la gestion des sessions Express.
  • Recommandations :
  • À modifier en production
  • Utiliser une chaîne aléatoire forte
  • Le conserver de façon sécurisée

• ENABLE_SWAGGER

  • Par défaut : false
  • Description : Active ou désactive la documentation de l’API Swagger.
  • Recommandation :
  • Définissez cette option sur true pour activer la documentation de l’API
  • Utile pour le développement et les tests
  • À désactiver en production

• BETA_CH_OTEL_JSON_SCHEMA_ENABLED

  • Par défaut : false
  • Description : Active la prise en charge bêta du type JSON dans HyperDX. Voir aussi OTEL_AGENT_FEATURE_GATE_ARG pour activer la prise en charge de JSON dans l’OTel collector.
  • Recommandations :
    • Active une fonctionnalité en bêta. Les schémas de type JSON sont déconseillés pour les workloads d’observabilité courants. Voir Map vs JSON type pour une comparaison et savoir dans quels cas utiliser l’un ou l’autre.
    • Définissez cette valeur sur true pour activer la prise en charge de JSON dans la ClickStack UI.

​

Collecteur OpenTelemetry

Voir “ClickStack OpenTelemetry Collector” pour plus de détails.

• CLICKHOUSE_ENDPOINT

  • Par défaut : Aucune (obligatoire) si l’image est autonome. Avec une distribution All-in-one ou Docker Compose, cette valeur pointe vers l’instance ClickHouse intégrée.
  • Description : URL HTTPS de l’instance ClickHouse vers laquelle exporter les données de télémétrie.
  • Conseils :
    • Doit être un endpoint HTTPS complet, port inclus (par ex. https://clickhouse.example.com:8443)
    • Obligatoire pour que le collecteur puisse envoyer des données à ClickHouse

• CLICKHOUSE_USER

  • Par défaut : default
  • Description : Nom d’utilisateur utilisé pour s’authentifier auprès de l’instance ClickHouse.
  • Conseils :
    • Assurez-vous que l’utilisateur dispose des permissions INSERT et CREATE TABLE
    • Il est recommandé de créer un utilisateur dédié à l’ingestion

• CLICKHOUSE_PASSWORD

  • Par défaut : Aucun (obligatoire si l’authentification est activée)
  • Description : Mot de passe de l’utilisateur ClickHouse indiqué.
  • Conseils :
    • Obligatoire si un mot de passe est défini pour ce compte utilisateur
    • Stockez-le de façon sécurisée via des secrets dans les déploiements de production

• HYPERDX_LOG_LEVEL

  • Par défaut : info
  • Description : Niveau de verbosité des logs du collecteur.
  • Conseils :
    • Accepte des valeurs telles que debug, info, warn, error
    • Utilisez debug pendant le dépannage

• OPAMP_SERVER_URL

  • Par défaut : Aucune (obligatoire) si l’image est autonome. Avec une distribution All-in-one ou Docker Compose, cette valeur pointe vers l’instance HyperDX déployée.
  • Description : URL du serveur OpAMP utilisé pour gérer le collecteur (par ex. une instance HyperDX). Par défaut, il utilise le port 4320.
  • Conseils :
    • Doit pointer vers votre instance HyperDX
    • Active la configuration dynamique et l’ingestion sécurisée
    • Si elle est omise, l’ingestion sécurisée est désactivée, sauf si une valeur OTLP_AUTH_TOKEN est spécifiée.

• OTLP_AUTH_TOKEN

  • Par défaut : Aucun. Utilisé uniquement avec l’image autonome.
  • Description : Permet de spécifier un jeton d’authentification OTLP. S’il est défini, toute communication nécessite ce jeton Bearer.
  • Conseils :
    • Recommandé si vous utilisez l’image autonome du collecteur en production.

• HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

  • Par défaut : default
  • Description : Base de données ClickHouse dans laquelle le collecteur écrit les données de télémétrie.
  • Conseils :
    • Définissez-le si vous utilisez un nom de base de données personnalisé
    • Assurez-vous que l’utilisateur indiqué a accès à cette base de données

• OTEL_AGENT_FEATURE_GATE_ARG

  • Par défaut : <empty string>
  • Description : Active les feature flags dans le collecteur. S’il est défini sur --feature-gates=clickhouse.json, il active la prise en charge bêta du type JSON dans le collecteur et garantit que les schémas sont créés avec ce type. Voir aussi BETA_CH_OTEL_JSON_SCHEMA_ENABLED pour activer la prise en charge de JSON dans HyperDX.
  • Conseils :
    • Active une fonctionnalité bêta. Les schémas typés JSON sont déconseillés pour les charges de travail d’observabilité classiques. Voir Map vs JSON type pour une comparaison et les cas d’usage adaptés à chacun.
    • Définissez-le sur --feature-gates=clickhouse.json pour créer de nouvelles tables avec le type JSON.

​

ClickHouse

ClickStack Open Source est livré avec une configuration ClickHouse par défaut conçue pour fonctionner à l’échelle de plusieurs téraoctets, mais les utilisateurs peuvent librement la modifier et l’optimiser en fonction de leur charge de travail.

Pour optimiser ClickHouse efficacement, vous devez comprendre les principaux concepts de stockage tels que les parts, les partitions, les shards et répliques, ainsi que la façon dont les fusions se produisent à l’insertion. Nous vous recommandons de revoir les principes fondamentaux des index primaires, des index secondaires creux et des index de saut de données, ainsi que les techniques de gestion du cycle de vie des données, par exemple à l’aide d’une politique TTL.

ClickStack prend en charge la personnalisation du schéma - vous pouvez modifier les types de colonnes, extraire de nouveaux champs (par exemple à partir des logs), appliquer des codecs et des dictionnaires, et accélérer les requêtes à l’aide de projections.

En outre, des vues matérialisées peuvent être utilisées pour transformer ou filtrer les données pendant l’ingestion, à condition que les données soient écrites dans la table source de la vue et que l’application lise depuis la table cible. Les vues matérialisées peuvent également être utilisées pour accélérer nativement les requêtes dans ClickStack.

Pour plus de détails, consultez la documentation ClickHouse sur la conception de schéma, les stratégies d’indexation et les bonnes pratiques de gestion des données — la plupart s’appliquent directement aux déploiements ClickStack.