Capture one structured evidence envelope at each failed checkout boundary, then correlate those envelopes with a request ID and deployment identity. The deciding constraint is signal quality: a useful incident record must preserve the stack, safe request context, release, and environment without turning authorization headers, cookies, or one-time codes into permanent logs.
TL;DR: instrument Route Handlers and Server Actions at their outer error boundaries; normalize thrown values into real errors; allowlist a small set of headers; attach stable operation and release fields; record the exception once; and rethrow it so framework behavior remains intact. Metrics can show that checkout failures increased, but the envelope supplies the evidence needed to reconstruct which operation failed and under which deployment.
This is an architecture decision record for an e-commerce backend. Its invariant is simple: the same failure gets one primary exception event, even when it crosses several layers. Its privacy boundary is stricter: secrets, payment data, message bodies, email addresses, phone numbers, and OTP values never enter the envelope. That boundary matters because the most convenient debugging payload is often the worst compliance record.
What Evidence Actually Reconstructs a Customer Incident?
A customer report usually starts with a thin statement: checkout failed, the confirmation message did not arrive, or the page asked for another verification code. A stack trace alone answers where execution stopped. It does not answer which deployment ran, which logical operation was underway, or whether the incoming request carried the correlation identifier seen by another service.
The minimum useful envelope has five parts:
- a generated or validated request ID;
- a stable operation name such as
checkout.submitorotp.verify; - the exception type, message, stack, and causal chain;
- an explicit release and environment supplied by deployment configuration;
- narrowly allowlisted HTTP context, plus low-cardinality business state such as payment phase or delivery channel.
Keep customer identity out of the grouping key. Two failures caused by the same code path should remain comparable even when different shoppers trigger them. Conversely, do not group every Error message together: dynamic order IDs and provider response text can split one defect into thousands of apparent issues. A stable operation plus exception class and the top application frame is a reasonable starting fingerprint. Sentry's grouping documentation describes the same underlying concern: stack traces, exception details, and fingerprints influence how events become issues.
There is a second invariant: configuration must fail closed. If APP_RELEASE is absent, report unknown; do not infer a release from a mutable hostname. If an environment value is absent, use a bounded label such as unknown, not an arbitrary process dump. This makes a missing deployment field visible without manufacturing provenance.
Decision: One Envelope at the Outermost Owned Boundary
The capture point should be the outermost boundary your application owns. For a Route Handler, that is the exported HTTP method. For a Server Action, it is the exported action called by the UI. Domain functions should add typed context or an error cause, but they should not independently emit the same exception. Otherwise a single declined checkout can appear as three incidents: repository, service, and transport.
This is the trade-off record:
| Option | Signal quality | Noise and risk | Decision |
|---|---|---|---|
Capture at every catch
|
Rich local context | Duplicate events, inconsistent redaction, distorted counts | Rejected |
| Capture only in a global process handler | Last-resort visibility | Request context may be gone; recovery semantics are unclear | Reserve for uncaught failures |
| Capture once at each exported application boundary | Request-aware evidence with clear ownership | Requires a small wrapper and disciplined rethrowing | Chosen |
| Log complete requests for later search | Maximum raw context | Secret and personal-data exposure; expensive, noisy retention | Rejected |
The chosen boundary does not replace metrics. OpenTelemetry defines a metric event as a measurement captured at runtime and describes counters and histograms as metric instruments. Use a counter for failed operations and, where latency matters, a histogram for duration. Keep labels bounded: route pattern, operation, outcome, and environment are candidates; request IDs, order IDs, emails, and raw error messages are not. The event envelope can carry the unique request ID because it is searched as evidence, not aggregated as a metric dimension.
Quiet data wins.
During an OTP delivery gap, repeated lines saying that polling succeeded will obscure the one transition that matters: the send operation failed after an accepted checkout. Record state changes and terminal failures, not every loop iteration.
How Should Next.js API Routes and Server Actions Capture Errors?
The framework-facing wrapper belongs in the application runtime, but the policy is easier to inspect as a small, dependency-free Python reference. The same sequence applies in a Node.js handler: derive safe context, execute the operation, capture an exception envelope, then rethrow. This example deliberately omits transport to any backend; emit_exception is a generic interface.
from __future__ import annotations
import os
import traceback
import uuid
from collections.abc import Callable, Mapping
from typing import Any, TypeVar
T = TypeVar("T")
SAFE_HEADERS = {
"accept",
"content-type",
"traceparent",
"user-agent",
"x-request-id",
}
def safe_headers(headers: Mapping[str, str]) -> dict[str, str]:
return {
name.lower(): value[:512]
for name, value in headers.items()
if name.lower() in SAFE_HEADERS
}
def normalize_exception(thrown: BaseException | object) -> BaseException:
if isinstance(thrown, BaseException):
return thrown
return RuntimeError(f"Non-exception value thrown: {type(thrown).__name__}")
def capture_boundary(
*,
operation: str,
request_headers: Mapping[str, str],
run: Callable[[], T],
emit_exception: Callable[[dict[str, Any]], None],
) -> T:
incoming_id = request_headers.get("x-request-id", "")
request_id = incoming_id[:128] if incoming_id else str(uuid.uuid4())
try:
return run()
except BaseException as thrown:
error = normalize_exception(thrown)
envelope = {
"operation": operation,
"request_id": request_id,
"release": os.getenv("APP_RELEASE", "unknown"),
"environment": os.getenv("APP_ENV", "unknown"),
"exception": {
"type": type(error).__name__,
"message": str(error),
"stack": "".join(
traceback.format_exception(type(error), error, error.__traceback__)
),
},
"request": {"headers": safe_headers(request_headers)},
}
emit_exception(envelope)
raise
Three details are doing more work than they first appear. The header policy is an allowlist, so a newly introduced credential header is excluded by default. Values are bounded to prevent an attacker-controlled header from inflating an event. Finally, bare raise preserves the original exception and traceback; replacing it with a new generic failure would destroy the causal evidence the envelope was built to retain. I choose this asymmetry deliberately: losing an unapproved diagnostic header is recoverable, while retaining a bearer token or session cookie creates a second incident. The initial five-header set is small enough to review field by field, and any addition has to justify its diagnostic value, retention period, and reader population before deployment.
In the actual Route Handler, return expected domain outcomes as deliberate HTTP responses before the exception boundary. A rejected coupon or declined payment is not automatically a software fault. Unexpected exceptions pass through the capture wrapper and are rethrown, allowing the framework's normal error response behavior to continue. In a Server Action, model validation results as data the caller can render; reserve thrown exceptions for failures that should enter error handling.
Do not copy all request headers and redact afterward. Header names evolve, proxies add fields, and cookies can contain several credentials in one string. The five-name allowlist above is illustrative rather than universal: even user-agent may be unnecessary for a server-only defect, while traceparent is useful when the deployment participates in W3C Trace Context. Review each admitted field against retention and access policies.
How Do We Know the Envelope Is Trustworthy?
Test the evidence policy as production code. A unit test should send mixed-case header names and verify that authorization, cookie, set-cookie, and an invented x-otp field are absent. Another should throw a real exception and assert that the captured stack contains the failing function, the configured release survives unchanged, and the original exception is rethrown. Add a non-Error case because JavaScript permits throwing arbitrary values, even though application code should throw Error objects.
Then run one deployment-level smoke test using a synthetic checkout that cannot affect inventory or payment. Give it a known request ID, trigger a controlled internal failure, and verify exactly one event with the expected environment and release. Do not assert on a vendor-generated event identifier; assert on the fields the application owns.
Release values need immutability. A commit SHA or immutable build identifier supplied by CI works because every running instance of the same artifact reports the same value. Environment should describe the deployment class, such as production or staging, rather than a host name. These fields answer two different questions: what code was running, and where was it running?
Operational review closes the loop. Sample several recent envelopes and ask whether an on-call engineer could reconstruct the transition without opening raw customer data. Check for accidental high-cardinality metric labels. Exercise retention deletion and access control, not merely ingestion. OWASP's logging guidance recommends excluding or masking data such as access tokens, authentication passwords, sensitive personal data, and payment cardholder data; the envelope policy should encode that rule before deployment.
One hard rule: OTP values never belong in telemetry.
Delivery channel and a coarse outcome can be useful. The code itself cannot.
Rejected Option and Its Narrow Valid Use
Capturing errors only through a global process-level handler was rejected for request-path diagnosis. By the time an uncaught exception or unhandled rejection reaches that boundary, operation metadata may be unavailable, and continuing after an unknown process state can be unsafe. It is a backstop, not the primary capture path.
The global handler still has a valid use: record a minimal last-resort event for failures outside a request or action boundary, then follow the runtime's established termination policy. Background startup work and scheduler failures can land there when no narrower owner exists. Mark these events with a distinct operation, avoid pretending they have request headers, and never count a globally captured copy again if the application boundary already emitted it.
Full request logging also has a narrow use in isolated, synthetic test environments with generated data and short retention. It should not quietly become the production incident strategy. The evidence envelope is intentionally smaller because an e-commerce incident record must remain useful after security, privacy, and on-call noise are treated as engineering constraints rather than cleanup tasks.
References
- https://opentelemetry.io/docs/concepts/signals/metrics/
- https://docs.sentry.io/concepts/data-management/event-grouping/
- https://www.w3.org/TR/trace-context/
- https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
- https://nextjs.org/docs/app/getting-started/route-handlers-and-middleware
- https://nextjs.org/docs/app/getting-started/updating-data
Top comments (0)