跳至主要内容
跳至主要内容
编辑此页

使用 OpenTelemetry 追踪 ClickHouse

OpenTelemetry 是一种用于从分布式应用程序收集追踪和指标的开放标准。ClickHouse 对 OpenTelemetry 有一定支持。

向 ClickHouse 提供追踪上下文​

ClickHouse 接受 W3C 推荐描述的追踪上下文 HTTP 标头，W3C 推荐。它还接受通过 ClickHouse 服务器之间或客户端和服务器之间通信使用的本机协议的追踪上下文。为了手动测试，可以使用 --opentelemetry-traceparent 和 --opentelemetry-tracestate 标志向 clickhouse-client 提供符合追踪上下文推荐标准的追踪上下文标头。

如果未提供父追踪上下文，或者提供的追踪上下文不符合上述 W3C 标准，ClickHouse 可以启动一个新的追踪，其概率由 opentelemetry_start_trace_probability 设置控制。

传播追踪上下文​

在以下情况下，追踪上下文将传播到下游服务

  • 对远程 ClickHouse 服务器的查询，例如在使用 Distributed 表引擎时。

  • url 表函数。追踪上下文信息通过 HTTP 标头发送。

追踪 ClickHouse Keeper 请求​

ClickHouse 支持 ClickHouse Keeper 请求（ZooKeeper 兼容的协调服务）的 OpenTelemetry 追踪。此功能提供了对 Keeper 操作生命周期的详细可见性，从客户端请求提交到服务器端处理。

启用 Keeper 追踪​

要启用 Keeper 请求的追踪，请在 ZooKeeper/Keeper 客户端配置中配置以下设置

<clickhouse>
    <zookeeper>
        <node>
            <host>keeper1</host>
            <port>9181</port>
        </node>
        <!-- Enable OpenTelemetry tracing context propagation -->
        <pass_opentelemetry_tracing_context>true</pass_opentelemetry_tracing_context>
    </zookeeper>
</clickhouse>

Keeper Span 类型​

启用追踪后，ClickHouse 会为客户端和服务器端的 Keeper 操作创建 span

客户端 span

  • zookeeper.create — 创建新节点
  • zookeeper.get — 获取节点数据
  • zookeeper.set — 设置节点数据
  • zookeeper.remove — 删除节点
  • zookeeper.list — 列出子节点
  • zookeeper.exists — 检查节点是否存在
  • zookeeper.multi — 原子执行多个操作
  • zookeeper.client.requests_queue — 请求在发送前排队的时间

服务器端 span (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 span。

为了有用，追踪信息必须导出到支持 OpenTelemetry 的监控系统，例如 Jaeger 或 Prometheus。ClickHouse 避免对特定监控系统产生依赖，而是仅通过系统表提供追踪数据。OpenTelemetry trace span 信息 根据标准要求 存储在 system.opentelemetry_span_log 表中。

该表必须在服务器配置中启用，请参阅默认配置文件 config.xml 中的 opentelemetry_span_log 元素。默认情况下已启用。

标签或属性保存为两个并行数组，包含键和值。使用 ARRAY JOIN 来处理它们。

Log-query-settings​

设置 log_query_settings 允许记录查询执行期间查询设置的更改。启用后，对查询设置所做的任何修改都将记录在 OpenTelemetry span 日志中。此功能在生产环境中特别有用，用于跟踪可能影响查询性能的配置更改。

与监控系统的集成​

目前，没有现成的工具可以将 ClickHouse 的追踪数据导出到监控系统。

为了测试，可以使用通过 URL 引擎通过 system.opentelemetry_span_log 表将传入的日志数据推送到 Zipkin 实例的 HTTP 端点（运行在 https://: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

如果出现任何错误，发生错误的部分日志数据将被静默丢弃。如果数据未到达，请检查服务器日志中的错误消息。

相关内容​

    © . This site is unofficial and not affiliated with ClickHouse, Inc.