Rastreando o ClickHouse com OpenTelemetry

OpenTelemetry é um padrão aberto para coletar traces e métricas de aplicações distribuídas. O ClickHouse oferece algum suporte a OpenTelemetry.

Fornecendo contexto de rastreamento ao ClickHouse

O ClickHouse aceita cabeçalhos HTTP de contexto de rastreamento, conforme descrito na recomendação do W3C. Ele também aceita contexto de rastreamento por um protocolo nativo usado na comunicação entre servidores do ClickHouse ou entre o cliente e o servidor. Para testes manuais, cabeçalhos de contexto de rastreamento em conformidade com a recomendação Trace Context podem ser fornecidos ao clickhouse-client usando as flags --opentelemetry-traceparent e --opentelemetry-tracestate. Se nenhum contexto de rastreamento pai for fornecido, ou se o contexto de rastreamento informado não estiver em conformidade com o padrão W3C mencionado acima, o ClickHouse poderá iniciar um novo rastreamento, com probabilidade controlada pela configuração opentelemetry_start_trace_probability.

Propagação do contexto de rastreamento

O contexto de rastreamento é propagado para serviços downstream nos seguintes casos:

Consultas para servidores ClickHouse remotos, como ao usar o motor de tabela Distributed.
Função de tabela url. As informações do contexto de rastreamento são enviadas nos cabeçalhos HTTP.

Rastreamento de solicitações do ClickHouse Keeper

O ClickHouse oferece rastreamento com OpenTelemetry para solicitações do ClickHouse Keeper (serviço de coordenação compatível com ZooKeeper). Esse recurso oferece visibilidade detalhada do ciclo de vida das operações do Keeper, desde o envio da solicitação pelo cliente até o processamento no servidor.

Habilitando o rastreamento do Keeper

Para habilitar o rastreamento das requisições do Keeper, configure as seguintes definições na configuração do cliente ZooKeeper/Keeper:

<clickhouse>
    <zookeeper>
        <node>
            <host>keeper1</host>
            <port>9181</port>
        </node>
        <!-- Habilitar a propagação de contexto de rastreamento do OpenTelemetry -->
        <pass_opentelemetry_tracing_context>true</pass_opentelemetry_tracing_context>
    </zookeeper>
</clickhouse>

Tipos de spans do Keeper

Quando o rastreamento está habilitado, o ClickHouse cria spans para operações do Keeper tanto no lado do cliente quanto no lado do servidor: Spans do lado do cliente:

zookeeper.create — Criar um novo nó
zookeeper.get — Obter os dados do nó
zookeeper.set — Definir os dados do nó
zookeeper.remove — Remover um nó
zookeeper.list — Listar nós filhos
zookeeper.exists — Verificar se um nó existe
zookeeper.multi — Executar várias operações de forma atômica
zookeeper.client.requests_queue — Tempo gasto na fila de solicitações antes do envio

Spans do lado do servidor (Keeper):

keeper.receive_request — Recebimento e análise da solicitação do cliente
keeper.dispatcher.requests_queue — Solicitações na fila do dispatcher
keeper.write.pre_commit — Pré-processamento de solicitações de escrita antes do commit do Raft
keeper.write.commit — Processamento de solicitações de escrita após o commit do Raft
keeper.read.wait_for_write — Solicitações de leitura aguardando escritas das quais dependem
keeper.read.process — Processamento de solicitações de leitura
keeper.dispatcher.responses_queue — Respostas na fila do dispatcher
keeper.send_response — Envio da resposta ao cliente

Amostragem e desempenho

Para gerenciar a sobrecarga do rastreamento, o Keeper implementa amostragem dinâmica. A taxa de amostragem é ajustada automaticamente entre 1/10.000 e 1/10 com base no tamanho da solicitação. As durações de todas as solicitações (amostradas e não amostradas) são registradas em métricas de histograma para monitoramento de desempenho.

Rastreando o próprio ClickHouse

O ClickHouse cria trace spans para cada consulta e para alguns estágios da execução da consulta, como o planejamento da consulta ou consultas distribuídas. Para serem úteis, as informações de rastreamento precisam ser exportadas para um sistema de monitoramento compatível com OpenTelemetry, como Jaeger ou Prometheus. O ClickHouse evita depender de um sistema de monitoramento específico e, em vez disso, fornece os dados de rastreamento apenas por meio de uma tabela de sistema. As informações de trace span do OpenTelemetry exigidas pelo padrão são armazenadas na tabela system.opentelemetry_span_log. A tabela deve estar habilitada na configuração do servidor; consulte o elemento opentelemetry_span_log no arquivo de configuração padrão config.xml. Ela é habilitada por padrão. As tags ou atributos são salvos como dois arrays paralelos, contendo as chaves e os valores. Use ARRAY JOIN para trabalhar com eles.

Registro das configurações da consulta

A configuração log_query_settings permite registrar alterações nas configurações da consulta durante sua execução. Quando habilitada, qualquer modificação feita nas configurações da consulta será registrada no log do span do OpenTelemetry. Esse recurso é especialmente útil em ambientes de produção para rastrear alterações de configuração que possam afetar o desempenho da consulta.

Integração com sistemas de monitoramento

No momento, não existe uma ferramenta pronta para exportar os dados de rastreamento do ClickHouse para um sistema de monitoramento. Para testes, é possível configurar a exportação usando uma visão materializada com o motor URL sobre a tabela system.opentelemetry_span_log, para enviar os dados de log recebidos a um endpoint HTTP de um coletor de traces. Por exemplo, para enviar os dados mínimos de span para uma instância do Zipkin em execução em http://localhost:9411, no formato JSON v2 do Zipkin:

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

Em caso de erro, a parte dos dados de log em que o erro ocorreu será perdida silenciosamente. Verifique o log do servidor em busca de mensagens de erro se os dados não chegarem.

Blog: Criando uma solução de observabilidade com ClickHouse - Parte 2 - traces

​Fornecendo contexto de rastreamento ao ClickHouse

​Propagação do contexto de rastreamento

​Rastreamento de solicitações do ClickHouse Keeper

​Habilitando o rastreamento do Keeper

​Tipos de spans do Keeper

​Amostragem e desempenho

​Rastreando o próprio ClickHouse

​Registro das configurações da consulta

​Integração com sistemas de monitoramento

​Conteúdo relacionado