Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Cómo recopilar y visualizar una traza de consulta

View as MarkdownEdit this pageReport an issueSet up docs MCP

Requisitos previos:

[object Object]

Si no has realizado ninguna modificación en la sección opentelemetry_span_log de config.xml, puedes omitir este paso.

Abre el archivo config.xml predeterminado de ClickHouse y busca la siguiente sección:

<!--
    OpenTelemetry log contains OpenTelemetry trace spans.

    NOTE: this table does not use standard schema with event_date and event_time!
-->
<opentelemetry_span_log>
    <!--
        The default table creation code is insufficient, this <engine> spec
        is a workaround. There is no 'event_time' for this log, but two times,
        start and finish. It is sorted by finish time, to avoid inserting
        data too far away in the past (probably we can sometimes insert a span
        that is seconds earlier than the last span in the table, due to a race
        between several spans inserted in parallel). This gives the spans a
        global order that we can use to e.g. retry insertion into some external
        system.
    -->
    <engine>
        engine MergeTree
        partition by toYYYYMM(finish_date)
        order by (finish_date, finish_time_us, trace_id)
    </engine>
    <database>system</database>
    <table>opentelemetry_span_log</table>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</opentelemetry_span_log>

Asegúrate de que no esté comentado; de lo contrario, no podrás ver system.opentelemetry_span_log en los pasos siguientes. Esto también puede ocurrir si tu servidor de ClickHouse no está usando el archivo de configuración predeterminado.

Comprueba los logs del servidor para ver algo como esto:

Processing configuration file 'config.xml'.
There is no file 'config.xml', will use embedded config.

Habilitar el trazado de OpenTelemetry

Con su servidor de ClickHouse en ejecución, abra el cliente de ClickHouse y habilite la recopilación de trazas mediante la siguiente consulta:

SET opentelemetry_trace_processors=1;

Ahora deberías ver la tabla del sistema opentelemetry_span_log al ejecutar:

SHOW TABLES IN system

Próxima ejecución:

SET opentelemetry_start_trace_probability=1;

Esto establece la probabilidad de que ClickHouse inicie una traza para las consultas ejecutadas, donde 1 significa que la traza está habilitada para todas las consultas ejecutadas.

Obtener el ID de una consulta

Ejecute la siguiente consulta de prueba, o la consulta que le interese rastrear:

SELECT pow(number, 2) FROM numbers(10E4);

Copia el ID de la consulta:

:) SELECT pow(number, 2) FROM numbers(10E4);

SELECT pow(number, 2)
FROM numbers(100000.)

Query id: a9241258-a0c4-4776-a00b-e6a1d9bec4a1

Generar un archivo de traza

Ejecute la siguiente consulta, sustituyendo el ID de consulta por el que obtuvo en el paso anterior:

WITH 'a9241258-a0c4-4776-a00b-e6a1d9bec4a1' AS my_query_id
SELECT
    concat(substring(hostName(), length(hostName()), 1), leftPad(greatest(attribute['clickhouse.thread_id'], attribute['thread_number']), 5, '0')) AS group,
    operation_name,
    start_time_us,
    finish_time_us,
    sipHash64(operation_name) AS color,
    attribute
FROM system.opentelemetry_span_log
WHERE (trace_id IN (
    SELECT trace_id
    FROM system.opentelemetry_span_log
    WHERE (attribute['clickhouse.query_id']) = my_query_id
)) AND (operation_name != 'query') AND (operation_name NOT LIKE 'Query%')
ORDER BY
    hostName() ASC,
    group ASC,
    parent_span_id ASC,
    start_time_us ASC
INTO OUTFILE 'trace.json'
FORMAT JSON
SETTINGS output_format_json_named_tuples_as_objects = 1

Esto escribirá la traza en un archivo llamado trace.json. De forma predeterminada, este archivo se crea en el directorio de trabajo actual desde el que ejecuta la herramienta clickhouse-client o clickhouse-local.

Visualizar la traza con las herramientas integradas

Utiliza el visualizador de trazas alojado en https://trace-visualizer.clickhouse.com/. Carga el archivo trace.json del paso anterior para visualizar la traza.

Ejemplo del visualizador de trazas de ClickHouse

Usar Grafana para visualizar trazas

Recomendamos Grafana para visualizar y explorar datos de trazas con el plugin oficial de ClickHouse. El plugin se ha mejorado para permitir la visualización de trazas mediante el Trace Panel. Se admite tanto como visualización como componente en Explore.

Sigue los pasos descritos en "Uso de Grafana y ClickHouse para observabilidad" para configurar Grafana con el plugin de ClickHouse.

Desde la pestaña Explore, puedes ejecutar la siguiente consulta, sustituyendo trace_id por el tuyo:

SELECT
    toString(trace_id) AS traceID,
    toString(span_id) AS spanID,
    if(toString(parent_span_id)='0', '', toString(parent_span_id)) AS parentSpanID,
    'ClickHouse' AS serviceName,
    operation_name AS operationName,
    start_time_us/1000000 AS startTime,
    (finish_time_us - start_time_us)/1000 AS duration,
    arrayMap(key -> map('key', key, 'value', attribute[key]), mapKeys(attribute)) AS serviceTags
FROM system.opentelemetry_span_log
WHERE trace_id = '68a14b27-a61f-596d-3746-2b03d2530e42' ORDER BY startTime ASC

Asegúrate de configurar Query type como Traces:

Visualización de trazas de ClickHouse en Grafana

Haz clic en "Run Query" e inspecciona el diagrama de trazas:

Visualización de trazas de ClickHouse en Grafana
Navigation