agentsclimarketplace

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

Install
npx -y skills add jimkeecn/Claudalytics --skill grafana-clickhouse-dashboard

Assembled 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
ValueMeaning
1Table (stat panels, tables, pie charts, bar charts)
2Time 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:

ColumnContainsSet by
ResourceAttributesResource-level context: project.name, service.name, os.type, host.archOTEL_RESOURCE_ATTRIBUTES env var + SDK defaults
LogAttributesPer-event data: session.id, event.name, model, cost_usd, tool_name, input_tokensClaude 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"
  }
}

Source: grafana/clickhouse-datasource dashboard examples

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.