Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

StatChart metricLabel migration: conceptual issues with legendFormat mapping

Đang mở
  • Có gì không ổn?
#501 5 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Lỗi
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
typescript
Lĩnh vực
tooling

Hướng nghiên cứu

Bắt đầu bằng cách so sánh PR #281 với migration cha trong Perses' internal/api/plugin/migrate/grafana.go, đặc biệt là phần chuyển đổi panel quanh dòng 85. Xác minh cách StatChart và TimeSeries sử dụng targets, legendFormat và querySettings, sau đó điều chỉnh hành vi migration và các fixture để bảo toàn những trường liên quan và có thể kiểm thử mapping dự kiến khi runtime.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

bug
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):

Image

Both legendFormat and metricLabel applied:

Image

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.

Ngôn ngữ chính
TypeScript
Star
32
Fork
86
Merge trung bình
2 ngày 11 giờ
Pull request đã merge (30 ngày)
44

Chuẩn bị môi trường

  • Không có Dockerfile hay tệp Docker Compose
  • Có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của perses/plugins

Tất cả issue của perses/plugins

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.