feat: grafana query metadata

[MattiasMTS]

Type of Change

Please check the relevant option.

• 🚀 Feature
• 🐛 Bug Fix
• 📝 Documentation
• 🧹 Refactor / Chore

---

Feature

Adds Grafana dashboard UID and panel ID metadata to ClickHouse query logs by extending the existing ClientInfo.Comment mechanism.

When a query is executed from a Grafana dashboard panel, the ClickHouse system.query_log.client_name column now includes:
grafana-clickhouse/4.x.x clickhouse-go/2.43.0 (grafana_user:admin; grafana_dashboard:abc123; grafana_panel:42; lv:go/1.22; os:linux)

This is implemented by:

1. A new MutateQueryData() method (implementing sqlds.QueryDataMutator) that extracts X-Dashboard-Uid and X-Panel-Id from Grafana's forwarded request headers and stores them in the context
2. An updated MutateQuery() that reads the dashboard/panel info from context and appends it to the existing ClientInfo.Comment alongside the Grafana username

Who is this feature for?

When running ClickHouse as a Grafana datasource, it's currently impossible to identify which dashboard or panel is generating expensive or slow queries. The only metadata available in
system.query_log is the Grafana username (added in a prior PR). This makes it difficult to:

• Debug memory pressure caused by specific dashboard panels
• Identify which dashboards need query optimization
• Attribute resource consumption to specific panels during incidents

This is especially critical for shared ClickHouse read replicas serving multiple Grafana dashboards, where a single heavy panel can starve other queries.

How to test this feature

Provide step-by-step instructions for reviewers to test the feature.

1. Configure a ClickHouse datasource in Grafana (either native or HTTP protocol)
2. Create a dashboard with a panel that queries ClickHouse
3. Open the dashboard and let the panel query execute
4. Query system.query_log on ClickHouse:

SELECT client_name, query 
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC LIMIT 10

5. Verify client_name contains grafana_dashboard: and grafana_panel: alongside the existing grafana_user:

---

Bug Fix

If this is a bug fix, please complete this section. Otherwise, delete it.

What is the bug?

Provide a clear and concise description of the bug.

How to reproduce

Provide step-by-step instructions to reproduce the bug.

Related Issues

Link to any open issues this PR will close. Use "Closes #123" or "Fixes #123" syntax.

Closes #

Environment (if no related issue)

If there is no open issue, please specify the versions where the bug occurs.

• ClickHouse version:
• Grafana version:
• Plugin version:

---

Screenshots / Videos

Please provide screenshots or videos demonstrating the bug or the feature working. This helps reviewers understand the change visually and speeds up the review process.

Before	After

---

Please check that:

• Tests for this change have been added/updated.
• Documentation has been added/updated (where applicable).

Special notes for your reviewer

• No frontend changes. This is a backend-only change in pkg/plugin/driver.go
• No breaking changes. The existing grafana_user comment is preserved; dashboard/panel info is appended alongside it
• Works on both protocols. ClientInfo.Comment is protocol-agnostic (native: client_name column, HTTP: http_user_agent column in system.query_log)
• Grafana v9.4+ required. The X-Dashboard-Uid and X-Panel-Id headers are forwarded to backend plugins. On older Grafana versions, the headers won't be present and the behavior is unchanged (only grafana_user is included)

[cla-assistant]

All committers have signed the CLA.

[SpencerTorres]

Thanks! This is our best available solution until we can get metadata on the query log table.

[SpencerTorres]

Still concerned with how complex dashboard names may be parsed, but this is still pretty good.

I'm not sure if it's the standard for client info but maybe we could try to protect it with %q to quote/escape any complex dashboard names? I'll let other reviewers decide on that

cc @borismattijssen

[borismattijssen]

This is great! Thanks for adding this @MattiasMTS .

One small request: Can the X-Rule-Uid header also be added? We need this for queries used for alerting rules.

[borismattijssen]

Still concerned with how complex dashboard names may be parsed, but this is still pretty good.

I'm not sure if it's the standard for client info but maybe we could try to protect it with %q to quote/escape any complex dashboard names? I'll let other reviewers decide on that

IIUC, this is only logging IDs, not names.

[MattiasMTS]

This is great! Thanks for adding this @MattiasMTS .

One small request: Can the X-Rule-Uid header also be added? We need this for queries used for alerting rules.

Done! Thanks ✨