Passer au contenu principal
Essayez OTel FYI - la documentation de l’OTel collector en toute simplicitéOTel FYI propose une documentation claire et concise sur l’OTel collector, couvrant les receivers, processors, exporters et pipelines. Une excellente ressource complémentaire pour configurer votre ClickStack OTel collector.
Cette page présente les détails de configuration du collector OpenTelemetry (OTel) officiel de ClickStack.

​
Rôles du collector

Les OpenTelemetry collectors peuvent être déployés selon deux rôles principaux :
  • Agent - Les instances d’agent collectent les données à la périphérie, par exemple sur des serveurs ou des nœuds Kubernetes, ou reçoivent directement des événements d’applications instrumentées avec un SDK OpenTelemetry. Dans ce dernier cas, l’instance d’agent s’exécute avec l’application ou sur le même hôte que celle-ci (par exemple en sidecar ou sous forme de DaemonSet). Les agents peuvent soit envoyer leurs données directement à ClickHouse, soit à une instance de gateway. Dans le premier cas, on parle du modèle de déploiement Agent.
  • gateway - Les instances de gateway fournissent un service autonome (par exemple, un déploiement Kubernetes), généralement par cluster, par centre de données ou par région. Elles reçoivent des événements d’applications (ou d’autres collectors faisant office d’agents) via un point de terminaison OTLP unique. En général, plusieurs instances de gateway sont déployées, avec un équilibreur de charge prêt à l’emploi pour répartir la charge entre elles. Si tous les agents et toutes les applications envoient leurs signaux vers ce point de terminaison unique, on parle souvent du modèle de déploiement gateway.
Important : le collector, y compris dans les distributions par défaut de ClickStack, assume le rôle de gateway décrit ci-dessous et reçoit les données des agents ou des SDKs. Les utilisateurs qui déploient des OTel collectors dans le rôle d’agent utiliseront généralement la distribution contrib par défaut du collector plutôt que la version ClickStack, mais ils sont libres d’utiliser d’autres technologies compatibles OTLP telles que Fluentd et Vector.

​
Déployer le collector


Nous recommandons d’utiliser la distribution officielle ClickStack du collector pour le rôle de gateway lors de l’envoi vers Managed ClickStack, dans la mesure du possible. Si vous choisissez d’utiliser le vôtre, assurez-vous qu’il inclut le ClickHouse exporter.Le collecteur peut être déployé via Helm (recommandé pour Kubernetes) ou via Docker. Le chart Helm ClickStack officiel intègre le chart Helm du collecteur OpenTelemetry en tant que sous-chart, avec l’image de la distribution ClickStack préconfigurée — consultez le guide de déploiement Helm ClickStack si vous souhaitez installer la stack complète incluant HyperDX. Pour un déploiement autonome du collecteur, le chart upstream peut être utilisé directement avec l’image ClickStack, comme illustré ci-dessous.
Ajoutez le dépôt Helm OpenTelemetry officiel :
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
Créez un fichier values.yaml qui configure l’image ClickStack et les identifiants de Managed ClickStack :
# values.yaml
mode: deployment

image:
  repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
  tag: "2.19.0"

ports:
  otlp:
    enabled: true
  otlp-http:
    enabled: true

extraEnvs:
  - name: CLICKHOUSE_ENDPOINT
    value: "https://your-instance.clickhouse.cloud:8443"
  - name: CLICKHOUSE_USER
    value: "default"
  - name: CLICKHOUSE_PASSWORD
    value: "<password>"
Installez le chart :
helm install clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
Pour les déploiements de production, nous vous recommandons de stocker CLICKHOUSE_PASSWORD dans un secret Kubernetes et d’y faire référence via extraEnvsFrom plutôt que d’intégrer directement la valeur.
L’instance ClickHouse cible est configurée via les variables d’environnement CLICKHOUSE_ENDPOINT, CLICKHOUSE_USER et CLICKHOUSE_PASSWORD. La valeur de CLICKHOUSE_ENDPOINT doit correspondre à l’endpoint HTTP complet de ClickHouse Cloud, protocole et port inclus — par exemple, https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443.Pour plus d’informations sur la récupération de vos identifiants Managed ClickStack, consultez cette page.
Utilisateur pour la productionEn production, vous devez utiliser un utilisateur disposant des identifiants appropriés.

​
Modification de la configuration

​
Configuration de l’instance Managed ClickStack

L’OpenTelemetry Collector peut être configuré pour utiliser une instance Managed ClickStack via les variables d’environnement CLICKHOUSE_ENDPOINT, CLICKHOUSE_USER et CLICKHOUSE_PASSWORD. La façon dont ces variables sont définies dépend de votre méthode de déploiement :
Surchargez les entrées appropriées sous extraEnvs dans votre values.yaml, puis mettez à jour la release :
# values.yaml
extraEnvs:
  - name: CLICKHOUSE_ENDPOINT
    value: "<HTTPS_ENDPOINT>"
  - name: CLICKHOUSE_USER
    value: "<CLICKHOUSE_USER>"
  - name: CLICKHOUSE_PASSWORD
    value: "<CLICKHOUSE_PASSWORD>"

helm upgrade clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml

​
Étendre la configuration du collector

La distribution ClickStack de l’OTel collector permet d’étendre la configuration de base en montant un fichier de configuration personnalisé et en définissant une variable d’environnement.Pour ajouter des receivers, des processors ou des pipelines personnalisés :
  1. Créez un fichier de configuration personnalisé contenant votre configuration supplémentaire
  2. Montez le fichier dans /etc/otelcol-contrib/custom.config.yaml
  3. Définissez la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Exemple de configuration personnalisée :
receivers:
  # Collect logs from local files
  filelog:
    include:
      - /var/log/**/*.log
      - /var/log/syslog
      - /var/log/messages
    start_at: beginning

  # Collect host system metrics
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      memory:
        metrics:
          system.memory.utilization:
            enabled: true
      disk:
      network:
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true

service:
  pipelines:
    # Logs pipeline
    logs/host:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
    
    # Metrics pipeline
    metrics/hostmetrics:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - batch
      exporters:
        - clickhouse
Déploiement avec le collector autonome :
docker run -d \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  # -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -v "$(pwd)/custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-otel-collector:latest
Dans la configuration personnalisée, vous ne définissez que de nouveaux receivers, processors et pipelines. Les processors de base (memory_limiter, batch) et les exporters (clickhouse) sont déjà définis — faites-y référence par leur nom. La configuration personnalisée est fusionnée avec la configuration de base et ne peut pas redéfinir des composants existants.
Pour des configurations plus complexes, consultez la configuration par défaut du collector ClickStack et la documentation de l’exporter ClickHouse.

​
Structure de configuration

Pour en savoir plus sur la configuration des collectors OTel, notamment les receivers, les operators et les processors, nous vous recommandons de consulter la documentation officielle de l’OpenTelemetry Collector.

​
Docker Compose

Avec Docker Compose, modifiez la configuration du collector en utilisant les mêmes variables d’environnement qu’indiqué ci-dessus :
  otel-collector:
    image: hyperdx/hyperdx-otel-collector
    environment:
      CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443'
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      CLICKHOUSE_USER: 'default'
      CLICKHOUSE_PASSWORD: 'password'
      CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml'
    ports:
      - '13133:13133' # health_check extension
      - '24225:24225' # fluentd receiver
      - '4317:4317' # OTLP gRPC receiver
      - '4318:4318' # OTLP http receiver
      - '8888:8888' # metrics extension
    volumes:
      - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
    restart: always
    networks:
      - internal

​
Sécurisation du collector

Par défaut, le ClickStack OpenTelemetry collector n’est pas sécurisé lorsqu’il est déployé en dehors des distributions open source et ne nécessite aucune authentification sur ses ports OTLP.Pour sécuriser l’ingestion, spécifiez un jeton d’authentification lors du déploiement du collector à l’aide de la variable d’environnement OTLP_AUTH_TOKEN. La manière de le définir dépend de votre méthode de déploiement :
Ajoutez OTLP_AUTH_TOKEN à extraEnvs dans votre values.yaml, puis mettez à jour la release :
# values.yaml
extraEnvs:
  - name: OTLP_AUTH_TOKEN
    value: "a_very_secure_string"
  - name: CLICKHOUSE_ENDPOINT
    value: "<HTTPS_ENDPOINT>"
  - name: CLICKHOUSE_USER
    value: "<CLICKHOUSE_USER>"
  - name: CLICKHOUSE_PASSWORD
    value: "<CLICKHOUSE_PASSWORD>"

helm upgrade clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
Pour les déploiements en production, nous recommandons de stocker OTLP_AUTH_TOKEN et CLICKHOUSE_PASSWORD dans un secret Kubernetes et de les référencer via extraEnvsFrom.
Nous recommandons également :
  • De configurer le collector pour communiquer avec ClickHouse en HTTPS.
  • De créer un utilisateur dédié à l’ingestion avec des permissions limitées - voir ci-dessous.
  • D’activer TLS pour l’endpoint OTLP, afin de garantir une communication chiffrée entre les SDK/agents et le collector. Cela peut être configuré via la configuration personnalisée du collector.

​
Création d’un utilisateur d’ingestion

Nous recommandons de créer une base de données et un utilisateur dédiés pour le OTel collector afin d’ingérer les données dans Managed ClickStack. Ils doivent pouvoir créer des tables et y insérer des données parmi les tables créées et utilisées par ClickStack.
CREATE DATABASE otel;
CREATE USER hyperdx_ingest IDENTIFIED WITH sha256_password BY 'ClickH0u3eRocks123!';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON otel.* TO hyperdx_ingest;
Cela suppose que le collector a été configuré pour utiliser la base de données otel. Ce paramètre peut être défini via la variable d’environnement HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE. Transmettez-la au collector comme les autres variables d’environnement.

​
Traitement - filtrage, transformation et enrichissement

Les utilisateurs voudront inévitablement filtrer, transformer et enrichir les messages d’événement lors de l’ingestion. Comme la configuration du connecteur ClickStack ne peut pas être modifiée, nous recommandons aux utilisateurs qui ont besoin d’un filtrage et d’un traitement supplémentaires des événements de faire l’un des choix suivants :
  • Déployer leur propre version de l’OTel collector pour assurer le filtrage et le traitement, puis envoyer les événements au ClickStack collector via OTLP pour ingestion dans ClickHouse.
  • Déployer leur propre version de l’OTel collector et envoyer les événements directement à ClickHouse à l’aide du ClickHouse exporter.
Si le traitement est effectué à l’aide de l’OTel collector, nous recommandons d’effectuer les transformations sur les instances gateway et de réduire au minimum le travail réalisé sur les instances agent. Cela garantit que les ressources requises par les agents en périphérie, exécutés sur les serveurs, restent aussi limitées que possible. En général, nous constatons que les utilisateurs se limitent au filtrage (pour réduire l’utilisation réseau inutile), au réglage des timestamps (via des operators) et à l’enrichissement, qui nécessite du contexte dans les agents. Par exemple, si les instances gateway se trouvent dans un autre cluster Kubernetes, l’enrichissement k8s devra être effectué dans l’agent. OpenTelemetry prend en charge les fonctionnalités suivantes de traitement et de filtrage que vous pouvez exploiter :
  • Processors - Les processors prennent les données collectées par les receivers et les modifient ou les transforment avant de les envoyer aux exporters. Les processors sont appliqués dans l’ordre défini dans la section processors de la configuration du collector. Ils sont facultatifs, mais l’ensemble minimal est généralement recommandé. Lors de l’utilisation d’un OTel collector avec ClickHouse, nous recommandons de limiter les processors à :
  • Un memory_limiter est utilisé pour éviter les situations de manque de mémoire sur le collector. Consultez Estimating Resources pour obtenir des recommandations.
  • Tout processor qui effectue un enrichissement basé sur le contexte. Par exemple, le Kubernetes Attributes Processor permet de définir automatiquement les attributs de ressource des spans, metrics et logs à partir des métadonnées k8s, par exemple en enrichissant les événements avec l’identifiant de leur pod source.
  • Le sampling tail ou head si nécessaire pour les traces.
  • Le filtrage de base - suppression des événements non requis si cela ne peut pas être fait via un operator (voir ci-dessous).
  • Le batching - essentiel lorsque vous travaillez avec ClickHouse pour garantir que les données sont envoyées par lots. Voir « Optimizing inserts ».
  • Operators - Les operators constituent l’unité de traitement la plus élémentaire disponible au niveau du receiver. Le parsing de base est pris en charge, ce qui permet de définir des champs tels que Severity et Timestamp. Le parsing JSON et regex est pris en charge ici, ainsi que le filtrage des événements et les transformations de base. Nous recommandons d’effectuer le filtrage des événements à ce niveau.
Nous recommandons aux utilisateurs d’éviter un traitement excessif des événements à l’aide d’operators ou de transform processors. Ceux-ci peuvent entraîner une surcharge importante en mémoire et en CPU, en particulier le parsing JSON. Il est possible d’effectuer tout le traitement dans ClickHouse au moment de l’insert avec des materialized views et des colonnes, à quelques exceptions près - en particulier l’enrichissement sensible au contexte, par exemple l’ajout de métadonnées k8s. Pour plus de détails, voir Extracting structure with SQL.

​
Exemple

La configuration suivante montre la collecte de ce fichier de logs non structuré. Cette configuration peut être utilisée par un collector jouant le rôle d’agent pour envoyer les données vers le gateway ClickStack. Notez l’utilisation d’opérateurs pour extraire une structure à partir des lignes de logs (regex_parser) et filtrer les événements, ainsi que d’un processeur pour traiter les événements par lots et limiter l’utilisation de la mémoire.
file=code_snippets/ClickStack/config-unstructured-logs-with-processor.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-unstructured.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<ip>[\d.]+)\s+-\s+-\s+\[(?P<timestamp>[^\]]+)\]\s+"(?P<method>[A-Z]+)\s+(?P<url>[^\s]+)\s+HTTP/[^\s]+"\s+(?P<status>\d+)\s+(?P<size>\d+)\s+"(?P<referrer>[^"]*)"\s+"(?P<user_agent>[^"]*)"'
        timestamp:
          parse_from: attributes.timestamp
          layout: '%d/%b/%Y:%H:%M:%S %z'
          #22/Jan/2019:03:56:14 +0330
processors:
  batch:
    timeout: 1s
    send_batch_size: 10000
  memory_limiter:
    check_interval: 1s
    limit_mib: 2048
    spike_limit_mib: 256
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_INGESTION_API_KEY>
    compression: gzip

  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]
Notez qu’il faut inclure un en-tête d’autorisation contenant votre API key d’ingestion dans toute communication OTLP. Pour une configuration plus avancée, nous vous recommandons de consulter la documentation du collector OpenTelemetry.

​
Optimisation des insertions

Afin d’obtenir des performances d’insertion élevées tout en bénéficiant de fortes garanties de cohérence, vous devez respecter quelques règles simples lors de l’insertion de données d’observabilité dans ClickHouse via le ClickStack collector. Avec une configuration appropriée de l’OTel collector, les règles suivantes devraient être faciles à appliquer. Cela permet également d’éviter les problèmes courants que les utilisateurs rencontrent lorsqu’ils utilisent ClickHouse pour la première fois.

​
Traitement par lots

Par défaut, chaque insertion envoyée à ClickHouse amène celui-ci à créer immédiatement une part de stockage contenant les données de l’insertion ainsi que les autres métadonnées à stocker. Par conséquent, envoyer moins d’insertions, mais avec davantage de données dans chacune, plutôt qu’un plus grand nombre d’insertions plus petites, réduit le nombre d’écritures nécessaires. Nous recommandons d’insérer les données dans des lots assez volumineux d’au moins 1 000 lignes à la fois. Plus de détails ici. Par défaut, les insertions dans ClickHouse sont synchrones et idempotentes lorsqu’elles sont identiques. Pour les tables de la famille de moteurs MergeTree, ClickHouse déduplique automatiquement les insertions. Cela signifie que les insertions tolèrent des cas comme les suivants :
  • (1) Si le nœud qui reçoit les données rencontre des problèmes, la requête d’insertion expirera (ou renverra une erreur plus spécifique) et ne recevra pas d’accusé de réception.
  • (2) Si les données ont bien été écrites par le nœud, mais que l’accusé de réception ne peut pas être renvoyé à l’émetteur de la requête en raison d’interruptions réseau, l’émetteur recevra soit un timeout, soit une erreur réseau.
Du point de vue du collector, il peut être difficile de distinguer (1) de (2). Cependant, dans les deux cas, l’insertion sans accusé de réception peut simplement être relancée immédiatement. Tant que la requête d’insertion relancée contient les mêmes données dans le même ordre, ClickHouse ignorera automatiquement la nouvelle tentative si l’insertion d’origine (sans accusé de réception) a réussi. C’est pourquoi la distribution ClickStack de l’OTel collector utilise le batch processor. Cela garantit que les insertions sont envoyées sous forme de lots cohérents de lignes respectant les exigences ci-dessus. Si un collector est censé avoir un débit élevé (événements par seconde) et qu’au moins 10 000 événements peuvent être envoyés dans chaque insertion, c’est généralement le seul traitement par lots nécessaire dans le pipeline. Des valeurs allant jusqu’à 100 000 peuvent être utilisées si la mémoire le permet. Dans ce cas, le collector videra les lots avant que le timeout du batch processor ne soit atteint, ce qui garantit une faible latence de bout en bout du pipeline et des lots de taille cohérente.

​
Utiliser les insertions asynchrones

En général, les utilisateurs sont contraints d’envoyer des lots plus petits lorsque le débit d’un collector est faible, tout en s’attendant à ce que les données parviennent à ClickHouse avec une latence de bout en bout minimale. Dans ce cas, de petits lots sont envoyés lorsque le timeout du batch processor expire. Cela peut entraîner des problèmes, et c’est là que les insertions asynchrones deviennent nécessaires. Ce problème est rare si vous envoyez des données au ClickStack collector agissant comme Gateway : en jouant le rôle d’agrégateur, il atténue ce problème. Voir Rôles du collector. S’il n’est pas possible de garantir des lots volumineux, vous pouvez déléguer le traitement par lots à ClickHouse à l’aide des Asynchronous Inserts. Avec les insertions asynchrones, les données sont d’abord insérées dans un buffer, puis écrites plus tard dans le storage de la base de données, donc de manière asynchrone. Lorsque les insertions asynchrones sont activées, quand ClickHouse ① reçoit une insert query, les données de la requête sont ② immédiatement écrites dans un buffer en mémoire. Lorsque ③ le buffer est ensuite vidé, ses données sont triées puis écrites sous forme de part dans le storage de la base de données. Notez que les données ne peuvent pas être interrogées par des queries avant d’avoir été écrites dans le storage de la base de données ; le flush du buffer est configurable. Pour activer les insertions asynchrones pour le collector, ajoutez async_insert=1 à la connection string. Nous recommandons d’utiliser wait_for_async_insert=1 (valeur par défaut) afin d’obtenir des garanties de livraison ; voir ici pour plus de détails. Les données d’une insertion asynchrone sont insérées une fois le buffer de ClickHouse vidé. Cela se produit soit après dépassement de async_insert_max_data_size, soit après async_insert_busy_timeout_ms millisecondes à compter de la première requête INSERT. Si async_insert_stale_timeout_ms est défini sur une valeur non nulle, les données sont insérées après async_insert_stale_timeout_ms milliseconds à compter de la dernière requête. Vous pouvez ajuster ces paramètres pour contrôler la latence de bout en bout de votre pipeline. D’autres paramètres permettant d’ajuster le flush du buffer sont documentés ici. En général, les valeurs par défaut conviennent.
Envisagez les insertions asynchrones adaptativesDans les cas où un petit nombre d’agent est utilisé, avec un faible débit mais des exigences strictes en matière de latence de bout en bout, les insertions asynchrones adaptatives peuvent être utiles. En général, elles ne s’appliquent pas aux cas d’usage d’Observability à haut débit, comme ceux observés avec ClickHouse.
Enfin, le comportement précédent de déduplication associé aux insertions synchrones dans ClickHouse n’est pas activé par défaut lors de l’utilisation des insertions asynchrones. Si nécessaire, consultez le paramètre async_insert_deduplicate. Tous les détails sur la configuration de cette fonctionnalité sont disponibles sur cette page de documentation, ainsi que dans ce billet de blog plus approfondi.

​
Mise à l’échelle

Le ClickStack OTel collector joue le rôle d’une instance de gateway - voir Rôles des collectors. Celles-ci constituent un service autonome, généralement par centre de données ou par région. Elles reçoivent les événements des applications (ou d’autres collectors dans le rôle d’agent) via un unique endpoint OTLP. En général, un ensemble d’instances de collector est déployé, avec un load balancer prêt à l’emploi pour répartir la charge entre elles. L’objectif de cette architecture est de décharger les agents des traitements gourmands en calcul, ce qui minimise leur consommation de ressources. Ces gateways ClickStack peuvent effectuer des tâches de transformation qui, autrement, devraient être réalisées par les agents. De plus, en agrégeant les événements de nombreux agents, les gateways peuvent garantir l’envoi de lots volumineux vers ClickHouse, ce qui permet une insertion efficace. Ces collectors jouant le rôle de gateway peuvent facilement passer à l’échelle à mesure que davantage d’agents et de sources via SDK sont ajoutés et que le throughput d’événements augmente.

​
Ajouter Kafka

Les lecteurs remarqueront peut-être que les architectures ci-dessus n’utilisent pas Kafka comme file d’attente de messages. Utiliser une file Kafka comme tampon de messages est un modèle de conception courant dans les architectures de logging, popularisé par la stack ELK. Cela présente plusieurs avantages : principalement, cela permet d’obtenir de meilleures garanties de livraison des messages et de mieux gérer le backpressure. Les messages sont envoyés des agents de collecte vers Kafka puis écrits sur disque. En théorie, une instance Kafka en cluster devrait fournir un tampon de messages à haut débit, car écrire les données de façon linéaire sur disque entraîne moins de surcharge de calcul que d’analyser et de traiter un message. Dans Elastic, par exemple, la tokenization et l’indexing entraînent une surcharge importante. En éloignant les données des agents, vous réduisez également le risque de perdre des messages à cause de la rotation des logs à la source. Enfin, cela offre certaines capacités de relecture des messages et de réplication inter-région, ce qui peut être intéressant dans certains cas d’usage. Cependant, ClickHouse peut insérer des données très rapidement — des millions de lignes par seconde sur du matériel modeste. Le backpressure venant de ClickHouse est rare. Bien souvent, s’appuyer sur une file Kafka ajoute de la complexité architecturale et des coûts. Si vous acceptez le principe selon lequel les logs n’ont pas besoin des mêmes garanties de livraison que les transactions bancaires et d’autres données critiques, nous vous recommandons d’éviter la complexité de Kafka. Cependant, si vous avez besoin de fortes garanties de livraison ou de la possibilité de rejouer les données (éventuellement vers plusieurs sources), Kafka peut être un ajout architectural utile. Dans ce cas, les agents OTel peuvent être configurés pour envoyer les données à Kafka via le Kafka exporter. Les instances de gateway, à leur tour, consomment les messages à l’aide du Kafka receiver. Nous vous recommandons de consulter la documentation de Confluent et d’OTel pour plus de détails.
Configuration de l’OTel collectorLa distribution ClickStack OpenTelemetry collector peut être configurée avec Kafka à l’aide de la configuration personnalisée du collector.

​
Estimation des ressources

Les besoins en ressources de l’OTel collector dépendent du volume d’événements par seconde, de la taille des messages et du niveau de traitement appliqué. Le projet OpenTelemetry met à disposition des benchmarks que les utilisateurs peuvent utiliser pour estimer ces besoins. D’après notre expérience, une instance gateway ClickStack dotée de 3 cœurs et de 12 Go de RAM peut traiter environ 60k événements par seconde. Cela suppose un pipeline minimal, limité au renommage des champs et n’utilisant aucune expression régulière. Pour les instances agent chargées d’acheminer les événements vers une gateway et de simplement définir le timestamp sur l’événement, nous recommandons de dimensionner en fonction du volume de logs attendu par seconde. Les valeurs ci-dessous sont approximatives et peuvent servir de point de départ :
Taux de loggingRessources pour l’agent collector
1k/seconde0.2CPU, 0.2GiB
5k/seconde0.5 CPU, 0.5GiB
10k/seconde1 CPU, 1GiB

​
Choix du schéma : Map vs JSON

Le collector ClickStack crée par défaut des tables qui stockent les attributs dans des colonnes Map(LowCardinality(String), String). Il s’agit du schéma recommandé pour les workloads d’observabilité. Un schéma de type JSON est disponible en bêta pour l’évaluation sur des workloads disposant d’un ensemble de clés d’attributs réduit et stable. Pour une comparaison complète, savoir dans quels cas chacun convient, connaître les variables d’environnement requises pour activer le schéma de type JSON et suivre le guide de migration, consultez Map vs JSON type.
Dernière modification le 25 juin 2026