feat(sentry): define common Sentry tags and apply them at the beforeSend seams

[vbudhram]

Because

• We cannot group or filter Sentry issues by area. fxa.name is the only tag applied centrally, and nothing writes down which tags the team is supposed to use.
• One correction to the ticket: there is no critical tag in this repo. I looked. What we actually have is fxa.name in tagFxaName.ts, plus three ad-hoc tags in fxa-auth-server, deleteStage in account-delete.ts and clientId and grantType in oauth/account-activity.ts. Flagging it because the ticket is written against a version of the code that does not match what is there.

This pull request

• Adds libs/shared/sentry/src/lib/utils/tags.ts with the tag keys, a comment on each saying what it means, and an applyCommonTags helper. One place to check before you filter on a tag.
• Applies the tags at the two existing beforeSend seams, beforeSend.client.ts and beforeSend.server.ts. Both used to call tagFxaName directly.
• Exports tags.ts from the library index so callers can import the keys instead of retyping the strings.
• Extends beforeSend.client.spec.ts to cover the three tags.

Tags shipped:

Tag	Meaning
fxa.name	The FxA app or service that sent the event. Already applied; now defined in the tag module. Behaviour is unchanged.
fxa.runtime	browser or server. Which side sent the event.
fxa.known_error	True when the event carries an FxA errno, so an FxA API returned a handled error rather than an unexpected crash.

Three tags, not the five the ticket asks for. I would rather ship three I can define than five I have to hand-wave, because a vague tag turns into Sentry noise that nobody cleans up. Here is what I left out and why:

• sub-plat needs a list of the endpoints subscription platform owns. That list does not exist in the code, and a path does not tell you who owns a route. Someone on the product side has to supply it.
• external needs a signal that tells third-party errors apart from ours. I went looking in libs/shared/sentry*, fxa-settings, and fxa-content-server/app/scripts/lib for extension URL schemes, a deny list, an error class, anything. There is nothing, so implementing this would mean making up a heuristic and calling it a fact.
• email has no seam here. Email is generated and sent server side, nowhere near beforeSend, and the email sender is out of scope for this change.

Issue that this pull request solves

Closes: FXA-5685

Checklist

Put an x in the boxes that apply

• My commit is GPG signed.
• If applicable, I have modified or added tests which pass locally.
• I have added necessary documentation (if appropriate).
• I have verified that my changes render correctly in RTL (if appropriate).
• I have manually reviewed all AI generated code.

How to review (Optional)

• Key files/areas to focus on: utils/tags.ts for the tag definitions, and the two beforeSend files for where they are applied.
• Suggested review order: tags.ts, then beforeSend.client.ts, then beforeSend.server.ts, then the spec.
• Risky or complex parts: none. The change only adds tags. fxa.name keeps its previous value on both seams.

Screenshots (Optional)

Other information (Optional)

Worth knowing before you rely on the new tags: we have four separate copies of beforeSend floating around. browser.ts and node.ts in this same library, plus the sentry-utils, sentry-browser, sentry-nest and sentry-next copies, each call tagFxaName themselves. None of them get fxa.runtime or fxa.known_error yet, so coverage is partial until those seams converge. node.ts already has a @@todo to move onto utils/beforeSend.server.ts. I left that convergence for a follow-up rather than widening this change.

Verified locally: beforeSend.client.spec.ts 12 tests pass, tsc -p libs/shared/sentry/tsconfig.lib.json --noEmit is clean, and nx lint shared-sentry passes. config-builder.spec.ts has one failure on this machine, util.isError is not a function, which is the intel logger against a newer Node and predates this change.

[Copilot]

Pull request overview

Adds standardized Sentry tags for service name, runtime, and known FxA errors.

Changes:

• Introduces and exports common tag definitions and helper.
• Applies tags to Next.js client/server beforeSend paths.
• Adds client and helper tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
utils/tags.ts	Defines and applies common tags.
utils/beforeSend.server.ts	Tags server events.
utils/beforeSend.client.ts	Tags browser events.
utils/beforeSend.client.spec.ts	Tests tag behavior.
index.ts	Exports the tag API.

---

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