Трассировка ClickHouse с OpenTelemetry

OpenTelemetry — это открытый стандарт для сбора трейсов и метрик в распределённых приложениях. ClickHouse в некоторой степени поддерживает OpenTelemetry.

Передача контекста трассировки в ClickHouse

ClickHouse принимает HTTP-заголовки контекста трассировки, как описано в рекомендации W3C. Он также принимает контекст трассировки через собственный протокол, который используется для обмена данными между серверами ClickHouse или между клиентом и сервером. Для ручного тестирования заголовки контекста трассировки, соответствующие рекомендации Trace Context, можно передать в clickhouse-client с помощью флагов --opentelemetry-traceparent и --opentelemetry-tracestate. Если родительский контекст трассировки не передан или переданный контекст трассировки не соответствует указанному выше стандарту W3C, ClickHouse может начать новую трассировку с вероятностью, задаваемой настройкой opentelemetry_start_trace_probability.

Передача контекста трассировки

Контекст трассировки передаётся в сервисы ниже по цепочке в следующих случаях:

Запросы к удалённым серверам ClickHouse, например при использовании движка таблицы Distributed.
Табличная функция url. Информация о контексте трассировки отправляется в заголовках HTTP.

Спаны распределённых запросов

Для распределённого SELECT каждое чтение с удалённого сегмента покрывается спаном RemoteQueryExecutor::execute. Такие спаны содержат атрибуты, идентифицирующие query fragment:

clickhouse.cluster и clickhouse.shard_num — cluster и сегмент, с которого читает исполнитель;
clickhouse.query_id и clickhouse.initial_query_id — query ids с точки зрения initiator;
clickhouse.target_host — адреса установленных соединений.

status_code такого спана показывает, чем завершился fragment:

OK — сегмент вернул полный результат.
ERROR — fragment завершился с ошибкой: сегмент вернул exception, initiator не смог прочитать данные либо не удалось отменить работу сегмента.
UNSET — ни успех, ни ошибка. Такие спаны содержат атрибут, дающий дополнительный контекст.

Запросы INSERT в Distributed table порождают аналогичные спаны в DistributedSink с теми же ключами атрибутов clickhouse.cluster и clickhouse.shard_num.

Трассировка запросов ClickHouse Keeper

ClickHouse поддерживает трассировку OpenTelemetry для запросов ClickHouse Keeper (сервиса координации, совместимого с ZooKeeper). Эта возможность обеспечивает подробную видимость всего жизненного цикла операций Keeper — от отправки клиентского запроса до его обработки на стороне сервера.

Включение трассировки запросов Keeper

Чтобы включить трассировку запросов Keeper, настройте следующие параметры в конфигурации клиента ZooKeeper/Keeper:

<clickhouse>
    <zookeeper>
        <node>
            <host>keeper1</host>
            <port>9181</port>
        </node>
        <!-- Включить передачу контекста трассировки OpenTelemetry -->
        <pass_opentelemetry_tracing_context>true</pass_opentelemetry_tracing_context>
    </zookeeper>
</clickhouse>

Типы спанов Keeper

Когда трассировка включена, ClickHouse создает спаны как для клиентских, так и для серверных операций Keeper: Клиентские спаны:

zookeeper.create — Создание нового узла
zookeeper.get — Получение данных узла
zookeeper.set — Запись данных узла
zookeeper.remove — Удаление узла
zookeeper.list — Получение списка дочерних узлов
zookeeper.exists — Проверка существования узла
zookeeper.multi — Атомарное выполнение нескольких операций
zookeeper.client.requests_queue — Время ожидания запросов в очереди перед отправкой

Серверные спаны (Keeper):

keeper.receive_request — Получение и разбор запроса от клиента
keeper.dispatcher.requests_queue — Ожидание запроса в очереди диспетчера
keeper.write.pre_commit — Предварительная обработка запросов на запись перед фиксацией в Raft
keeper.write.commit — Обработка запросов на запись после фиксации в Raft
keeper.read.wait_for_write — Ожидание запросов на чтение в очереди до завершения обработки текущего батча запросов
keeper.read.process — Обработка запросов на чтение
keeper.dispatcher.responses_queue — Ожидание ответа в очереди диспетчера
keeper.send_response — Отправка ответа клиенту

Сэмплирование и производительность

Чтобы снизить накладные расходы на трассировку, Keeper использует динамическое сэмплирование. Частота сэмплирования автоматически регулируется в диапазоне от 1/10,000 до 1/10 в зависимости от размера запроса. Для мониторинга производительности значения длительности всех запросов (как сэмплированных, так и несэмплированных) записываются в метрики-гистограммы.

Трассировка самого ClickHouse

ClickHouse создает trace spans для каждого запроса и некоторых этапов его выполнения, таких как планирование запроса или распределенные запросы. Чтобы эта информация была полезной, ее нужно экспортировать в систему мониторинга с поддержкой OpenTelemetry, например Jaeger или Prometheus. ClickHouse не зависит от какой-либо конкретной системы мониторинга и предоставляет данные трассировки только через системную таблицу. Информация о спанах трассировки OpenTelemetry, требуемая стандартом, хранится в таблице system.opentelemetry_span_log. Эта таблица должна быть включена в конфигурации сервера, см. элемент opentelemetry_span_log в файле конфигурации по умолчанию config.xml. По умолчанию она включена. Теги или атрибуты сохраняются в виде двух параллельных массивов, содержащих ключи и значения. Используйте ARRAY JOIN, чтобы работать с ними.

Журналирование настроек запроса

Настройка log_query_settings позволяет журналировать изменения настроек запроса во время выполнения запроса. Когда она включена, любые изменения, внесенные в настройки запроса, будут записаны в журнал спана OpenTelemetry. Эта возможность особенно полезна в продакшн-средах для отслеживания изменений конфигурации, которые могут повлиять на производительность запросов.

Интеграция с системами мониторинга

На данный момент не существует готового инструмента, который мог бы экспортировать данные трассировки из ClickHouse в систему мониторинга. Для тестирования можно настроить экспорт с помощью materialized view с движком URL поверх таблицы system.opentelemetry_span_log, которая будет отправлять поступающие записи журнала на HTTP-конечную точку коллектора трассировки. Например, чтобы отправлять минимальный набор данных спана в экземпляр Zipkin, работающий по адресу http://localhost:9411, в формате Zipkin v2 JSON:

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

В случае ошибок соответствующая часть данных журнала будет незаметно потеряна. Если данные не поступают, проверьте журнал сервера на наличие сообщений об ошибках.

Блог: Создание решения для обсервабилити на базе ClickHouse — часть 2 — трейсы

Руководства по ClickHouse

Руководства по сценариям использования

Трассировка ClickHouse с OpenTelemetry

Передача контекста трассировки в ClickHouse

Передача контекста трассировки

Спаны распределённых запросов

Трассировка запросов ClickHouse Keeper

Включение трассировки запросов Keeper

Типы спанов Keeper

Сэмплирование и производительность

Трассировка самого ClickHouse

Журналирование настроек запроса

Интеграция с системами мониторинга

​Передача контекста трассировки в ClickHouse

​Передача контекста трассировки

​Спаны распределённых запросов

​Трассировка запросов ClickHouse Keeper

​Включение трассировки запросов Keeper

​Типы спанов Keeper

​Сэмплирование и производительность

​Трассировка самого ClickHouse

​Журналирование настроек запроса

​Интеграция с системами мониторинга

​Материалы по теме

Передача контекста трассировки в ClickHouse

Передача контекста трассировки

Спаны распределённых запросов

Трассировка запросов ClickHouse Keeper

Включение трассировки запросов Keeper

Типы спанов Keeper

Сэмплирование и производительность

Трассировка самого ClickHouse

Журналирование настроек запроса

Интеграция с системами мониторинга

Материалы по теме