Ingestión con OpenTelemetry

Todos los datos se ingieren en ClickStack a través de una instancia de OpenTelemetry (OTel) collector, que actúa como punto de entrada principal para logs, métricas, traces y datos de sesión. Recomendamos usar la distribución oficial de ClickStack del collector para esta instancia.

Los usuarios envían datos a este collector desde SDKs de distintos lenguajes o mediante agentes de recopilación de datos que recogen métricas de infraestructura y logs (como OTel collectors en un rol de agent u otras tecnologías, p. ej., Fluentd o Vector). Para los equipos que quieren un pipeline de OpenTelemetry gestionado, Bindplane ofrece una solución nativa de OpenTelemetry con un destino nativo de ClickStack, lo que simplifica la recopilación, el procesamiento y el enrutamiento de la telemetría.

Enviar datos de OpenTelemetry

Instalación del ClickStack OpenTelemetry collector

Para enviar datos a Managed ClickStack, se debe desplegar un OTel collector en un rol de gateway. La instrumentación compatible con OTel enviará eventos a este collector mediante OTLP sobre HTTP o gRPC.

Para obtener más información, consulte "Despliegue del collector".

Envío de datos al collector

Para enviar datos a Managed ClickStack, dirija su instrumentación de OpenTelemetry a los siguientes endpoints expuestos por el OpenTelemetry collector:

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

Para los SDK de lenguaje y las bibliotecas de telemetría compatibles con OpenTelemetry, puede simplemente configurar la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en su aplicación:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Si despliega una distribución contrib del OTel collector en el rol de agente, puede usar el exportador OTLP para enviar datos al ClickStack collector. A continuación se muestra una configuración de ejemplo de un agente que consume este archivo de logs estructurado.

# 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]

El ClickStack OpenTelemetry collector está incluido en la mayoría de las distribuciones de ClickStack, entre ellas:

Instalación de ClickStack OpenTelemetry collector

El OTel collector de ClickStack también puede desplegarse de forma independiente, sin depender de otros componentes de la pila.

Si usas la distribución HyperDX-only, eres responsable de enviar los datos a ClickHouse por tu cuenta. Esto puede hacerse de las siguientes formas:

Ejecutando tu propio OpenTelemetry collector y configurándolo para que apunte a ClickHouse; consulta más abajo.
Enviando directamente a ClickHouse con herramientas alternativas, como Vector, Fluentd, etc., o incluso la distribución predeterminada de OTel contrib collector.

Para obtener más información, consulta "Despliegue del collector".

Envío de datos al collector

Para enviar datos a ClickStack, apunta tu instrumentación de OpenTelemetry a los siguientes endpoints expuestos por el OpenTelemetry collector:

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

Para los SDKs de lenguaje y las bibliotecas de telemetría compatibles con OpenTelemetry, puedes simplemente establecer la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en tu aplicación:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Además, se requiere un header de autorización que contenga la clave de ingestión de API. Puedes encontrar la clave en la aplicación HyperDX, en Team Settings → API Keys.

En los SDKs de lenguaje, esto puede configurarse mediante una función init o a través de la variable de entorno OTEL_EXPORTER_OTLP_HEADERS, por ejemplo:

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

Los agentes deben incluir asimismo este encabezado de autorización en cualquier comunicación OTLP. Por ejemplo, si se despliega una distribución contrib del OTel collector en el rol de agente, se puede usar el exportador OTLP. A continuación se muestra un ejemplo de configuración de un agente que consume este archivo de registro estructurado. Tenga en cuenta que es necesario especificar una clave de autorización; consulte <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]