Ingestión con OpenTelemetry

Ingestión de datos con OpenTelemetry para ClickStack - La pila de observabilidad de ClickHouse

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.

También hay disponible una versión gestionada de ClickStack; consulta Managed ClickStack.

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

Managed ClickStack

​

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.

Recomendamos usar el ClickStack OpenTelemetry collector

Esto le permite beneficiarse de una ingestión estandarizada, esquemas aplicados y compatibilidad inmediata con la interfaz de usuario de ClickStack (HyperDX). El uso del esquema predeterminado habilita la detección automática de fuentes y asignaciones de columnas preconfiguradas.

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:
  # Configuración HTTP
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # Configuración gRPC (alternativa)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modificado porque hay 2 collectors ejecutándose en el mismo host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

ClickStack Open Source

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

• All-in-One
• Docker Compose
• Helm

​

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.

Recomendamos usar ClickStack OpenTelemetry collector

Esto te permite beneficiarte de una ingestión estandarizada, esquemas aplicados y compatibilidad inmediata con la UI de HyperDX. Usar el esquema predeterminado habilita la detección automática de fuentes y asignaciones de columnas preconfiguradas.

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:
  # Configuración HTTP
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # Configuración gRPC (alternativa)
  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 # Modificado porque hay 2 collectors ejecutándose en el mismo host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]