ClickHouse 官方文档：如何使用 Grafana 分析数据【5/5】

在 Grafana 中配置 ClickHouse 数据源时，插件允许用户指定日志和跟踪的默认数据库和表，并指定这些表是否遵循 OTel 模式。这可以帮助插件返回正确的日志和跟踪所需的列。如果您修改了 OTel 的默认模式并希望使用自定义列名，插件允许这样配置。如果使用了像时间戳（Timestamp）、日志级别（SeverityText）或消息内容（Body）这样的默认列名，那么无需进行任何更改。

HTTP 或原生协议

用户可以通过 HTTP 协议或原生协议将 Grafana 连接到 ClickHouse。尽管原生协议在性能上有微弱优势，但对于大多数由 Grafana 发出的聚合查询而言，这种提升可能并不明显。相比之下，HTTP 协议在代理和调试方面通常更为简便。

日志配置要求至少包含时间、日志级别和消息内容列，以确保日志正确渲染。

跟踪配置稍显复杂（完整列表见此处【https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-data-storage】），要求提供的列有助于构建完整的跟踪数据。此功能假设数据结构遵循 OTel 模式，因此若用户有较大偏离，需通过视图来适配和使用该功能。

完成配置后，用户可以在 Grafana Explore 中开始搜索日志和跟踪数据。

当用户遵循 Grafana 对日志的要求时，可以在查询构建器中选择查询类型：日志，并点击运行查询。查询构建器将自动生成查询来列出日志并确保它们正确渲染，例如：

SELECT Timestamp as timestamp, Body as body, SeverityText as level, TraceId as traceID FROM "default"."otel_logs" WHERE ( timestamp >= $__fromTime AND timestamp <= $__toTime ) ORDER BY timestamp DESC LIMIT 1000

查询构建器提供了一个简单的方式来修改查询，避免用户编写 SQL。如果需要，用户可以通过查询构建器进行日志过滤，甚至查找包含特定关键词的日志。对于需要编写更复杂查询的用户，可以切换到 SQL 编辑器。只要返回了正确的列，并且选择了日志作为查询类型，结果将自动显示为日志。有关日志渲染所需的列，请参阅这里。【https://grafana.com/developers/plugin-tools/tutorials/build-a-logs-data-source-plugin#logs-data-frame-format】

如果日志中包含跟踪 ID，用户可以轻松地导航到特定日志行对应的完整跟踪记录。

与日志的配置类似，如果满足 Grafana 渲染跟踪所需的列（例如，使用 OTel 模式），查询构建器可以自动生成必要的查询。选择查询类型：跟踪并点击运行查询，系统将生成并执行一个类似下面的查询（具体取决于您配置的列 - 假设使用 OTel）：

SELECT "TraceId" as traceID,  "ServiceName" as serviceName,  "SpanName" as operationName,  "Timestamp" as startTime,  multiply("Duration", 0.000001) as durationFROM "default"."otel_traces"WHERE ( Timestamp >= $__fromTime AND Timestamp <= $__toTime )  AND ( ParentSpanId = '' )  AND ( Duration > 0 )  ORDER BY Timestamp DESC, Duration DESC LIMIT 1000

该查询会返回 Grafana 所需的列，并渲染出一个跟踪表格，用户可以在不编写 SQL 的情况下进行过滤，比如按持续时间或其他列筛选。

如果用户希望编写更复杂的查询，也可以切换到 SQL 编辑器。

在 Grafana 中，跟踪 ID 会作为可点击的链接显示。点击某个跟踪 ID 后，用户可以选择通过查看跟踪链接查看该跟踪关联的 spans。系统将会发出查询（假设使用 OTel 模式）来检索相关的 spans，并将结果以瀑布图形式呈现。

WITH '<trace_id>' as trace_id,  (SELECT min(Start) FROM "default"."otel_traces_trace_id_ts"    WHERE TraceId = trace_id) as trace_start,  (SELECT max(End) + 1 FROM "default"."otel_traces_trace_id_ts"    WHERE TraceId = trace_id) as trace_endSELECT "TraceId" as traceID,  "SpanId" as spanID,  "ParentSpanId" as parentSpanID,  "ServiceName" as serviceName,  "SpanName" as operationName,  "Timestamp" as startTime,  multiply("Duration", 0.000001) as duration,  arrayMap(key -> map('key', key, 'value',"SpanAttributes"[key]),  mapKeys("SpanAttributes")) as tags,  arrayMap(key -> map('key', key, 'value',"ResourceAttributes"[key]),  mapKeys("ResourceAttributes")) as serviceTagsFROM "default"."otel_traces"WHERE traceID = trace_id  AND startTime >= trace_start  AND startTime <= trace_endLIMIT 1000

注意

上述查询利用了物化视图 otel_traces_trace_id_ts 来执行跟踪 ID 查找。有关加速查询和使用物化视图进行查找的详细信息，请参阅《加速查询 - 使用物化视图进行查找》。

如果日志中包含跟踪 ID，用户可以从跟踪页面跳转到对应的日志。只需点击某个跟踪 ID，然后选择查看日志选项，系统会发出查询（假设使用默认的 OTel 列）来显示关联的日志。

SELECT Timestamp as "timestamp",  Body as "body", SeverityText as "level",  TraceId as "traceID" FROM "default"."otel_logs"WHERE ( traceID = '<trace_id>' )ORDER BY timestamp ASC LIMIT 1000

用户可以使用 Grafana 和 ClickHouse 数据源来构建个性化的仪表板。我们推荐查阅 Grafana 和 ClickHouse 数据源的文档【https://github.com/grafana/clickhouse-datasource】，特别是其中关于宏和变量的部分，这些内容能帮助用户更好地创建动态的仪表板。

Grafana 插件还提供了多个开箱即用的仪表板，包括一个示例仪表板“简单的 ClickHouse OTel 仪表板”，用于显示符合 OTel 规范的日志和跟踪数据。此示例仪表板要求使用 OTel 默认的列名，并可以通过数据源配置进行安装。

可视化构建小贴士

在下面，我们提供了一些关于构建可视化图表的基本建议，帮助用户快速上手。

在可观测性应用场景中，折线图和统计图表是最常见的可视化方式之一。如果查询返回一个名为 time 的日期时间字段和一个数值类型的列，ClickHouse 插件会自动将结果渲染为折线图。示例如下：

SELECT $__timeInterval(Timestamp) as time, quantile(0.99)(Duration)/1000000 AS p99FROM otel_tracesWHERE $__timeFilter(Timestamp) AND ( Timestamp  >= $__fromTime AND Timestamp <= $__toTime )GROUP BY timeORDER BY time ASCLIMIT 100000

如果查询结果满足以下条件，ClickHouse 插件将自动渲染多线图：

• 字段 1：日期时间字段，别名为 `time`  

• 字段 2：用于分组的字段值，类型为字符串  

• 字段 3+：多个度量值  

例如：

SELECT  $__timeInterval(Timestamp) as time,  ServiceName,  quantile(0.99)(Duration)/1000000 AS p99FROM otel_tracesWHERE $__timeFilter(Timestamp)AND ( Timestamp  >= $__fromTime AND Timestamp <= $__toTime )GROUP BY ServiceName, timeORDER BY time ASCLIMIT 100000

在前面的部分，我们介绍了如何使用 IP 字典将地理坐标信息融入可观测性数据。如果你已经有了纬度和经度列，可以使用 geohashEncode 函数对这些数据进行可视化，从而生成与 Grafana 的地理地图图表兼容的地理哈希值。以下是一个查询示例和其对应的可视化效果：

WITH coords AS    (        SELECT            Latitude,            Longitude,            geohashEncode(Longitude, Latitude, 4) AS hash        FROM otel_logs_v2        WHERE (Longitude != 0) AND (Latitude != 0)    )SELECT    hash,    count() AS heat,    round(log10(heat), 2) AS adj_heatFROM coordsGROUP BY hash

Open Telemetry 项目提供了一个演示应用【https://opentelemetry.io/docs/demo/】。这个应用的一个维护版本已经集成了 ClickHouse，作为日志和追踪数据的存储源。你可以在此找到相关的代码仓库【https://github.com/ClickHouse/opentelemetry-demo】。用户可以按照官方提供的部署指南【https://opentelemetry.io/docs/demo/docker-deployment/】，使用 Docker 来部署该演示应用。在部署过程中，除了已有的组件外【https://opentelemetry.io/docs/demo/collector-data-flow-dashboard/】，还将部署一个 ClickHouse 实例，用于存储日志和追踪数据。