> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Guía para usar OpenTelemetry para el trazado distribuido y la recopilación de métricas en ClickHouse

# Trazado de ClickHouse con OpenTelemetry

[OpenTelemetry](https://opentelemetry.io/) es un estándar abierto para recopilar trazas y métricas de aplicaciones distribuidas. ClickHouse ofrece cierta compatibilidad con OpenTelemetry.

<h2 id="supplying-trace-context-to-clickhouse">
  Proporcionar el contexto de traza a ClickHouse
</h2>

ClickHouse acepta encabezados HTTP de contexto de traza, como se describe en la [recomendación del W3C](https://www.w3.org/TR/trace-context/). 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](/es/reference/settings/session-settings/opentelemetry-start#opentelemetry_start_trace_probability).

<h2 id="propagating-the-trace-context">
  Propagación del contexto de traza
</h2>

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](/es/reference/engines/table-engines/special/distributed).

* Función de tabla [url](/es/reference/functions/table-functions/url). La información del contexto de traza se envía en las cabeceras HTTP.

<h2 id="spans-of-distributed-queries">
  Spans de consultas distribuidas
</h2>

En un `SELECT` distribuido, cada lectura de un segmento remoto queda cubierta por un span `RemoteQueryExecutor::execute`. Estos spans llevan atributos que identifican el fragmento de la consulta:

* `clickhouse.cluster` y `clickhouse.shard_num`: el cluster y el segmento desde el que lee el executor;
* `clickhouse.query_id` y `clickhouse.initial_query_id`: los identificadores de consulta desde la perspectiva del initiator;
* `clickhouse.target_host`: las direcciones de las conexiones establecidas.

El `status_code` de dicho span indica cómo terminó el fragmento:

* `OK`: el segmento entregó su resultado completo.
* `ERROR`: el fragmento falló, ya sea porque el segmento devolvió una excepción, porque el initiator no pudo leer los datos o porque no se pudo cancelar el segmento.
* `UNSET`: ni éxito ni fallo. Estos spans incluyen un atributo que aporta más contexto.

Las consultas `INSERT` sobre una tabla `Distributed` generan spans análogos en `DistributedSink`, con las mismas claves de atributo `clickhouse.cluster` y `clickhouse.shard_num`.

<h2 id="tracing-clickhouse-keeper-requests">
  Trazado de solicitudes de ClickHouse Keeper
</h2>

ClickHouse admite trazado de OpenTelemetry para las solicitudes de [ClickHouse Keeper](/es/guides/oss/deployment-and-scaling/keeper/index) (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.

<h3 id="enabling-keeper-tracing">
  Habilitar el trazado de Keeper
</h3>

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

```xml theme={null}
<clickhouse>
    <zookeeper>
        <node>
            <host>keeper1</host>
            <port>9181</port>
        </node>
        <!-- Habilitar la propagación del contexto de trazado de OpenTelemetry -->
        <pass_opentelemetry_tracing_context>true</pass_opentelemetry_tracing_context>
    </zookeeper>
</clickhouse>
```

<h3 id="keeper-span-types">
  Tipos de spans de Keeper
</h3>

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 cola a la espera de que se complete un lote de solicitudes en curso
* `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

<h3 id="sampling-and-performance">
  Muestreo y rendimiento
</h3>

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.

<h2 id="tracing-the-clickhouse-itself">
  Trazado del propio ClickHouse
</h2>

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](https://jaegertracing.io/) o [Prometheus](https://prometheus.io/). 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](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#span) se almacena en la tabla [system.opentelemetry\_span\_log](/es/reference/system-tables/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](/es/reference/statements/select/array-join) para trabajar con ellos.

<h2 id="log-query-settings">
  Log-query-settings
</h2>

La configuración [log\_query\_settings](/es/reference/settings/session-settings/log-query#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.

<h2 id="integration-with-monitoring-systems">
  Integración con sistemas de monitoreo
</h2>

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](/es/reference/engines/table-engines/special/url) sobre la tabla [system.opentelemetry\_span\_log](/es/reference/system-tables/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:

```sql theme={null}
CREATE MATERIALIZED VIEW default.zipkin_spans
ENGINE = URL('http://127.0.0.1:9411/api/v2/spans', 'JSONEachRow')
SETTINGS output_format_json_named_tuples_as_objects = 1,
    output_format_json_array_of_rows = 1 AS
SELECT
    lower(hex(trace_id)) AS traceId,
    CASE WHEN parent_span_id = 0 THEN '' ELSE lower(hex(parent_span_id)) END AS parentId,
    lower(hex(span_id)) AS id,
    operation_name AS name,
    start_time_us AS timestamp,
    finish_time_us - start_time_us AS duration,
    cast(tuple('clickhouse'), 'Tuple(serviceName text)') AS localEndpoint,
    cast(tuple(
        attribute.values[indexOf(attribute.names, 'db.statement')]),
        'Tuple("db.statement" text)') AS tags
FROM system.opentelemetry_span_log
```

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.

<h2 id="related-content">
  Contenido relacionado
</h2>

* Blog: [Cómo crear una solución de observabilidad con ClickHouse - Parte 2 - Trazas](https://clickhouse.com/blog/storing-traces-and-spans-open-telemetry-in-clickhouse)