feat(frontend): resolve symbol-ref trees after the final merge

[jake-kramer]

Part of a series: symbol-aware tree references (6 of 8)

Full context and series overview: #5317 (PR 1). Compact map:

1. symbolizer: expose address-level Resolve API (feat(symbolizer): expose address-level symbol resolution as a public API #5317)
2. proto: SymbolRefTable + tree query/report fields (feat(query): add SymbolRefTable and symbol_refs tree fields to the query API #5318)
3. model/symbolref: intern table + merge rebasing (feat(model): add symbolref package for symbol-aware tree references #5321)
4. model/symbolref: unresolved-binary grouping + tree rebuild (feat(model): add unresolved-binary grouping and tree rebuild to symbolref #5322)
5. symdb: symbol-ref tree resolver output (feat(symdb): add symbol-ref tree resolver output #5332) · querybackend: query mode + aggregation (feat(querybackend): produce and aggregate symbol-ref tree reports #5333)
6. frontend: orchestration behind a default-off per-tenant flag ← this PR
7. integration tests + docs (test(symbolizer): add symbol-ref tree integration tests and docs #5335)
8. symdb: compaction preserves line-less locations (fix(symdb): preserve line-less locations when rewriting partitions without functions #5337) — stacked at the bottom of the series, merges first

Tracking issue: grafana/pyroscope-squad#487. Based on #5333's branch.

What

The activation PR. Behind a new per-tenant flag symbolizer.symbol-ref-trees-enabled (default off), tree and span-profile queries request symbol-ref tree reports instead of being rewritten through the pprof path when symbolization is needed. With the flag off, request construction and the legacy symbolization path are byte-identical to today — that's the rollback story.

When a merged report comes back with unresolved references, the frontend:

• groups them by binary (symbolref.UnresolvedBinaries),
• resolves each through the symbolizer's address-level API under bounded concurrency (the existing max-debuginfod-concurrency, shared with the pprof path) and a per-binary timeout (symbolizer.resolve-timeout, default 20s),
• rebuilds the final tree (symbolref.Rebuild), rendering the existing binary!0xaddr fallback for anything unresolved.

Error semantics: a per-binary timeout degrades that one binary to fallbacks and lets the query succeed; cancellation of the request context fails the query, matching how SymbolizePprof errors are already handled at these call sites.

Observability

A single unsampled counter, symbol_ref_locations_total{result=resolved|miss|timeout}, drives the fallback-rate signal (an alert can't be built on sampled traces). The per-request detail — resolution timing, binary count, unresolved-reference count — lives on a resolveSymbolRefs tracing span instead of dedicated metrics.

Testing

go test ./pkg/frontend/... ./pkg/validation/... -race green. Tests cover: flag off ⇒ byte-identical legacy behavior (existing shouldSymbolize tests untouched); flag on ⇒ symbol-ref request, no legacy wrapper; old-backend/degenerate responses pass through; per-buildID resolution with sorted/deduped addresses and fallback on miss; per-binary timeout ⇒ fallback + query succeeds; request-context cancellation ⇒ query fails; multi-tenant all-tenants gating. golangci-lint clean; whole-repo build clean.

[jake-kramer]

This change is part of the following stack:

• fix(symdb): preserve line-less locations when rewriting partitions without functions #5337
  • feat(symbolizer): expose address-level symbol resolution as a public API #5317
    • feat(query): add SymbolRefTable and symbol_refs tree fields to the query API #5318
      • feat(model): add symbolref package for symbol-aware tree references #5321
        • feat(model): add unresolved-binary grouping and tree rebuild to symbolref #5322
          • feat(symdb): add symbol-ref tree resolver output #5332
            • feat(querybackend): produce and aggregate symbol-ref tree reports #5333
              • feat(frontend): resolve symbol-ref trees after the final merge #5334 ◀
                • test(symbolizer): add symbol-ref tree integration tests and docs #5335
                  • test(symbolizer): comparative benchmark, symbol-ref vs pprof-detour #5336

_{Change managed by git-spice.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4fa35d0. Configure here.}