创建可视化
GROUP BY 查询——你需要定义要在所选维度上聚合的指标。
例如，你可以绘制按服务名称分组的错误数量 (count()) 图表。
在下面的示例中，我们使用 sql.clickhouse.com 上提供的远程数据集，详见指南 “远程演示数据集”。你也可以访问 play-clickstack.clickhouse.com 来复现这些示例。
2
创建可视化
在下面的示例中，我们绘制按服务名称区分的平均请求耗时随时间变化的图表。这要求用户指定一个指标、一列 (可以是 SQL 表达式) 以及一个聚合字段。从顶部菜单中选择
Line/Bar 可视化类型，然后选择 Traces 数据集 (如果使用 play-clickstack.clickhouse.com，则选择 Demo Traces) 。填写以下值：- 指标：
Average - 列：
Duration/1000 - Where：
<empty> - Group By：
ServiceName - 别名：
Average Time
WHERE 子句，也可以使用 Lucene 语法来过滤事件，并设置事件可视化的时间范围。还支持多个数据系列。例如，添加过滤器 ServiceName:"frontend"，按 frontend 服务进行过滤。点击 Add Series，添加第二个表示事件数量随时间变化的数据系列，并将别名设为 Count。若要基于现有数据系列创建一个类似的新数据系列，你可以直接复制，而不必从头开始。点击某个数据系列行上的复制图标 (Duplicate series)，即可在其正下方插入一个副本。副本会保留原数据系列的设置，例如指标、列和过滤器。然后你只需修改不同的字段 (例如聚合方式) ，并为副本设置自己的别名。在所有支持多个数据系列 的地方都可以使用复制功能。对于仅允许一个数据系列 的可视化类型，例如 数值、Pie 和 Heatmap，则会隐藏该功能。可以基于任何数据源创建可视化——无论是指标、trace 还是日志。ClickStack 将这些统一视为宽事件。任何数值列都可以按时间绘制成图，而字符串、日期或数值列都可用于分组。这种统一方式使你能够基于一致且灵活的模型，跨不同类型的遥测数据构建仪表盘。
创建仪表盘
2
创建可视化——按服务查看平均请求耗时
选择
Add New Tile，打开可视化创建面板。在顶部菜单中选择 Line/Bar 可视化类型，然后选择 Traces 数据集 (如果使用 play-clickstack.clickhouse.com，则选择 Demo Traces) 。填写以下值，以创建一个按服务名称展示平均请求耗时随时间变化的图表：- 图表名称：
Average duration by service - 指标：
Average - 列：
Duration/1000 - Where：
<empty> - Group By：
ServiceName - 别名：
Average Time
Save 之前，先点击 play 按钮。调整可视化大小，使其占满仪表板的整个宽度。3
创建可视化——按服务查看事件随时间的变化
选择
Add New Tile 打开可视化创建面板。从顶部菜单中选择 Line/Bar 可视化类型，然后选择 Logs 数据集 (如果使用 play-clickstack.clickhouse.com，则选择 Demo Logs) 。填写以下值，以创建一个按服务名称展示事件计数随时间变化的图表：- 图表名称：
Event count by service - 指标：
Count of Events - 条件：
<empty> - 分组依据：
ServiceName - 别名：
Count of events
Save 前，先点击 play 按钮。调整可视化大小，使其占满整个仪表板宽度。4
为 span 耗时添加热力图卡片
热力图卡片会将落入每个 (时间、值) bucket 的事件数绘制成彩色网格。当你想查看某个分布随时间变化的形态，而不只是平均值或某一个百分位数时，应使用热力图。延迟热力图能够揭示双峰耗时模式、慢尾聚集或突发扩散，而这些现象在线图中往往会被平均掉。要添加热力图卡片：
- 选择
Add New Tile。 - 从顶部菜单中选择
Heatmap可视化类型。数据源下拉列表只会显示source type isTraces的数据源。日志、指标和 session 数据源会被过滤掉，因为热力图需要 span 耗时列，而这只有 traces 数据源才提供。 - 按名称选择任意一个 traces 数据源。名称本身是任意的，关键在于类型。
- Value：该数据源的
Duration Expression，并按当前显示单位进行缩放 (例如(Duration)/1e6，将每个事件的 span 耗时从纳秒转换为毫秒) - Count：
count()
- 设置图表名称，并使用
Where将热力图限定到你想观察其性能的特定服务或一组操作。 - 调整时间范围以匹配你关注的时间段。较大的时间范围可以揭示分布偏移和双峰延迟模式，而较短的时间窗口可能会掩盖这些现象。
Run 预览图表，然后点击 Save。保存后的卡片会在仪表盘上渲染为热力图。将鼠标悬停在任意单元上，即可查看 bucket 边界和事件数。下钻到 Event Deltas
点击已渲染热力图卡片中的任意单元，即可打开 View in Event Deltas 操作。选择它后，会打开 Event Deltas 视图，并带入该卡片的数据源、Where 子句和时间范围。在那里，你可以交互式检查同一分布，按 attribute 切分以查看慢 spans 与快 spans 的差异，并查看任意单元背后的各个 spans，而无需手动重新构建查询。5
筛选仪表板
可在仪表板级别应用 Lucene 或 SQL 过滤器以及时间范围，这些设置会自动同步到所有可视化中。为演示这一点，请将 Lucene 过滤器
ServiceName:"frontend" 应用到仪表板，并将时间窗口调整为最近 3 小时。注意，此时所有可视化都只显示来自 frontend 服务的数据。仪表板会自动保存。要设置仪表板名称，请选中标题并进行修改，然后点击 Save Name。仪表盘 - 编辑可视化
卡片显示设置
数值卡片颜色
语义标记 (面向状态) ：
当数值表示状态时，请使用语义标记 (例如，使用
chart-error 表示错误计数，或使用 chart-success 表示健康率) 。如果希望在相关 KPI 卡片之间形成视觉区分，但不表达状态含义，请使用 categorical 标记。
较旧的配置可能仍存储 legacy 数值标记 (chart-1 到 chart-10) 。加载 仪表盘 时，ClickStack 会将这些标记映射为上述以色相命名的标记。
同一调色板还支持在同一抽屉中设置可选的 颜色规则：根据显示值评估有序条件 (最后匹配的规则生效) 。如果没有规则匹配，则应用静态颜色；若未设置静态颜色，则使用默认文本颜色。
数值卡片背景图表
仪表盘 API：数值卡片颜色
POST / PUT /api/v2/dashboards) 创建或更新仪表盘时，请将 builder 数值卡片配置中的 color 设为调色板标记。不支持原始十六进制值。
color 可接受上述 categorical 和语义列表中的任何标记 (例如 chart-blue 或 chart-success) 。可选的 backgroundChart.color 可使用相同的标记枚举覆盖迷你线图的颜色。有关身份验证和基础 URL，请参阅 ClickStack API 参考文档。
仪表盘 - 列表与搜索
仪表盘 - 标签
- 组织方式：标签显示在左侧边栏中，仪表盘和已保存的搜索会按分配的标签分组
- 多个标签：您可以为单个项目添加一个或多个标签，以便更好地分类
- 自动创建：如果您分配了一个尚不存在的标签，系统会自动创建该标签
- 易于管理：您可以随时添加或移除标签，以调整您的组织结构
自定义过滤器和变量
- 广播 — 将所选内容作为过滤条件应用于匹配的卡片。无需更新卡片以引用该过滤器。
- 变量 — 将所选内容以
$variableName的形式提供给卡片查询，因此每个卡片可自行决定在何处以及如何使用该值。
1
打开“Edit 过滤器”对话框
打开一个已保存的仪表盘，然后在工具栏中选择 Edit 过滤器 and 变量。
2
添加新过滤器
点击 Add new filter。通过填写 Display Name、选择 数据源，并输入 Filter expression 来配置过滤器；它可以是一个 SQL 列或表达式，其不同值将填充到下拉框中。点击 Save filter。例如，要为链路追踪数据添加服务过滤器，可选择
Traces 数据源，并将 ServiceName 用作过滤表达式。“Dropdown values filter”为可选项，可用于限制下拉框中显示的值。同一对话框还可控制过滤器是否会广播其值，以及是否可作为变量使用，下文将对此进行说明。过滤器 模态框会显示该仪表盘上已配置的所有过滤器。你可以在这里编辑或删除现有过滤器，也可以添加更多过滤器。3
使用过滤器
关闭 过滤器 模态框。新的下拉过滤器会显示在搜索栏下方。点击它可查看可用值，然后选择一个值，以过滤仪表盘上的所有可视化内容。
4
（可选）将过滤器值保存为默认值
要将某个过滤器选择保存为仪表盘的默认值，请在仪表盘菜单中选择 Save Query & 过滤器 as Default。此后，该仪表盘打开时将始终自动应用所选过滤器。若要重置，请在同一菜单中选择 Remove Default Query & 过滤器。
自定义下拉过滤器适用于已保存的仪表盘。要查看这种用法的实际示例，请参阅 Kubernetes 仪表盘，其中为 pod (容器组) 、部署、节点名称、命名空间和集群提供了内置下拉过滤器。
广播
$__filters 宏，并且已选择来源，因为 ClickStack 无法推断该条件应在手写查询的何处使用。
变量
$variableName 的形式供卡片查询使用。变量 name 默认为过滤器的显示名称 (移除非法字符后) ，也可自行覆盖。名称必须以字母开头，且只能包含字母、数字和下划线。
如果不希望广播 WHERE 条件，请使用变量——例如，在 SELECT 表达式、HAVING 子句或连接键中使用该值，或者根据不同于过滤器自身表达式的列来过滤卡片。
引用变量
由于在未选择任何值时，
$name 会呈现为 NULL，因此在需要 SQL 谓词的地方，建议优先使用以下宏。当变量未选择任何值时，这些宏都会展开为 1=1，从而确保查询仍然有效：
在图表构建器卡片中使用变量
SELECT 列和各序列表达式、WHERE、GROUP BY 以及 HAVING。编辑器会自动补全仪表盘变量，并显示每个引用在当前选择下展开后的内容。
在 SQL 模式下，建议使用 $__filter 和 $__conditionalAll 宏，以确保变量选择为空时查询仍然有效。Lucene 输入不支持宏，应直接引用原始变量 (例如 ServiceName:$service) 。
在 Lucene 输入中，变量引用本身是否加引号决定了多值选择的匹配方式。假设 $service 选择了 a,b：
如果所选值应与
Field 精确匹配而非按子串匹配，请为变量引用加引号 — Field:"$var"。
在 SQL 卡片中使用变量
引用仪表盘变量的卡片上的告警会将每个变量视为空值进行评估，而不会使用仪表盘中选定的值。
下钻到搜索页
- 查看所有事件 — 跳转到搜索页，显示所选时间范围内的所有事件。
- 按组筛选 — 跳转到搜索页，并筛选为特定数据系列。
预设
ClickHouse 仪表盘
所需的系统表访问权限此仪表盘会查询 ClickHouse 系统表 以显示关键指标。需要以下授权：
GRANT SHOW COLUMNS, SELECT(CurrentMetric_MemoryTracking, CurrentMetric_S3Requests, ProfileEvent_OSCPUVirtualTimeMicroseconds, ProfileEvent_OSReadChars, ProfileEvent_OSWriteChars, ProfileEvent_S3GetObject, ProfileEvent_S3ListObjects, ProfileEvent_S3PutObject, ProfileEvent_S3UploadPart, event_time) ON system.metric_logGRANT SHOW COLUMNS, SELECT(active, database, partition, rows, table) ON system.partsGRANT SHOW COLUMNS, SELECT(event_date, event_time, memory_usage, normalized_query_hash, query, query_duration_ms, query_kind, read_rows, tables, type, written_bytes, written_rows) ON system.query_logGRANT SHOW COLUMNS, SELECT(event_date, event_time, hostname, metric, value) ON system.transposed_metric_log