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

使用 OpenTelemetry 追踪 ClickHouse

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

向 ClickHouse 提供追踪上下文​

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

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

传播追踪上下文​

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

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

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

追踪 ClickHouse 自身​

ClickHouse 为每个查询和一些查询执行阶段创建 trace spans，例如查询计划或分布式查询。

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

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

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

日志查询设置​

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

与监控系统集成​

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

对于测试，可以使用物化视图和 URL 引擎通过 system.opentelemetry_span_log 表来设置导出，这将把到达的日志数据推送到追踪收集器的 HTTP 端点。例如，要将最小的 span 数据推送到运行在 https://127.0.0.1:9411 的 Zipkin 实例，使用 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

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

相关内容​