MetaMask / MetaMask/metamask-extension
[P2] Sentry distributed tracing — wrap background entry points
- Dominant language
- TypeScript
- Stars
- 13.2k
- Forks
- 5.6k
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 451
Description
**Parent Epic:** [#6759 - Sentry observability maturity](https://github.com/MetaMask/MetaMask-planning/issues/6759)
**File:** `shared/lib/background-entry-tracing.ts` (new), call sites in `app/scripts/streams/provider-stream.ts`, `app/scripts/controllers/metametrics-controller.ts`, `app/scripts/controllers/app-state-controller.ts`
**Size:** S | **Hours:** 3-5
---
## Problem
Background-only flows (alarm callbacks, runtime message handlers, intervals, timers) execute without a parent Sentry trace, so their controller activity, `http.client` calls, and core-package `trace()` callers don't show up in any Sentry trace waterfall.
The four cases where `getActiveSpan()` returns null on the background side:
1. Sentry not yet initialized (early service worker startup)
2. MetaMetrics disabled (no transactions opened)
3. Trace was sampled out (only 0.75% of UI traces are sampled)
4. **Background entry without a UI parent** — alarms, `chrome.runtime.onMessage`, `setInterval`, timers, WebSocket events
PR #39891 addresses cases 1-3 via Wrappers 1-3. This issue covers case 4.
---
## Solution
Add `wrapBackgroundEntry(name, fn)` helper to `shared/lib/`:
- Wraps a handler with a `Background Entry: ${name}` root span (`op: 'background.entry'`).
- Volume bounded by global `tracesSampleRate` (0.0075), no per-call sub-sampling.
- Returns the original handler unchanged when `SENTRY_DISTRIBUTED_TRACING_DISABLED` is set, in lockstep with the rest of the kill switch.
- Same wrapper pattern as `wrapMessengerWithTracing` (HOF, no decorators).
Initial coverage to ship:
- `app/scripts/streams/provider-stream.ts` — `runtime.onMessage` listener for content-script ready
- `app/scripts/controllers/metametrics-controller.ts` — fragment-finalization alarm + non-MV3 `setInterval`
- `app/scripts/controllers/app-state-controller.ts` — auto-lock alarm + non-MV3 `setTimeout`
Deliberately deferred to subsequent follow-ups:
- Tab/window listeners (`tabs.onActivated`, `windows.onFocusChanged`)
- Runtime lifecycle (`onInstalled`, `onStartup`, `onMessageExternal`)
- WebSocket message handlers (already partially covered by `BackendWebSocketService` — verify before wrapping)
---
## Acceptance Criteria
- [ ] `wrapBackgroundEntry` helper added to `shared/lib/background-entry-tracing.ts` with unit tests
- [ ] `TraceRequest['name']` extended to allow `` `Background Entry: ${string}` `` template literal
- [ ] Three initial entry points wrapped (provider-stream, metametrics, app-state-controller)
- [ ] Sentry shows `Background Entry: {name}` root traces queryable by `op:background.entry`
- [ ] Kill switch verified to disable wrapping (helper returns original fn)
- [ ] No CI regressions (lint, unit tests, e2e)
- [ ] PR body documents the new wrapper layer in the Wrappers table
---
## Labels
`team-extension-platform`, `area-observability`
---
## Dependencies
**Depends on:** #39891 (this ticket builds on the existing wrapper infrastructure)
**Dependents:** —
---
## Notes
Implementation was completed and reverted from #39891 due to interaction with test failures and PR-size cap. The reverted commits (`cb377c5d1a`, `1ab4d0c200`, `adcd251a72`, `439c53e32a`, `0283231219`) can be cherry-picked from the prior branch state as a starting point.
Contributor guide
Research direction
Start by reading the existing wrapper infrastructure from dependency #39891 and the reverted commits, then inspect the listed provider-stream, metametrics-controller, and app-state-controller call sites. Add unit tests for the new helper and verify the three entry points, kill switch, trace naming, and relevant lint, unit, and e2e checks against the acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- observability
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100