Saltar al contenido principal
OpenTelemetry es un estándar abierto para recopilar trazas y métricas de aplicaciones distribuidas. ClickHouse ofrece cierta compatibilidad con OpenTelemetry.

​
Proporcionar el contexto de traza a ClickHouse

ClickHouse acepta encabezados HTTP de contexto de traza, como se describe en la recomendación del W3C. También acepta contexto de traza a través de un protocolo nativo que se utiliza para la comunicación entre servidores de ClickHouse o entre el cliente y el servidor. Para realizar pruebas manuales, se pueden proporcionar a clickhouse-client encabezados de contexto de traza conformes con la recomendación Trace Context mediante las opciones --opentelemetry-traceparent y --opentelemetry-tracestate. Si no se proporciona un contexto de traza padre, o si el contexto de traza proporcionado no cumple con el estándar W3C mencionado anteriormente, ClickHouse puede iniciar una nueva traza, con una probabilidad controlada por la configuración opentelemetry_start_trace_probability.

​
Propagación del contexto de traza

El contexto de traza se propaga a los servicios posteriores en los siguientes casos:
  • Consultas a servidores remotos de ClickHouse, como cuando se usa el motor de tabla Distributed.
  • Función de tabla url. La información del contexto de traza se envía en las cabeceras HTTP.

​
Trazado de solicitudes de ClickHouse Keeper

ClickHouse admite trazado de OpenTelemetry para las solicitudes de ClickHouse Keeper (servicio de coordinación compatible con ZooKeeper). Esta función proporciona visibilidad detallada del ciclo de vida de las operaciones de Keeper, desde el envío de la solicitud por parte del cliente hasta su procesamiento en el servidor.

​
Habilitar el trazado de Keeper

Para habilitar el trazado de las solicitudes a Keeper, configure los siguientes ajustes en la configuración de su cliente de ZooKeeper/Keeper:

​
Tipos de spans de Keeper

Cuando el trazado está habilitado, ClickHouse crea spans tanto para las operaciones de Keeper en el cliente como en el servidor: Spans del lado del cliente:
  • zookeeper.create — Crear un nodo
  • zookeeper.get — Obtener los datos del nodo
  • zookeeper.set — Establecer los datos del nodo
  • zookeeper.remove — Eliminar un nodo
  • zookeeper.list — Enumerar los nodos hijos
  • zookeeper.exists — Comprobar si existe un nodo
  • zookeeper.multi — Ejecutar varias operaciones de forma atómica
  • zookeeper.client.requests_queue — Tiempo empleado en poner en cola las solicitudes antes de enviarlas
Spans del lado del servidor (Keeper):
  • keeper.receive_request — Recepción y análisis de la solicitud del cliente
  • keeper.dispatcher.requests_queue — Puesta en cola de solicitudes en el dispatcher
  • keeper.write.pre_commit — Preprocesamiento de solicitudes de escritura antes del commit de Raft
  • keeper.write.commit — Procesamiento de solicitudes de escritura después del commit de Raft
  • keeper.read.wait_for_write — Solicitudes de lectura en espera de escrituras de las que dependen
  • keeper.read.process — Procesamiento de solicitudes de lectura
  • keeper.dispatcher.responses_queue — Puesta en cola de respuestas en el dispatcher
  • keeper.send_response — Envío de la respuesta al cliente

​
Muestreo y rendimiento

Para gestionar la sobrecarga del trazado, Keeper implementa muestreo dinámico. La tasa de muestreo se ajusta automáticamente entre 1/10,000 y 1/10 en función del tamaño de la solicitud. La duración de todas las solicitudes (muestreadas y no muestreadas) se registra en métricas de histograma para supervisar el rendimiento.

​
Trazado del propio ClickHouse

ClickHouse crea trace spans para cada consulta y para algunas etapas de ejecución de la consulta, como la planificación de consultas o las consultas distribuidas. Para que sea útil, la información de trazado debe exportarse a un sistema de monitorización compatible con OpenTelemetry, como Jaeger o Prometheus. ClickHouse evita depender de un sistema de monitorización concreto y, en su lugar, solo proporciona los datos de trazado a través de una tabla del sistema. La información de OpenTelemetry sobre trace spans requerida por el estándar se almacena en la tabla system.opentelemetry_span_log. La tabla debe estar habilitada en la configuración del servidor; consulte el elemento opentelemetry_span_log en el archivo de configuración predeterminado config.xml. Está habilitada de forma predeterminada. Las etiquetas o atributos se guardan como dos arrays paralelos que contienen las claves y los valores. Use ARRAY JOIN para trabajar con ellos.

​
Log-query-settings

La configuración log_query_settings permite registrar los cambios en los ajustes de la consulta durante su ejecución. Cuando está habilitada, cualquier modificación realizada en los ajustes de la consulta se registrará en el registro del span de OpenTelemetry. Esta función resulta especialmente útil en entornos de producción para hacer un seguimiento de los cambios de configuración que pueden afectar al rendimiento de la consulta.

​
Integración con sistemas de monitoreo

Por el momento, no existe una herramienta lista que pueda exportar los datos de trazado de ClickHouse a un sistema de monitoreo. Para realizar pruebas, es posible configurar la exportación mediante una vista materializada con el motor URL sobre la tabla system.opentelemetry_span_log, que enviaría los datos de log a medida que llegan a un endpoint HTTP de un collector de traces. Por ejemplo, para enviar los datos mínimos de span a una instancia de Zipkin que se ejecuta en http://localhost:9411, en formato JSON v2 de Zipkin:
En caso de error, la parte de los datos de registro en la que se haya producido se perderá sin aviso. Consulte el log del servidor para ver los mensajes de error si los datos no llegan.

​
Contenido relacionado

Última modificación el 25 de junio de 2026