MetaMask / MetaMask/metamask-extension

[P2] Sentry distributed tracing — wrap background entry points

Open
#42,268 0 comments 0 reactions 0 assignees View on GitHub
INVALID-ISSUE-TEMPLATE
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.