When to use this pattern
Use this pattern when a user reports a failed or slow interaction and aggregate service metrics do not identify the affected request.
Investigation flow
- Locate the relevant session, view, action, and network resource event rather than treating the entire session as one request.
- Select the backend request associated with that action and follow its recorded trace reference.
- Check that frontend trace headers are sent only to intended API destinations and survive gateways and server extraction. For cross-origin requests, confirm the required CORS behavior.
- Compare frontend timing with recorded server and dependency activity, then inspect matching backend logs to test the failure explanation.
Required fields
| Field or dimension | Purpose |
|---|---|
| session, view, and action identifiers | Locate the user interaction within the browser telemetry product. |
| network resource event and trace reference | Associate one API call with a backend request, rather than joining all session activity. |
| service, environment, and API destination | Keep the connection scoped to the intended backend. |
| compatible propagated trace context | Relate browser and server observations when the SDKs and intermediaries support it. |
Worked example: A payment click leads to one failed API request
A browser session records a payment click followed by a POST to the checkout API that returns an error. The linked backend trace locates a failing payment-provider call, and matching server logs supply its error details. Other requests from the same session may have different trace IDs. If the browser failed before sending the API call, there would be no backend request to follow.
| Evidence | Observation |
|---|---|
| Session | A specific payment action and its API resource event are selected. |
| Backend | The resource trace reference opens the matching checkout operation. |
| Boundary check | Compare browser-side delays, server spans, and provider evidence without equating their durations. |
Limitations and false matches
- A user session spans many actions and requests; it is not represented by a single trace ID.
- Frontend and backend sampling or retention can remove one side of the connection.
- Cross-origin preflight failures, stripped headers, or mismatched propagators can break the association.
- JavaScript failures before a request and browser-side rendering delays may have no corresponding server span. Session replay is not required for trace correlation.
Verification checklist
- Use a test interaction that sends a known API request and confirm the resource event opens its backend trace.
- Inspect the configured tracing destinations and verify compatibility across the browser SDK, gateway, and server.
- Test a browser-only failure separately to confirm it is not mistaken for a missing backend trace.
Supported by
Documented examples, not an exhaustive compatibility list. Features require suitable instrumentation and configuration; availability can depend on the runtime, backend, and subscription.
- Datadog RUM and APM — Configured browser request tracing links selected RUM resource events with backend APM traces; header propagation, allowed destinations, CORS, and sampling affect coverage.
Related signals
Related concepts
Related patterns
Related guides
FAQ
Do I need to send a user identity through every service?
No. A request trace can provide the association. A product-specific session or user identifier is a separate concern and should not be confused with trace context.