Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Options de configuration

View as MarkdownEdit this pageReport an issueSet up docs MCP

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 :

Configuration de la source HyperDX

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.

Les paramètres suivants sont disponibles pour chaque source :

Logs

Paramètre Description Obligatoire Inféré dans le schéma par défaut Valeur inférée
Nom Nom de la source. Oui No –
Section Libellé facultatif permettant de regrouper les sources dans le sélecteur de sources. Les sources appartenant à une même section apparaissent ensemble, et la recherche tient compte du nom de la section en plus de celui de la source. No No –
Connexion au serveur Nom de la connexion au serveur. Oui No Par défaut
Base de données Nom de la base de données ClickHouse. Yes Yes default
Table Nom de la table cible. Définissez otel_logs si le schéma par défaut est utilisé. Yes No
Paramètres de requête Paramètres de session au niveau des requêtes, définis chacun par un nom de paramètre et une valeur, appliqués à chaque requête exécutée sur cette source. No No –
Activé Une source désactivée est conservée, mais masquée dans les sélecteurs de sources et n’est jamais sélectionnée automatiquement. No No Activé
Colonne d’horodatage Colonne ou expression DateTime faisant partie de votre clé primaire. Oui Oui TimestampTime
Sélection par défaut Colonnes affichées dans les résultats de recherche par défaut. Oui Oui Timestamp, ServiceName, SeverityText, Body
Expression du nom du service Expression ou colonne correspondant au nom du service. Oui Oui ServiceName
Expression de version du service Expression ou colonne identifiant la version d’un service en cours d’exécution, utilisée pour tracer des marqueurs de version sur les graphiques des tableaux de bord. Utilise par défaut l’attribut de ressource OpenTelemetry service.version lorsqu’elle est laissée vide. Non Non ResourceAttributes['service.version']
Expression de niveau de journalisation Expression ou colonne correspondant au niveau de journalisation. Oui Oui SeverityText
Expression du corps Expression ou colonne correspondant au message de journal. Oui Oui Body
Expression des attributs de journal Expression ou colonne pour les attributs de journal personnalisés. Oui Oui LogAttributes
Expression d’attributs de ressource Expression ou colonne pour les attributs au niveau de la ressource. Oui Oui ResourceAttributes
Colonne d’horodatage affichée Colonne d’horodatage facultative, de précision supérieure, utilisée pour l’affichage dans l’UI. Si elle n’est pas renseignée, la colonne Timestamp est utilisée par défaut. No Yes Timestamp
Source de métriques corrélée Source de métriques associée (par ex. les métriques HyperDX). No No –
Source de traces corrélée Source de traces liée (par exemple, les traces HyperDX). No No –
Expression d’ID de trace Expression ou colonne utilisée pour extraire l’ID de trace. Oui Oui TraceId
Expression d’ID de span Expression ou colonne utilisée pour extraire l’ID de span. Oui Oui SpanId
Expression de colonne implicite Colonne utilisée pour la recherche en texte intégral lorsqu’aucun champ n’est spécifié (syntaxe Lucene). Il s’agit généralement du corps du journal. Oui Oui Body
Liste des colonnes connues Pour les sources basées sur une table Distributed ou Merge dont les tables cibles n'ont pas les mêmes ensembles de colonnes. Liste, séparée par des virgules, des colonnes disponibles dans toutes les tables cibles, utilisée à la place de SELECT * lors de la récupération des données complètes d'une ligne (par exemple, dans le panneau latéral de la ligne). Laissez vide pour sélectionner toutes les colonnes. Uniquement des noms de colonnes ; aucune expression ni aucun alias. No No –
Utiliser l’index textuel Indique si les recherches basées sur Lucene utilisent hasAllTokens lors d’une recherche dans la colonne implicite. Non Non Auto (détecté à partir du schéma)
Highlighted Attributes Expressions ou colonnes affichées à l’ouverture des détails des logs. Les expressions renvoyant des URL s’affichent sous forme de liens. Non Non –
Highlighted Trace Attributes Expressions ou colonnes extraites de chaque journal d'une trace, affichées au-dessus de la vue en cascade de la trace. Les expressions qui renvoient des URL s'affichent sous forme de liens. Non No –
Vues matérialisées Views matérialisées préagrégées associées à cette source, utilisées automatiquement pour accélérer les requêtes éligibles. Consultez Views matérialisées. No No –
Vues matérialisées de métadonnées Vues matérialisées utilisées pour accélérer la découverte des champs et la saisie semi-automatique des valeurs. Consultez les vues matérialisées de métadonnées. No Yes <table>_kv_rollup_15m
Ordre par défaut Expression ORDER BY qui remplace l’ordre de tri par défaut des résultats de recherche. Laissez ce champ vide pour utiliser la valeur par défaut détectée automatiquement. Ce paramètre peut ensuite être personnalisé pour chaque recherche. No No –

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 -
Query Settings Paramètres de session au niveau de la requête, chacun indiqué sous la forme d’un nom de paramètre et d’une valeur, qui sont ajoutés à chaque requête exécutée sur cette source. Non Non –
Enabled Une source désactivée est conservée, mais masquée dans les sélecteurs de sources et n’est jamais choisie automatiquement. Non Non Activée
Timestamp Column Colonne DateTime ou expression faisant partie de votre clé primaire. 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
Service Version Expression Expression ou colonne identifiant la version en cours d’exécution d’un service, utilisée pour afficher des marqueurs de version sur les graphiques du tableau de bord. Utilise par défaut l’attribut de ressource OpenTelemetry service.version lorsqu’elle est laissée vide. Non Non ResourceAttributes['service.version']
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
Sample Rate Expression Colonne ou expression contenant le poids d’échantillonnage en amont (1/N). Lorsqu’elle est définie, les agrégations (count, avg, sum, quantile) sont corrigées pour l’échantillonnage. Les percentiles utilisent alors quantileTDigestWeighted, qui est une approximation, de sorte que les valeurs exactes peuvent légèrement différer. Laissez vide si les spans ne sont pas échantillonnés. Non Non –
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
Span Links Expression Expression pour extraire les liens de span, utilisée pour capturer les liens d’un span vers des spans d’autres traces. Le type attendu est Nested(TraceId String, SpanId String, TraceState String, Attributes Map(LowCardinality(String), String)). Non Oui Links
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
Known Columns List Pour les sources basées sur une table Distributed ou Merge dont les tables cibles ont des ensembles de colonnes différents. Liste séparée par des virgules des colonnes disponibles dans toutes les tables cibles, utilisée à la place de SELECT * lors de la récupération de données complètes de ligne (par exemple, dans le panneau latéral de la ligne). Laissez vide pour sélectionner toutes les colonnes. Noms de colonnes uniquement ; aucune expression ni alias. Non Non –
Use Text Index Indique si les recherches basées sur Lucene génèrent hasAllTokens lors de la recherche dans la colonne implicite. Non Non Auto (detect from schema)
Displayed Timestamp Column Colonne d’horodatage facultative, de précision supérieure, utilisée dans l’UI. Utilise par défaut Timestamp Column lorsqu’elle n’est pas fournie. Non Oui Timestamp
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 –
Materialized Views Vues matérialisées préagrégées enregistrées pour cette source, utilisées automatiquement pour accélérer les requêtes éligibles. Consultez Vues matérialisées. Non Non –
Metadata Materialized Views Vues matérialisées utilisées pour accélérer la découverte des champs et l’autocomplétion des valeurs. Consultez Vues matérialisées de métadonnées. Non Oui <table>_kv_rollup_15m
Default Order By Expression ORDER BY qui remplace l’ordre par défaut des résultats de recherche. Laissez vide pour utiliser la valeur par défaut détectée automatiquement. Vous pourrez la personnaliser ultérieurement pour chaque recherche. 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
Query Settings Jusqu’à dix paramètres de session au niveau des requêtes, chacun indiqué sous la forme d’un nom de paramètre et d’une valeur, qui sont ajoutés à chaque requête exécutée sur cette source. Non Non –
Enabled Bouton bascule en haut du formulaire de source. Une source désactivée est conservée, mais masquée dans les sélecteurs de sources et jamais sélectionnée automatiquement. Affiché uniquement lors de la modification d’une source existante. Non Non Activé
Gauge Table Table stockant les métriques de type Gauge. Non Oui otel_metrics_gauge
Histogram Table Table stockant les métriques de type histogramme. Non Oui otel_metrics_histogram
Sum Table Table stockant les métriques de type somme (Counter). Non Oui otel_metrics_sum
Exponential Histogram Table Table stockant les métriques de type histogramme exponentiel. Non Oui otel_metrics_exponential_histogram
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 -
Query Settings Jusqu'à dix paramètres de session au niveau de la requête, chacun indiqué par un nom de paramètre et une valeur, qui sont ajoutés à chaque requête émise sur cette source. Non Non –
Enabled Commutateur situé en haut du formulaire de source. Une source désactivée est conservée, mais masquée des sélecteurs de sources et jamais choisie automatiquement. Affiché uniquement lors de la modification d'une source existante. Non Non Activé
Correlated Trace Source Source de traces liée pour la corrélation des sessions. Oui Non –
Timestamp Column Colonne DateTime ou expression faisant partie de la clé primaire. Oui Oui TimestampTime
Resource Attributes Expression Expression permettant d'extraire les métadonnées associées à la ressource. Non Oui ResourceAttributes

Vues matérialisées

Des vues matérialisées peuvent être enregistrées pour les sources de données de logs et de traces afin que les requêtes d’agrégation éligibles soient exécutées à partir de la vue pré-agrégée plutôt que de la table source. Pour savoir comment créer et enregistrer des vues, consultez « Vues matérialisées ».

Chaque vue enregistrée est configurée avec les paramètres suivants :

Paramètre Description
Database Base de données ClickHouse contenant la table cible de la vue matérialisée.
Table Table cible de la vue matérialisée, et non la vue elle-même.
Timestamp Column Colonne d’horodatage de la table cible.
Granularity Granularité temporelle de la colonne d’horodatage de la table cible, par exemple 1 minute. Une requête ne peut utiliser la vue que si sa propre granularité temporelle est égale ou plus grossière.
Minimum Date Facultatif. Date et heure les plus anciennes pour lesquelles la vue contient des données. Si cette valeur n’est pas fournie, ClickStack suppose que la vue contient des données pour toutes les dates couvertes par la table source.
Dimension Columns Liste des colonnes, séparées par des virgules, qui ne sont pas pré-agrégées par la vue et peuvent donc être utilisées pour le filtrage et le regroupement.
Pre-aggregated Columns Colonnes pré-agrégées par la vue. Chaque entrée associe une fonction d’agrégation (avg, count, max, min, quantile, sum ou histogram) et une colonne de la table source à la colonne correspondante de la vue. La colonne source n’est pas requise pour count.

La plupart de ces paramètres sont déduits du schéma de la vue lorsque la table cible est sélectionnée.

Vues matérialisées de métadonnées

Les vues matérialisées de métadonnées accélèrent la découverte des champs pour les filtres et l’autocomplétion. Elles peuvent être configurées sur les sources de données Log et Trace.

Paramètre Description
Key Rollup Table Facultatif et obsolète. Table d’agrégation des clés présentes dans la table source.
KV Rollup Table Table d’agrégation des paires clé/valeur présentes dans la table source.
granularité temporelle L’intervalle temporel utilisé par les tables d’agrégation, par exemple 15 minute.

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.

Chaque attribut est configuré avec les paramètres suivants :

Paramètre Description
SQL Expression La colonne ou l’expression SQL arbitraire à interroger. Obligatoire.
Alias Facultatif. Le libellé affiché pour l’attribut à la place de l’expression SQL.
Lucene Expression Facultatif. Une version Lucene de l’expression SQL, utilisée lors de la recherche de cette valeur d’attribut.

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

Configuration des Highlighted Attributes

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

Highlighted Attributes

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.

Recherche des Highlighted Attributes

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 :

Source corrélée HyperDX

Paramètres de configuration de l’application

  • 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.

Navigation