Ingestion avec OpenTelemetry

Toutes les données sont ingérées dans ClickStack via une instance de collector OpenTelemetry (OTel), qui sert de point d'entrée principal pour les logs, les métriques, les traces et les données de session. Nous recommandons d'utiliser pour cette instance la distribution ClickStack officielle du collector.

Les utilisateurs envoient les données vers ce collector depuis les language SDKs ou via des agents de collecte qui récupèrent les métriques d'infrastructure et les logs (comme des OTel collectors dans un rôle d'agent, ou d'autres technologies telles que Fluentd ou Vector). Pour les équipes qui souhaitent un pipeline OpenTelemetry managé, Bindplane propose une solution native OpenTelemetry avec une destination ClickStack native, ce qui simplifie la collecte, le traitement et le routage de la télémétrie.

Envoi de données OpenTelemetry

Installer le ClickStack OpenTelemetry collector

Pour envoyer des données à Managed ClickStack, un OTel collector doit être déployé dans un rôle de gateway. Une instrumentation compatible OTel enverra les événements à ce collector via OTLP sur HTTP ou gRPC.

Pour plus de détails, consultez "Déployer le collector".

Envoyer des données au collector

Pour envoyer des données à Managed ClickStack, faites pointer votre instrumentation OpenTelemetry vers les points de terminaison suivants exposés par l'OpenTelemetry collector :

HTTP (OTLP) : http://localhost:4318
gRPC (OTLP) : localhost:4317

Pour les language SDKs et les bibliothèques de télémétrie compatibles avec OpenTelemetry, vous pouvez simplement définir la variable d'environnement OTEL_EXPORTER_OTLP_ENDPOINT dans votre application :

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Si vous déployez une distribution contrib de l’OTel collector dans le rôle d’agent, vous pouvez utiliser l’exporter OTLP pour envoyer les données au ClickStack collector. Un exemple de configuration d’agent utilisant ce fichier journal structuré est présenté ci-dessous.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
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]

Le ClickStack OpenTelemetry collector est inclus dans la plupart des distributions ClickStack, notamment :

Installation du ClickStack OpenTelemetry collector

Le ClickStack OTel collector peut également être déployé en mode autonome, indépendamment des autres composants de la stack.

Si vous utilisez la distribution HyperDX-only, c’est à vous d’acheminer les données vers ClickHouse. Vous pouvez procéder de plusieurs façons :

Exécuter votre propre OpenTelemetry collector et le configurer pour qu’il envoie les données vers ClickHouse — voir ci-dessous.
Envoyer les données directement vers ClickHouse à l’aide d’autres outils, comme Vector, Fluentd, etc., ou même la distribution OTel contrib collector par défaut.

Pour en savoir plus, consultez "Déployer le collector".

Envoyer des données au collector

Pour envoyer des données à ClickStack, configurez votre instrumentation OpenTelemetry pour qu’elle utilise les points de terminaison suivants, exposés par l’OpenTelemetry collector :

HTTP (OTLP) : http://localhost:4318
gRPC (OTLP) : localhost:4317

Pour les language SDKs et les bibliothèques de télémétrie compatibles avec OpenTelemetry, vous pouvez simplement définir la variable d’environnement OTEL_EXPORTER_OTLP_ENDPOINT dans votre application :

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

De plus, un en-tête d’autorisation contenant la clé d’ingestion de l’API est nécessaire. Vous trouverez cette clé dans l’application HyperDX, dans Team Settings → API Keys.

Pour les language SDKs, vous pouvez ensuite la définir soit dans une fonction init, soit via la variable d’environnement OTEL_EXPORTER_OTLP_HEADERS, par ex. :

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

Les agents doivent eux aussi inclure cet en-tête d’autorisation dans toute communication OTLP. Par exemple, si vous déployez une distribution contrib de l’OTel collector dans le rôle d’agent, vous pouvez utiliser l’exporteur OTLP. Un exemple de configuration d’agent qui consomme ce fichier de logs structuré est présenté ci-dessous. Notez qu’il est nécessaire de spécifier une clé d’autorisation - voir <YOUR_API_INGESTION_KEY>.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
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]