> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/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.

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

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](/docs/es/reference/settings/session-settings#opentelemetry_start_trace_probability).

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

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

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

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

ClickHouse admite trazado de OpenTelemetry para las solicitudes de [ClickHouse Keeper](/docs/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.

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

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>
```

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

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

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

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.

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

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](/docs/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](/docs/es/reference/statements/select/array-join) para trabajar con ellos.

<div id="log-query-settings">
  ## Log-query-settings
</div>

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

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

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

<div id="related-content">
  ## Contenido relacionado
</div>

* 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)