向 ClickHouse 传递 trace 上下文
ClickHouse 接受 W3C Trace Context 建议中定义的 trace 上下文 HTTP 请求头。它也接受通过原生协议传递的 trace 上下文,该协议用于 ClickHouse 服务器之间或客户端与服务器之间的通信。进行手动测试时,可以使用--opentelemetry-traceparent 和 --opentelemetry-tracestate 标志,向 clickhouse-client 传入符合 Trace Context 建议的 trace 上下文请求头。
如果未提供父 trace 上下文,或者提供的 trace 上下文不符合上述 W3C 标准,ClickHouse 可以启动一个新的 trace,其概率由 opentelemetry_start_trace_probability 设置控制。
传播 trace 上下文
在以下情况下,trace 上下文 会传递到下游服务:- 向远程 ClickHouse 服务器发起查询时,例如使用 Distributed 表引擎时。
- url 表函数。trace 上下文 信息会通过 HTTP 请求头 发送。
分布式查询的 span
对于分布式SELECT,从每个远程 shard 的读取都由一个 RemoteQueryExecutor::execute span 覆盖。这些 span 带有用于标识该 query fragment 的属性:
clickhouse.cluster和clickhouse.shard_num— executor 所读取的 cluster 和 shard;clickhouse.query_id和clickhouse.initial_query_id— 从发起服务器视角看到的 query id;clickhouse.target_host— 已建立的 connection 的地址。
status_code 表明该 fragment 的结束方式:
OK— 该 shard 返回了完整结果。ERROR— 该 fragment 失败:shard 返回了 exception、发起服务器读取数据失败,或取消 shard 失败。UNSET— 既非成功也非失败。此类 span 会带有一个属性以提供更多 context。
Distributed 表执行的 INSERT 查询会在 DistributedSink 中产生类似的 span,并使用相同的 clickhouse.cluster 和 clickhouse.shard_num 属性键。
分布式执行计划任务的 span
启用实验性的make_distributed_plan 设置后,查询会被拆分为由多个阶段组成的执行计划,每个阶段再拆分为若干任务,并通过 HTTP 分派给无状态工作节点。分派请求通过 traceparent 和 tracestate 请求头携带追踪上下文,因此工作节点上的 span 会并入发起服务器的 trace:
StatelessWorkerClient::sendTask(类型CLIENT) —— 发起服务器上每个已分派的任务各对应一个 span,仅涵盖启动请求;任务本身在工作节点上异步运行,并通过轮询确认是否完成。属性:clickhouse.distributed.task_id、clickhouse.initial_query_id和clickhouse.target_host,分派失败时另含clickhouse.exception;InterserverIOHTTPHandler(类型SERVER) —— 携带追踪上下文的请求在工作节点侧的 span,包含clickhouse.uri、http.method和clickhouse.http_status。如果请求在任务启动前就已失败 (身份验证失败,或端点抛出异常) ,则会在此 span 上记录clickhouse.exception和clickhouse.exception_code,此时它就是该次分派在工作节点侧留下的唯一追踪记录。不带traceparent请求头的请求 (例如副本之间的数据分片拉取操作) 不会被追踪;DistributedPlanTask::execute(类型SERVER) —— 表示工作节点上单个任务的执行,相当于常规查询中的queryspan:它以相同方式携带db.statement、clickhouse.query_id,以及clickhouse.query_status或异常信息;此外还包含标识任务身份的属性:clickhouse.distributed.task_id、clickhouse.initial_query_id、clickhouse.distributed.plan_hash(已序列化执行计划片段的哈希) 、clickhouse.distributed.serialization_version、clickhouse.distributed.execute_locally,以及该任务所读写的clickhouse.exchange.inputs/clickhouse.exchange.outputs流。
distributed_plan_execute_locally = 1 时,不会发送任何请求:任务直接在发起服务器的线程上运行,其 DistributedPlanTask::execute span 也会直接附加到发起服务器的 trace 上。
追踪 ClickHouse Keeper 请求
ClickHouse 支持对 ClickHouse Keeper 请求进行 OpenTelemetry 追踪 (ClickHouse 的兼容 ZooKeeper 语义的协调服务) 。该功能可让你详细了解 Keeper 操作的整个生命周期,从客户端提交请求到服务端处理。启用 Keeper 追踪
要为 Keeper 请求启用追踪,请在 ZooKeeper/Keeper 客户端配置中设置以下参数:Keeper Span 类型
启用追踪后,ClickHouse 会为客户端和服务端的 Keeper 操作创建 spans: 客户端 spans:zookeeper.create— 创建新节点zookeeper.get— 获取节点数据zookeeper.set— 设置节点数据zookeeper.remove— 删除节点zookeeper.list— 列出子节点zookeeper.exists— 检查节点是否存在zookeeper.multi— 以原子方式执行多个操作zookeeper.client.requests_queue— 请求发送前在队列中等待的时间
keeper.receive_request— 接收并解析来自客户端的请求keeper.dispatcher.requests_queue— dispatcher 中的请求排队keeper.write.pre_commit— 在 Raft commit 之前预处理写入请求keeper.write.commit— 在 Raft commit 之后处理写入请求keeper.read.wait_for_write— 读取请求排在尚在传输中的请求批次之后等待keeper.read.process— 处理读取请求keeper.dispatcher.responses_queue— dispatcher 中的响应排队keeper.send_response— 向客户端发送响应
采样与性能
为控制追踪开销,Keeper 实现了动态采样。采样率会根据请求大小在 1/10,000 到 1/10 之间自动调整。所有请求 (无论是否被采样) 都会将其耗时记录到直方图指标中,以便进行性能监控。追踪 ClickHouse 自身
ClickHouse 会为每个查询以及查询执行的某些阶段 (例如查询计划或分布式查询) 创建trace spans。
为了让这些追踪信息发挥作用,必须将其导出到支持 OpenTelemetry 的监控系统,例如 Jaeger 或 Prometheus。ClickHouse 不依赖任何特定的监控系统,而是仅通过系统表提供追踪数据。标准要求的 OpenTelemetry trace span 信息存储在 system.opentelemetry_span_log 表中。
必须在服务器配置中启用该表,参见默认配置文件 config.xml 中的 opentelemetry_span_log 元素。该表默认已启用。
标签或属性以两个并行数组的形式保存,分别包含键和值。使用 ARRAY JOIN 来处理它们。
日志查询设置
设置 log_query_settings 允许记录查询执行期间对查询设置所做的更改。启用后,对查询设置进行的任何修改都会记录到 OpenTelemetry span 日志中。此功能在生产环境中尤其有用,可用于跟踪可能影响查询性能的配置变更。与监控系统集成
目前,还没有现成的工具可将 ClickHouse 中的 tracing 数据导出到监控系统。 在测试场景下,可以通过在 system.opentelemetry_span_log 表上创建使用 URL 引擎的 materialized view 来配置导出,这样可将收到的日志数据推送到 trace collector 的 HTTP 端点。例如,要将最基本的 span 数据以 Zipkin v2 JSON 格式推送到运行在http://localhost:9411 的 Zipkin 实例: