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 aoclickhouse-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.
Spans de consultas distribuídas
Em umSELECT distribuído, cada leitura de um shard remoto é coberta por um span RemoteQueryExecutor::execute. Esses spans carregam atributos que identificam o fragmento da consulta:
clickhouse.clustereclickhouse.shard_num— o cluster e o shard do qual o executor lê;clickhouse.query_ideclickhouse.initial_query_id— os IDs da consulta sob a perspectiva do initiator;clickhouse.target_host— os endereços das conexões estabelecidas.
status_code desse tipo de span indica como o fragmento terminou:
OK— o shard entregou seu resultado completo.ERROR— o fragmento falhou: o shard retornou uma exceção, o initiator não conseguiu ler os dados ou o cancelamento do shard falhou.UNSET— nem sucesso, nem falha. Esses spans carregam um atributo que fornece mais contexto.
INSERT em uma tabela Distributed produzem spans análogos em DistributedSink, com as mesmas chaves de atributo clickhouse.cluster e clickhouse.shard_num.
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: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 filhoszookeeper.exists— Verificar se um nó existezookeeper.multi— Executar várias operações de forma atômicazookeeper.client.requests_queue— Tempo gasto na fila de requisições antes do envio
keeper.receive_request— Recebimento e análise da solicitação do clientekeeper.dispatcher.requests_queue— Requisições na fila do dispatcherkeeper.write.pre_commit— Pré-processamento de requisições de escrita antes do commit do Raftkeeper.write.commit— Processamento de requisições de escrita após o commit do Raftkeeper.read.wait_for_write— Requisições de leitura enfileiradas aguardando um lote de solicitações em andamentokeeper.read.process— Processamento de requisições de leiturakeeper.dispatcher.responses_queue— Respostas na fila do dispatcherkeeper.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 criatrace 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 emhttp://localhost:9411, no formato JSON v2 do Zipkin: