Make the listenerMetrics example match the listener defaults

[KR-Ravindra]

Problem

charts/gha-runner-scale-set/values.yaml (and the listener.metrics block in charts/gha-runner-scale-set-experimental/values.yaml) ship a commented-out listenerMetrics example introduced as the defaults ("Default buckets are provided here for documentation purposes") and tell users to uncomment it when they want custom histogram buckets.

The example is not the default configuration. It adds job_workflow_ref, job_workflow_name and job_workflow_target to both counters and both histograms, while the listener's built-in defaultMetrics has none of them. Anyone who uncomments the block to tune buckets silently starts exporting per-ref/per-PR labels on histograms with 45 buckets, which multiplies the series count on busy repositories by orders of magnitude. Nothing in the file mentions the cardinality cost of those labels.

Root cause

• cmd/ghalistener/metrics/metrics.go:162-281 (defaultMetrics): counters and histograms carry only enterprise, organization, repository, job_name, event_name (+ job_result).
• charts/gha-runner-scale-set/values.yaml:160, :170-172, :194, :252-254 and charts/gha-runner-scale-set-experimental/values.yaml:327-328, :335, :344-346, :368, :426-428: the example lists the three job_workflow_* labels on top of the defaults.

job_workflow_ref was dropped from the defaults in #3671 because of cardinality (#3670, #3153) and re-added in #4054 as an opt-in label plus this example; #4240 then added job_workflow_name/job_workflow_target to the example only. The example drifted into a superset of the defaults while the surrounding comment kept calling it the defaults.

Fix

Documentation/values-only change; no template or Go behaviour changes.

• Remove the three job_workflow_* labels from the example in both charts so it matches defaultMetrics exactly. Uncommenting the block (for example to change buckets) no longer changes the exported label set.
• Rewrite the comment: state that the block matches the built-in defaults, list job_workflow_ref, job_workflow_name and job_workflow_target as optional labels, and explain that the two ref-based labels create a new series per branch/pull request per job, multiplied by the bucket count on histograms.
• Add cmd/ghalistener/metrics/chart_values_test.go: uncomments the example block from both values files and asserts that the metric names, labels and buckets equal defaultMetrics, so the example cannot drift again without the test failing.

How tested

Before (test added, values unchanged):

--- FAIL: TestChartValuesMetricsExampleMatchesDefaults (0.00s)
    --- FAIL: TestChartValuesMetricsExampleMatchesDefaults/gha-runner-scale-set (0.00s)
        chart_values_test.go:40: elements differ
            extra elements in list B: "job_workflow_ref", "job_workflow_name", "job_workflow_target"
            Messages: counter "gha_started_jobs_total" labels
        chart_values_test.go:40: ... Messages: counter "gha_completed_jobs_total" labels
        chart_values_test.go:50: ... Messages: histogram "gha_job_startup_duration_seconds" labels
        chart_values_test.go:50: ... Messages: histogram "gha_job_execution_duration_seconds" labels
    --- FAIL: TestChartValuesMetricsExampleMatchesDefaults/gha-runner-scale-set-experimental (0.00s)
        (same four label mismatches)
FAIL	github.com/actions/actions-runner-controller/cmd/ghalistener/metrics	0.009s

After:

--- PASS: TestChartValuesMetricsExampleMatchesDefaults (0.00s)
    --- PASS: TestChartValuesMetricsExampleMatchesDefaults/gha-runner-scale-set (0.00s)
    --- PASS: TestChartValuesMetricsExampleMatchesDefaults/gha-runner-scale-set-experimental (0.00s)
ok  	github.com/actions/actions-runner-controller/cmd/ghalistener/metrics	0.008s

Also run:

• go test ./cmd/ghalistener/metrics/ and go test ./charts/gha-runner-scale-set/tests/: pass
• go vet ./cmd/ghalistener/metrics/, gofmt -l: clean
• helm unittest charts/gha-runner-scale-set-experimental: 176 passed
• helm lint and helm template with default values for both charts: rendered output is byte-identical before and after (the block is commented out, so the default render is unchanged)
• helm template -f <uncommented example> on the main chart: the rendered listenerMetrics now carries the default label set only

Links

• Issue: gha-runner-scale-set: the listenerMetrics example in values.yaml reads as a default but adds unbounded job_workflow_ref/name/target labels #4625
• Related history: metrics cardinality for ghalistener #3671, Add job_workflow_ref label to listener metrics #4054, Add workflow name and target labels #4240
• Related open PRs touching the same comment block: docs: clarify listener metric label sources #4525 (label sources), Add job_workflow_repo and job_workflow_path metric labels #4606 (new labels)

This change was prepared with an AI agent operated by KR-Ravindra, who reviewed and tested it.

[KR-Ravindra]

Round 1 self-review.

1. Checked cmd/ghalistener/metrics/metrics.go defaultMetrics on master: counters and histograms carry enterprise, organization, repository, job_name, event_name (+ job_result) only, no job_workflow_*, so the example in both values files was a superset of the defaults as described.
2. Ran go test ./cmd/ghalistener/metrics/ -run TestChartValuesMetricsExampleMatchesDefaults on this branch (pass) and again with the two values files replaced by their master versions (fails with extra elements in list B: job_workflow_ref, job_workflow_name, job_workflow_target for all four metrics), so the test guards the drift it is meant to.
3. The uncommenting helper keys on the exact # listenerMetrics: / # metrics: line and stops at the first line without the comment prefix, which matches the block layout in both files.

Default render is unchanged since the block stays commented out. Workflows need maintainer approval to run here; marking ready.

[Copilot]

🟢 Approval recommended

The changes are documentation/values-only plus a targeted regression test, with no runtime behavior changes and clear verification of example/default consistency.

Pull request overview

Aligns the Helm chart listenerMetrics commented examples with the listener’s built-in defaultMetrics to prevent users from unintentionally enabling high-cardinality workflow-ref labels when they only meant to adjust histogram buckets. Adds a regression test to ensure the examples cannot drift from defaultMetrics again.

Changes:

• Update both chart values.yaml files so the commented listenerMetrics/listener.metrics example label sets match defaultMetrics (removes job_workflow_* from the example).
• Rewrite the surrounding comment to clarify the example matches defaults and to document the cardinality impact of opting into job_workflow_ref / job_workflow_target.
• Add cmd/ghalistener/metrics/chart_values_test.go to parse/uncomment the example blocks and assert metric names/labels/buckets match defaultMetrics.

File summaries

File	Description
cmd/ghalistener/metrics/chart_values_test.go	Adds a Go unit test to ensure chart metric examples stay identical to defaultMetrics.
charts/gha-runner-scale-set/values.yaml	Makes the commented listenerMetrics example match listener defaults and improves cardinality guidance.
charts/gha-runner-scale-set-experimental/values.yaml	Same alignment and comment updates for the experimental chart’s nested listener.metrics example.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.