elastic / elastic/observability-migration-platform
[Grafana] Apply metric_map in the native PromQL path (currently bypassed) so operators can keep PromQL output and rename metrics
- Dominant language
- Python
- Stars
- 6
- Forks
- 8
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 23
Description
## Problem statement
On `main`, `metric_map` (PR #305) only takes effect on the **ES|QL** translation path. The **native PromQL** path embeds the literal source PromQL text and never calls `resolve_metric_field`, so any configured `metric_map` entry is silently ineffective. To avoid contradicting the "no silent renames" contract, the tool surfaces a panel note via `_metric_map_bypass_note` (`observability_migration/adapters/source/grafana/panels.py:1925`) and marks the panel `migrated_with_warnings`:
> metric_map not applied for : native PROMQL requires literal target metric names; use ES|QL translation (--metric-map-file auto-selects it, or pass --translation-mode esql)
This means an operator cannot currently have **both**: native PromQL output (literal Prometheus metric names / TS query in Kibana) **and** metric-name renames to their existing OTel fields. `--metric-map-file` in `auto` mode auto-selects ES|QL specifically to sidestep this; an explicit `--translation-mode native` (or a rule-pack-only map) hits the bypass.
This is a real use case: some operators want to keep the PromQL-native rendering (closer to the source dashboard, PromQL-literate teams) while still pointing panels at existing OTel data whose field names differ.
## Proposed change
Apply `metric_map` in the native PromQL path, at least for the tractable cases:
1. **Class-1 (exact renames)**: rewrite the literal metric token(s) in the native PromQL string from `source_metric` to `target_field` before emitting. This is a straightforward token substitution and removes the bypass warning for exact renames.
2. **Class-2 (transform / attribute_filter / unit_scale)**: these generally cannot be expressed as a literal PromQL rename. Keep the explicit gap/warning (or point the operator to ES|QL), consistent with #314. Do not emit a bare rename that would be wrong.
3. Keep the current warning only for the genuinely unsupported (Class-2) remainder, instead of for every mapped metric.
## Acceptance
- A dashboard migrated with `--translation-mode native` + `--metric-map-file` (Class-1 entries) emits native PromQL referencing the target field names, with no `metric_map not applied` warning for those metrics.
- Class-2 entries still surface an actionable note (use ES|QL) and are not silently renamed.
- Unit/snapshot tests cover native-path Class-1 substitution and Class-2 pass-through-with-warning.
## Code pointers
- `observability_migration/adapters/source/grafana/panels.py`: `_metric_map_bypass_note` (1925), `build_native_promql_query` (1596), `_prefix_native_metric_fields` (1385), and the native translate paths that call the bypass note (~2178, ~2360).
- `observability_migration/adapters/source/grafana/schema.py`: `resolve_metric_field` (canonical apply/classify logic to reuse).
## Related
Follows PR #305. Related: #314 (Class-2 emission), #309 (metric-name mapping layer).
Contributor guide
Research direction
Start in observability_migration/adapters/source/grafana/panels.py with build_native_promql_query, _prefix_native_metric_fields, and the native paths calling _metric_map_bypass_note. Read schema.py's resolve_metric_field for mapping classification, then inspect the existing unit or snapshot tests. Done means Class-1 native queries use target fields without the bypass warning, while Class-2 mappings remain unchanged and retain an actionable warning.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- grafana, python
- Domain
- observability-sre, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100