Grafana clickhouse dashboard
Skill jimkeecn/Claudalytics/.claude/skills/grafana-clickhouse-dashboard
Pitfalls and correct patterns when writing Grafana dashboard JSON for the grafana-clickhouse-datasource plugin. Use when creating or debugging ClickHouse-backed Grafana dashboards.From its SKILL.md
npx -y skills add jimkeecn/Claudalytics --skill grafana-clickhouse-dashboardAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.1 KB, as published. Nobody here has run it
Grafana ClickHouse Dashboard Pitfalls
Hard-won lessons from debugging the Claudalytics OTel dashboard. Apply these rules when writing or editing Grafana dashboard JSON that uses the grafana-clickhouse-datasource plugin.
Rule 1: format must be numeric, not string
The plugin unmarshals format into a Go sqlutil.FormatQueryOption (an integer type).
// WRONG — causes "cannot unmarshal string into Go struct field"
{ "rawSql": "SELECT ...", "format": "table" }
{ "rawSql": "SELECT ...", "format": "time_series" }
// CORRECT
{ "rawSql": "SELECT ...", "format": 1, "queryType": "sql" } // table
{ "rawSql": "SELECT ...", "format": 2, "queryType": "sql" } // time series
| Value | Meaning |
|---|---|
1 | Table (stat panels, tables, pie charts, bar charts) |
2 | Time series (timeseries panels with time column) |
Always include "queryType": "sql" on every target.
Rule 2: Know where OTel attributes live in ClickHouse
The OTel Collector's ClickHouse exporter creates tables with two attribute maps:
| Column | Contains | Set by |
|---|---|---|
ResourceAttributes | Resource-level context: project.name, service.name, os.type, host.arch | OTEL_RESOURCE_ATTRIBUTES env var + SDK defaults |
LogAttributes | Per-event data: session.id, event.name, model, cost_usd, tool_name, input_tokens | Claude Code OTel SDK per event |
Common mistake: assuming project.name is in LogAttributes because session.id is. They live in different maps.
To discover what's actually in each map:
-- Check ResourceAttributes keys
SELECT DISTINCT mapKeys(ResourceAttributes) FROM claudalytics.otel_logs LIMIT 1
-- Check LogAttributes keys
SELECT DISTINCT mapKeys(LogAttributes) FROM claudalytics.otel_logs LIMIT 1
-- Check actual values for a specific key
SELECT ResourceAttributes['project.name'], count() FROM claudalytics.otel_logs GROUP BY 1
Rule 3: Grafana caches provisioned dashboards
Grafana reads provisioned dashboard JSON files on startup and caches them in its internal database. Changing the file on disk does NOT immediately update the dashboard.
To force a reload:
cd docker-stack && docker compose restart grafana
Then hard-refresh the browser with Ctrl+Shift+R to clear browser cache too.
The updateIntervalSeconds: 30 in dashboards.yaml should poll for changes, but in practice a restart is more reliable, especially when the dashboard version field hasn't been incremented.
Rule 4: Validate queries in ClickHouse first
Before putting a query into dashboard JSON, test it directly in ClickHouse:
MSYS_NO_PATHCONV=1 docker exec claudalytics-clickhouse clickhouse-client --query "YOUR QUERY HERE"
The MSYS_NO_PATHCONV=1 prefix is required on Windows Git Bash to prevent path translation of Linux paths inside the query.
Rule 5: Template variable queries for ClickHouse
Grafana template variables with type: "query" use a different query path than panel queries. They do NOT support the format field — just provide the raw SQL string in the query field.
The ClickHouse plugin returns the first column as the variable value and the second column (if present) as the display text.
{
"name": "project",
"type": "query",
"datasource": { "type": "grafana-clickhouse-datasource", "uid": "clickhouse-claudalytics" },
"query": "SELECT DISTINCT project_name FROM claudalytics.sessions FINAL ORDER BY project_name"
}
Reference: Complete target structure
{
"refId": "A",
"rawSql": "SELECT count() AS total FROM claudalytics.otel_logs WHERE $__timeFilter(Timestamp)",
"format": 1,
"queryType": "sql",
"datasource": {
"type": "grafana-clickhouse-datasource",
"uid": "clickhouse-claudalytics"
}
}