StatChart metricLabel migration: conceptual issues with legendFormat mapping
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- typescript
- Domain
- tooling
Research direction
Start by comparing PR #281 with the parent migration in Perses' internal/api/plugin/migrate/grafana.go, especially the panel conversion around line 85. Verify how StatChart and TimeSeries consume targets, legendFormat, and querySettings, then align the migration behavior and fixtures so the relevant fields are preserved and the intended mapping is testable at runtime.
Written by the indexing model from the issue text.
Description
Description
PR #281 introduced by @AntoineThebaud changes to StatChart's Grafana migration to extract metricLabel from legendFormat based on textMode. This issue discusses the conceptual foundation of this approach and its implications.
In Grafana's time-series queries, legendFormat is a template string that controls how series names are rendered in legends and on panels.
- "{{instance}}" - Shows just the instance label
- "Server {{instance}} ({{region}})" - Combines multiple labels in a template
- "Prometheus {{job}}"- Static text with label interpolation
The legendFormat is applied at query time to format the series name based on available labels (if more than one). The series name becomes the visual representation of that time-series.
What is metricLabel in Perses?
In Perses StatChart, metricLabel is a field selector that:
- Selects a specific field/column by name (regex pattern)
- Extracts that field's value from the query result
- Displays that value instead of the calculated numeric result
This maps directly to Grafana's reduceOptions.fields configuration, which specifies which column or field to use for the stat value.
How It Works:
When a query returns data with multiple fields:
Fields: instance, status, version, uptime
Row 1: [server1, up, 1.5.0, 42d]
Row 2: [server2, down, 1.6.0, 15d]
Without metricLabel (or fields in Grafana):
Display the default calculated value (e.g., last value from time-series)
With metricLabel:
For server1 stat: Display "1.5.0" (the version field value)
For server2 stat: Display "1.6.0" (the version field value)
The metricLabel feature exists specifically because Grafana queries can return multiple fields, and sometimes you want to display a non-numeric field value (like version, status, name) as the stat's main value instead of the calculated metric value.
Series Name vs Display Value
legendFormat controls the series name (what appears in legends when showing multiple series)
metricLabel controls the display value (what numeric result is replaced with)
These two features could be used independently or together, but extracting one from the other assumes a 1:1 relationship that doesn't necessarily exist.
Examples
No legendFormat and no metricLabel (thin line on the top is actual series name from very long labels list):
Both legendFormat and metricLabel applied:
The panel.targets Dependency
I found interesting bug where stat chart migration and timeseries migration is relying on panel.targets which is being ommited in grafana.go (perses repo).
The current migration includes:
if #textMode == "name" && (*#panel.targets[0].legendFormat | null) != null {
metricLabel: strings.Trim(#panel.targets[0].legendFormat, "{}")
}
This depends on panel.targets being present in the migration data. However:
The parent migration script in Perses main repo (grafana.go line ) omits panel.targets when converting panels
This means the condition (*#panel.targets[0].legendFormat | null) will always evaluate to null
The legendFormat extraction never actually occurs in practice. This is especially hard to catch since test input fixture includes targets making it different with actual migration runtime.
Should panel.targets be included in the parent migration?
The same pattern appears in TimeSeries migration with querySettings, creating the same dependency issue. And never migrating querySettings.
Suggestions
Was the legendFormat-to-metricLabel mapping introduced because some dashboards relied on this pattern? What was the actual use case?
I would simplify metricLabel migration relying only on fields from grafana:
#metricLabel: *#panel.options.reduceOptions.fields | null
if #metricLabel != null && #metricLabel != "" {
metricLabel: #metricLabel
}
And I think we need to keep targets in migration script in order to fix timeseries querySettings migration.
- Dominant language
- TypeScript
- Stars
- 33
- Forks
- 95
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 40
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from perses/plugins
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 48/100
Maintainers usually reply within 1 day
-
[Trino] Split long-format results into one series per labelPossibly taken @dougkirkley claimed this 2 days ago. Openenhancement
Difficulty 4/5 3-5 days Newbie friendliness 35/100
Maintainers usually reply within 1 day
-
[BUG] splunk: export parsing, job polling and missing values are not handled robustlyPossibly taken @AnKiT-GaRG2 claimed this 22 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 35/100
Maintainers usually reply within 1 day
-
[BUG] clickhouse: getTimeSeriesData drops dimension columns, collapsing long-format results into one seriesPossibly taken @aminadojava claimed this 50 days ago. Open
Difficulty 4/5 3-5 days Newbie friendliness 58/100
perses/plugins#843 · 1 reaction ·
Maintainers usually reply within 1 day
Similar issues
-
db-d1-sqlite: upsert is aliased to updateOne, so payload.kv.set never inserts new keysPossibly taken @pcbeingused333 claimed this today. OpenBug db: d1-sqlite Payload OSS
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
payloadcms/payload#19766 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
device-management-toolkit/sample-web-ui#3711 ·
Maintainers usually reply within 1 day
-
bug impact:low Team: SecuritySolution Team:Defend Workflows v9.6.0
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
elastic/kibana#306401 · 3 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
agentes-chat/agentes-chat#927 ·
Maintainers usually reply within 1 day
-
Closing a pinned tab jumps to the Tabs section instead of the next open pinned tabPossibly taken @seenimohamed claimed this today. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
ardia-browser/ardia#2769 ·
Maintainers usually reply within 1 day