Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Как собирать и визуализировать трассировку запроса

View as MarkdownEdit this pageReport an issueSet up docs MCP

Предварительные требования:

[object Object]

Если вы не вносили изменений в раздел opentelemetry_span_log файла config.xml, этот шаг можно пропустить.

Откройте стандартный файл config.xml ClickHouse и найдите следующий раздел:

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

Убедитесь, что эта строка не закомментирована, иначе на следующих шагах вы не увидите system.opentelemetry_span_log. Это также может произойти, если ваш сервер ClickHouse не использует файл конфигурации по умолчанию.

Проверьте серверный журнал на наличие примерно следующего:

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

Включить трассировку OpenTelemetry

Когда сервер ClickHouse запущен, откройте клиент ClickHouse и включите сбор трассировок с помощью следующего запроса:

SET opentelemetry_trace_processors=1;

Теперь, если выполнить:

SHOW TABLES IN system

Далее выполните:

SET opentelemetry_start_trace_probability=1;

Этот параметр задает вероятность того, что ClickHouse будет запускать трассировку для выполняемых запросов, где 1 означает, что трассировка включена для всех выполняемых запросов.

Получить идентификатор запроса

Выполните следующий тестовый запрос или запрос, трассировку которого вы хотите выполнить:

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

Скопируйте Query id:

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

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

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

Сгенерировать файл трассировки

Выполните следующий запрос, подставив идентификатор запроса, полученный на предыдущем шаге:

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

Это запишет трассировку в файл с именем trace.json. По умолчанию этот файл создаётся в текущем рабочем каталоге, из которого запускается инструмент clickhouse-client или clickhouse-local.

Визуализируйте трассировку с помощью встроенных инструментов

Используйте размещённый сервис визуализации трейсов по адресу https://trace-visualizer.clickhouse.com/. Загрузите файл trace.json из предыдущего шага, чтобы визуализировать трейс.

Пример визуализатора трейсов ClickHouse

Визуализация трассировок в Grafana

Мы рекомендуем Grafana для визуализации и анализа данных трассировки с помощью официального плагина ClickHouse. Плагин был доработан, чтобы поддерживать визуализацию трассировок с помощью панели Trace Panel. Это поддерживается как в виде визуализации, так и в виде компонента в Explore.

Следуйте шагам, описанным в "Использование Grafana и ClickHouse для обсервабилити", чтобы настроить Grafana с плагином ClickHouse.

На вкладке Explore вы можете выполнить следующий запрос, заменив trace_id на свой:

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

Убедитесь, что для Query type выбрано значение Traces:

Визуализация трейсов ClickHouse в Grafana

Нажмите "Run Query" и просмотрите диаграмму трассировки:

Визуализация трейсов ClickHouse в Grafana
Navigation