A guided tour
of one feature's
data flow.

The trace tree (one tRPC request)

HTTP transaction               (auto, @sentry/nextjs)
└── tRPC procedure span        (auto, sentry trpc integration)
    └── controller span         (op="controller", composed at DI bind time)
        └── use-case span       (op="use-case",  composed at DI bind time)
            └── repository span (op="repository", inline per method)
                └── Payload Local API call (auto, @sentry/node http)

Where instrumentation actually lives

Two ways spans + captures get attached. Inline means the call appears in the layer's own body. Composed-in means a higher-order wrapper applied at DI bind time — the body stays vendor-clean.

Verifiable: grep -rn "this.tracer\|this.logger" packages/*/src returns hits only in infrastructure/repositories/*.repository.ts and *.repository.mock.ts. Use case and controller bodies have zero matches. withSpan / withCapture appear only in di/bind-*.ts files.

The wrapper sandwich (one feature, in bind-production.ts)

// Repository — inline, per public method
class ArticlesRepository {
  async getArticles(input) {
    return this.tracer.startSpan(
      { name: "articles.getArticles", op: "repository", attributes: { /* ... */ } },
      async (span) => {
        try {
          const result = await /* payload op */;
          span.setAttribute("count", result.length);
          return result;
        } catch (err) {
          this.logger.captureException(err, {
            tags: { feature: "blog", repo: "articles", method: "getArticles" },
          });
          span.setStatus("error", String(err));
          throw err;
        }
      },
    );
  }
}

// Use cases + controllers — composed at bind time, body stays clean
const wrappedUC = withSpan(
  tracer, { name: "blog.getArticles", op: "use-case" },
  withCapture(
    logger, { feature: "blog", layer: "use-case", name: "blog.getArticles" },
    getArticlesUseCase(repo),
  ),
);
const wrappedCtrl = withSpan(
  tracer, { name: "blog.getArticles", op: "controller" },
  withCapture(
    logger, { feature: "blog", layer: "controller", name: "blog.getArticles" },
    getArticlesController(wrappedUC),
  ),
);

Order matters. withSpan is outermost so the errored span's timing reflects the captured-and-rethrown failure. withCapture is between span and factory so the error is captured before the span closes with error status.

Capture rules (where captureException fires)

Double-report guard

Each error gets a non-enumerable __sentryReported flag the first time it's captured. withCapture, SentryLogger, and RecordingLogger all check the flag and bail if it's set. So an error bubbling repo → use-case → controller surfaces in the logger exactly once, with the inner-most layer's tags. Helper lives in core-shared/instrumentation/reported-flag.ts.

PII rules (R31–R38, non-negotiable)

• sendDefaultPii: false — every Sentry.init(). CI grep gate.
• Replay default-masks all text + inputs + media. Allowlist starts empty.
• beforeSend scrubber strips email / password / token / cookie / authorization / ipaddress keys (substring match).
• beforeSendTransaction scrubber strips PII query params from URLs.
• setUser accepts only { id }. Stripping wrapper warns in dev when other keys passed.
• IPv4/IPv6 in event payload string values redacted to [redacted-ip].