Saltar al contenido principal
Prueba OTel FYI: documentación simplificada del OTel collectorOTel FYI ofrece documentación clara y concisa sobre el OpenTelemetry collector, incluidos receivers, processors, exporters y canalizaciones. Es un excelente recurso complementario para configurar el OTel collector de ClickStack.
Esta página incluye detalles para configurar el OpenTelemetry (OTel) collector oficial de ClickStack.

​
Roles del collector

Los collectors de OpenTelemetry pueden implementarse en dos roles principales:
  • Agente - Las instancias de agente recopilan datos en el extremo, por ejemplo, en servidores o nodos de Kubernetes, o reciben eventos directamente de aplicaciones instrumentadas con un SDK de OpenTelemetry. En este último caso, la instancia de agente se ejecuta junto con la aplicación o en el mismo host que esta (como un sidecar o un conjunto de daemon). Los agentes pueden enviar sus datos directamente a ClickHouse o a una instancia de gateway. En el primer caso, esto se conoce como patrón de implementación de agente.
  • Gateway - Las instancias de gateway proporcionan un servicio independiente (por ejemplo, una Implementación en Kubernetes), normalmente por clúster, centro de datos o región. Reciben eventos de aplicaciones (u otros collectors que actúan como agentes) a través de un único endpoint de OTLP. Normalmente, se implementa un conjunto de instancias de gateway, con un balanceador de carga listo para usar para distribuir la carga entre ellas. Si todos los agentes y las aplicaciones envían sus señales a este único endpoint, suele denominarse patrón de implementación de gateway.
Importante: El collector, incluso en las distribuciones predeterminadas de ClickStack, asume el rol de gateway descrito a continuación, y recibe datos de agentes o SDKs. Los usuarios que implementen OTel collectors en el rol de agente normalmente usarán la distribución contrib predeterminada del collector y no la versión de ClickStack, aunque pueden usar otras tecnologías compatibles con OTLP, como Fluentd y Vector.

​
Despliegue del collector


Cuando sea posible, recomendamos utilizar la distribución oficial de ClickStack del collector para el rol de gateway al enviar datos a Managed ClickStack. Si decide usar el suyo propio, asegúrese de que incluya el exporter de ClickHouse.El collector puede implementarse mediante Helm (recomendado para Kubernetes) o mediante Docker. El gráfico de Helm de ClickStack oficial incorpora el gráfico de Helm del OpenTelemetry Collector como un subchart con la imagen de distribución de ClickStack preconfigurada; consulte la guía de implementación de ClickStack con Helm si desea instalar el stack completo, incluido HyperDX. Para una implementación standalone del collector, el chart upstream puede utilizarse directamente con la imagen de ClickStack, tal como se muestra a continuación.
Añada el repositorio de Helm oficial de OpenTelemetry:
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
Cree un values.yaml para configurar la imagen de ClickStack y las credenciales 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>"
Instale el chart:
helm install clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
Para implementaciones de producción, recomendamos almacenar CLICKHOUSE_PASSWORD en un Secret de Kubernetes y hacer referencia a él mediante extraEnvsFrom en lugar de incluir el valor directamente.
La instancia de ClickHouse de destino se configura mediante las variables de entorno CLICKHOUSE_ENDPOINT, CLICKHOUSE_USERNAME y CLICKHOUSE_PASSWORD. El valor de CLICKHOUSE_ENDPOINT debe ser el endpoint HTTP completo de ClickHouse Cloud, incluyendo el protocolo y el puerto; por ejemplo, https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443.Para obtener más información sobre cómo recuperar sus credenciales de Managed ClickStack, consulte aquí.
Usuario para producciónEn producción, debe usar un usuario con las credenciales adecuadas.

​
Modificación de la configuración

​
Configuración de la instancia de Managed ClickStack

El OpenTelemetry collector puede configurarse para usar una instancia de Managed ClickStack mediante las variables de entorno CLICKHOUSE_ENDPOINT, CLICKHOUSE_USERNAME y CLICKHOUSE_PASSWORD. La forma en que se configuran depende del método de implementación:
Sobrescribe las entradas correspondientes en extraEnvs de tu values.yaml y, a continuación, actualiza 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

​
Extensión de la configuración del collector

La distribución ClickStack del OTel collector permite ampliar la configuración base montando un archivo de configuración personalizado y estableciendo una variable de entorno.Para añadir receiver, processor o pipelines personalizados:
  1. Cree un archivo de configuración personalizado con la configuración adicional
  2. Monte el archivo en /etc/otelcol-contrib/custom.config.yaml
  3. Establezca la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Ejemplo de configuración personalizada:
receivers:
  # Recopilar registros de archivos locales
  filelog:
    include:
      - /var/log/**/*.log
      - /var/log/syslog
      - /var/log/messages
    start_at: beginning

  # Recopilar métricas del sistema host
  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:
    # Pipeline de logs
    logs/host:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
    
    # Pipeline de métricas
    metrics/hostmetrics:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - batch
      exporters:
        - clickhouse
Implemente con el collector independiente:
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
Solo debes definir nuevos receiver, processor y pipelines en la configuración personalizada. Los processor base (memory_limiter, batch) y los exportadores (clickhouse) ya están definidos; haz referencia a ellos por su nombre. La configuración personalizada se fusiona con la configuración base y no puede sobrescribir componentes existentes.
Para configuraciones más complejas, consulta la configuración predeterminada del ClickStack collector y la documentación del exportador de ClickHouse.

​
Estructura de la configuración

Para obtener más información sobre la configuración de los OTel collectors, incluidos receivers, operators y processors, recomendamos consultar la documentación oficial de OpenTelemetry Collector.

​
Docker Compose

Con Docker Compose, modifique la configuración del collector usando las mismas variables de entorno mencionadas anteriormente:
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' # extensión health_check
      - '24225:24225' # receptor fluentd
      - '4317:4317' # receptor OTLP gRPC
      - '4318:4318' # receptor OTLP HTTP
      - '8888:8888' # extensión de métricas
    volumes:
      - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
    restart: always
    networks:
      - internal

​
Protección del collector

De forma predeterminada, el ClickStack OpenTelemetry collector no está protegido cuando se implementa fuera de las distribuciones open source y no requiere autenticación en sus puertos OTLP.Para proteger la ingestión, especifica un token de autenticación al implementar el collector mediante la variable de entorno OTLP_AUTH_TOKEN. La forma de configurarlo depende del método de implementación:
Agrega OTLP_AUTH_TOKEN a extraEnvs en tu values.yaml y, a continuación, actualiza 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
Para implementaciones en producción, recomendamos almacenar OTLP_AUTH_TOKEN y CLICKHOUSE_PASSWORD en un secret de Kubernetes y hacer referencia a ellos mediante extraEnvsFrom.
Además, recomendamos:
  • Configurar el collector para que se comunique con ClickHouse a través de HTTPS.
  • Crear un usuario dedicado para la ingestión con permisos limitados; consulta la sección siguiente.
  • Habilitar TLS para el endpoint de OTLP, garantizando la comunicación cifrada entre los SDKs/agentes y el collector. Esto se puede configurar mediante la configuración personalizada del collector.

​
Crear un usuario de ingestión

Recomendamos crear una base de datos y un usuario dedicados para que el OTel collector realice la ingestión en Managed ClickStack. Este usuario debe poder crear e insertar datos en las tablas creadas y utilizadas por 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;
Esto supone que el collector se ha configurado para usar la base de datos otel. Esto se puede controlar mediante la variable de entorno HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE. Pásala al collector de forma similar a otras variables de entorno.

​
Procesamiento: filtrado, transformación y enriquecimiento

Los usuarios querrán filtrar, transformar y enriquecer los mensajes de eventos durante la ingestión. Dado que la configuración del conector de ClickStack no puede modificarse, recomendamos a quienes necesiten filtrado y procesamiento adicionales de eventos que hagan una de estas dos cosas:
  • Desplegar su propia versión del OTel collector para realizar el filtrado y el procesamiento, enviando los eventos al ClickStack collector mediante OTLP para su ingestión en ClickHouse.
  • Desplegar su propia versión del OTel collector y enviar los eventos directamente a ClickHouse mediante el exporter de ClickHouse.
Si el procesamiento se realiza con el OTel collector, recomendamos hacer las transformaciones en instancias gateway y minimizar cualquier trabajo realizado en instancias agente. Esto garantiza que los recursos requeridos por los agentes en el edge, que se ejecutan en servidores, sean mínimos. Normalmente, vemos que los usuarios solo realizan filtrado (para minimizar el uso innecesario de la red), configuración de timestamp (mediante operators) y enriquecimiento, que requiere contexto en los agentes. Por ejemplo, si las instancias gateway residen en un cluster de Kubernetes distinto, el enriquecimiento de k8s tendrá que hacerse en el agente. OpenTelemetry admite las siguientes funcionalidades de procesamiento y filtrado que puede aprovechar:
  • Processors - Los processors toman los datos recopilados por los receiver y los modifican o transforman antes de enviarlos a los exporters. Los processors se aplican en el orden en que están configurados en la sección processors de la configuración del collector. Son opcionales, pero normalmente se recomienda un conjunto mínimo. Al usar un OTel collector con ClickHouse, recomendamos limitar los processors a:
  • Un memory_limiter se usa para evitar situaciones de falta de memoria en el collector. Consulte Estimating Resources para ver recomendaciones.
  • Cualquier processor que realice enriquecimiento en función del contexto. Por ejemplo, el Kubernetes Attributes Processor permite establecer automáticamente atributos de recursos de spans, métricas y logs con metadatos de k8s; por ejemplo, enriqueciendo eventos con el ID de su pod de Kubernetes de origen.
  • Tail or head sampling si es necesario para traces.
  • Basic filtering - descarte de eventos que no sean necesarios si esto no puede hacerse mediante operator (véase más abajo).
  • Batching - esencial al trabajar con ClickHouse para garantizar que los datos se envíen en batches. Consulte “Optimizing inserts”.
  • Operators - Los Operators proporcionan la unidad de procesamiento más básica disponible en el receiver. Se admite parsing básico, lo que permite establecer campos como Severity y Timestamp. Aquí se admiten el parsing de JSON y regex, junto con el filtrado de eventos y transformaciones básicas. Recomendamos realizar aquí el filtrado de eventos.
Recomendamos a los usuarios evitar un procesamiento excesivo de eventos mediante operators o transform processors. Estos pueden generar una sobrecarga considerable de memoria y CPU, especialmente el parsing de JSON. Es posible realizar todo el procesamiento en ClickHouse en el momento del insert mediante vistas materializadas y columnas, con algunas excepciones; en concreto, el enriquecimiento dependiente del contexto, por ejemplo, la adición de metadatos de k8s. Para obtener más detalles, consulte Extracting structure with SQL.

​
Ejemplo

La siguiente configuración muestra la recopilación de este archivo de logs no estructurado. Esta configuración podría utilizarla un collector en el rol de agente para enviar datos al gateway de ClickStack. Observe el uso de operadores para extraer la estructura de las líneas de log (regex_parser) y filtrar eventos, junto con un processor para agrupar eventos en lotes y limitar el uso de memoria.
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:
  # Configuración HTTP
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_INGESTION_API_KEY>
    compression: gzip

  # Configuración gRPC (alternativa)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
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]
Ten en cuenta que es necesario incluir un encabezado de autorización que contenga tu API key de ingesta en cualquier comunicación OTLP. Para una configuración más avanzada, te recomendamos consultar la documentación del OpenTelemetry Collector.

​
Optimización de las inserciones

Para lograr un alto rendimiento de inserción sin renunciar a sólidas garantías de consistencia, debe seguir unas reglas sencillas al insertar datos de observabilidad en ClickHouse mediante el ClickStack collector. Con la configuración correcta del OTel collector, estas reglas deberían ser fáciles de seguir. Esto también ayuda a evitar problemas comunes con los que se encuentran los usuarios cuando usan ClickHouse por primera vez.

​
Agrupación por lotes

De forma predeterminada, cada inserción enviada a ClickHouse hace que ClickHouse cree inmediatamente una parte de almacenamiento que contiene los datos de la inserción junto con otros metadatos que deben almacenarse. Por lo tanto, enviar menos inserciones con más datos en cada una, en lugar de más inserciones con menos datos en cada una, reduce el número de escrituras necesarias. Recomendamos insertar datos en lotes relativamente grandes de al menos 1.000 filas cada vez. Más detalles aquí. De forma predeterminada, las inserciones en ClickHouse son síncronas e idempotentes si son idénticas. En las tablas de la familia de motores MergeTree, ClickHouse deduplica automáticamente las inserciones de forma predeterminada. Esto significa que las inserciones toleran casos como los siguientes:
  • (1) Si el nodo que recibe los datos tiene problemas, la consulta de inserción agotará el tiempo de espera (o devolverá un error más específico) y no se recibirá ninguna confirmación.
  • (2) Si el nodo escribió los datos, pero la confirmación no puede devolverse al remitente de la consulta debido a interrupciones de red, el remitente recibirá un timeout o un error de red.
Desde la perspectiva del collector, (1) y (2) pueden ser difíciles de distinguir. Sin embargo, en ambos casos, la inserción sin confirmar puede reintentarse de inmediato. Siempre que la consulta de inserción reintentada contenga los mismos datos en el mismo orden, ClickHouse ignorará automáticamente la inserción reintentada si la inserción original (sin confirmar) se realizó correctamente. Por esta razón, la distribución ClickStack del OTel collector usa el batch processor. Esto garantiza que las inserciones se envíen como lotes consistentes de filas que cumplen los requisitos anteriores. Si se espera que un collector tenga un alto rendimiento (eventos por segundo) y que puedan enviarse al menos 10.000 eventos en cada inserción, normalmente este es el único procesamiento por lotes necesario en la canalización. Pueden usarse valores de hasta 100.000 si la memoria lo permite. En este caso, el collector vaciará los lotes antes de que se alcance el timeout del batch processor, lo que garantiza que la latencia de extremo a extremo de la canalización siga siendo baja y que los lotes tengan un tamaño uniforme.

​
Usa inserciones asíncronas

Normalmente, los usuarios se ven obligados a enviar lotes más pequeños cuando el throughput de un collector es bajo, y aun así esperan que los datos lleguen a ClickHouse con una latencia mínima de extremo a extremo. En este caso, se envían lotes pequeños cuando expira el timeout del processor por lotes. Esto puede causar problemas, y es entonces cuando se requieren inserciones asíncronas. Este problema es poco frecuente si envías datos al ClickStack collector actuando como Gateway; al actuar como agregadores, mitigan este problema. Consulta Roles del collector. Si no se pueden garantizar lotes grandes, puedes delegar la agrupación por lotes en ClickHouse mediante inserciones asíncronas. Con las inserciones asíncronas, los datos se insertan primero en un búfer y después se escriben en el almacenamiento de la base de datos más tarde, es decir, de forma asíncrona. Con las inserciones asíncronas habilitadas, cuando ClickHouse ① recibe una consulta de inserción, los datos de la consulta ② se escriben inmediatamente en un búfer en memoria. Cuando ③ se produce el siguiente vaciado del búfer, los datos del búfer se ordenan y se escriben como una parte en el almacenamiento de la base de datos. Ten en cuenta que los datos no se pueden consultar antes de vaciarse en el almacenamiento de la base de datos; el vaciado del búfer es configurable. Para habilitar las inserciones asíncronas para el collector, añade async_insert=1 a la cadena de conexión. Recomendamos usar wait_for_async_insert=1 (el valor predeterminado) para obtener garantías de entrega; consulta aquí para más detalles. Los datos de una inserción asíncrona se insertan una vez que se vacía el búfer de ClickHouse. Esto ocurre cuando se supera async_insert_max_data_size o tras async_insert_busy_timeout_ms milisegundos desde la primera consulta INSERT. Si async_insert_stale_timeout_ms se establece en un valor distinto de cero, los datos se insertan después de async_insert_stale_timeout_ms milliseconds desde la última consulta. Puedes ajustar estas opciones para controlar la latencia de extremo a extremo de la canalización. Otras opciones que pueden usarse para ajustar el vaciado del búfer están documentadas aquí. En general, los valores predeterminados son adecuados.
Considera las inserciones asíncronas adaptativasEn los casos en que se utiliza un número reducido de agentes, con bajo throughput pero requisitos estrictos de latencia de extremo a extremo, las inserciones asíncronas adaptativas pueden ser útiles. En general, no suelen ser aplicables a casos de uso de observabilidad de alto throughput, como los habituales en ClickHouse.
Por último, el comportamiento anterior de deduplicación asociado a las inserciones síncronas en ClickHouse no está habilitado de forma predeterminada cuando se usan inserciones asíncronas. Si es necesario, consulta la opción async_insert_deduplicate. Los detalles completos sobre cómo configurar esta funcionalidad se pueden encontrar en esta página de documentación o en esta entrada del blog con un análisis en profundidad.

​
Escalado

El OTel collector de ClickStack actúa como una instancia de gateway; consulta Roles del collector. Estas proporcionan un servicio independiente, normalmente por centro de datos o por región. Reciben eventos de las aplicaciones (o de otros collectors en el rol de agente) a través de un único endpoint de OTLP. Normalmente, se despliega un conjunto de instancias de collector, con un balanceador de carga listo para usar que distribuye la carga entre ellas. El objetivo de esta arquitectura es descargar de los agentes el procesamiento con uso intensivo de cómputo, minimizando así su consumo de recursos. Estos gateways de ClickStack pueden realizar tareas de transformación que, de otro modo, tendrían que ejecutar los agentes. Además, al agregar eventos de muchos agentes, los gateways pueden garantizar que se envíen grandes lotes a ClickHouse, lo que permite una inserción eficiente. Estos collectors gateway pueden escalarse fácilmente a medida que se añaden más agentes y fuentes de SDK, y aumenta el caudal de eventos.

​
Añadir Kafka

Los lectores pueden notar que las arquitecturas anteriores no usan Kafka como cola de mensajes. Usar una cola de Kafka como búfer de mensajes es un patrón de diseño popular en arquitecturas de logging y fue popularizado por la pila ELK. Ofrece varias ventajas: principalmente, ayuda a proporcionar garantías de entrega de mensajes más sólidas y a gestionar la contrapresión. Los mensajes se envían desde los agentes de recopilación a Kafka y se escriben en disco. En teoría, una instancia de Kafka en clúster debería proporcionar un búfer de mensajes de alto rendimiento, ya que escribir datos secuencialmente en disco implica menos sobrecarga computacional que analizar y procesar un mensaje. En Elastic, por ejemplo, la tokenización y la indexación suponen una sobrecarga significativa. Al alejar los datos de los agentes, también se reduce el riesgo de perder mensajes como resultado de la rotación de logs en el origen. Por último, ofrece ciertas capacidades de reprocesamiento de mensajes y replicación entre regiones, lo que puede resultar atractivo para algunos casos de uso. Sin embargo, ClickHouse puede insertar datos muy rápidamente: millones de filas por segundo con hardware moderado. La contrapresión desde ClickHouse es poco frecuente. A menudo, usar una cola de Kafka implica más complejidad arquitectónica y más coste. Si puede asumir el principio de que los logs no necesitan las mismas garantías de entrega que las transacciones bancarias y otros datos de misión crítica, recomendamos evitar la complejidad de Kafka. Sin embargo, si necesita altas garantías de entrega o la capacidad de reprocesar datos (potencialmente hacia múltiples destinos), Kafka puede ser una incorporación útil a la arquitectura. En este caso, los agentes de OTel pueden configurarse para enviar datos a Kafka mediante el exporter de Kafka. A su vez, las instancias gateway consumen mensajes mediante el receiver de Kafka. Recomendamos consultar la documentación de Confluent y de OTel para obtener más detalles.
Configuración del OTel collectorLa distribución ClickStack OpenTelemetry collector puede configurarse con Kafka mediante la configuración personalizada del collector.

​
Estimación de recursos

Los requisitos de recursos del OTel collector dependerán del volumen de eventos, del tamaño de los mensajes y de la cantidad de procesamiento que se realice. El proyecto OpenTelemetry mantiene benchmarks que los usuarios pueden usar para estimar los requisitos de recursos. Según nuestra experiencia, una instancia gateway de ClickStack con 3 núcleos y 12 GB de RAM puede gestionar alrededor de 60 000 eventos por segundo. Esto asume una canalización de procesamiento mínimo, encargada de renombrar fields y sin regular expressions. Para las instancias agente encargadas de enviar eventos a un gateway y únicamente de establecer el timestamp del evento, recomendamos dimensionarlas en función de los logs por segundo previstos. Las siguientes cifras son aproximadas y pueden usarse como punto de partida:
Tasa de loggingRecursos para el collector agente
1k/segundo0.2CPU, 0.2GiB
5k/segundo0.5 CPU, 0.5GiB
10k/segundo1 CPU, 1GiB

​
Elección del esquema: Map vs JSON

El collector de ClickStack crea tablas que almacenan atributos como columnas Map(LowCardinality(String), String) de forma predeterminada. Este es el esquema recomendado para las cargas de trabajo de observabilidad. También está disponible, en beta, un esquema de tipo JSON para evaluarlo en cargas de trabajo con un conjunto pequeño y estable de claves de atributos. Para ver la comparación completa, cuándo conviene usar cada uno, las variables de entorno necesarias para habilitar el esquema de tipo JSON y la guía de migración, consulta Map vs tipo JSON.
Última modificación el 10 de junio de 2026