跳至主要内容

使用 OpenTelemetry 追踪 ClickHouse

OpenTelemetry 是一种用于从分布式应用程序收集跟踪和指标的开放标准。ClickHouse 对 OpenTelemetry 提供了一些支持。

向 ClickHouse 提供跟踪上下文​

ClickHouse 接受跟踪上下文 HTTP 标头，如 W3C 建议 中所述。它还接受通过用于 ClickHouse 服务器之间或客户端和服务器之间通信的原生协议传输的跟踪上下文。对于手动测试，可以使用 --opentelemetry-traceparent 和 --opentelemetry-tracestate 标志向 clickhouse-client 提供符合跟踪上下文建议的跟踪上下文标头。

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

传播跟踪上下文​

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

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

  • url 表函数。跟踪上下文信息以 HTTP 标头发送。

追踪 ClickHouse 本身​

ClickHouse 为每个查询和一些查询执行阶段（例如查询计划或分布式查询）创建 跟踪跨度。

为了发挥作用，跟踪信息必须导出到支持 OpenTelemetry 的监控系统，例如 Jaeger 或 Prometheus。ClickHouse 避免依赖于特定的监控系统，而是仅通过系统表提供跟踪数据。标准 所需 的 OpenTelemetry 跟踪跨度信息存储在 system.opentelemetry_span_log 表中。

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

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

日志查询设置​

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

与监控系统的集成​

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

为了进行测试，可以使用带有 URL 引擎的物化视图在 system.opentelemetry_span_log 表上设置导出，这将把到达的日志数据推送到跟踪收集器的 HTTP 端点。例如，要以 Zipkin v2 JSON 格式将最小的跨度数据推送到在 https://127.0.0.1:9411 上运行的 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

如果发生任何错误，则发生错误的日志数据部分将被静默丢失。如果数据未到达，请检查服务器日志以获取错误消息。

相关内容​