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

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

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

Если родительский контекст трассировки не передан или переданный контекст трассировки не соответствует указанному выше стандарту W3C, ClickHouse может начать новую трассировку с вероятностью, задаваемой настройкой opentelemetry_start_trace_probability.

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

• Запросы к удалённым серверам ClickHouse, например при использовании движка таблицы Distributed.

• Табличная функция url. Информация о контексте трассировки отправляется в заголовках HTTP.

ClickHouse поддерживает трассировку OpenTelemetry для запросов ClickHouse Keeper (сервиса координации, совместимого с ZooKeeper). Эта возможность обеспечивает подробную видимость всего жизненного цикла операций 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>

Когда трассировка включена, 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 создает 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 — трейсы