Short answer: For an Express error-tracking middleware setup, put one error boundary after the checkout routes, emit one redacted structured error event per failure, and classify it before alerting; that gives logistics teams better signal quality than logging every request body.
Start small.
No payload dump.
The least complex useful design is a request-boundary middleware that emits one structured failure event, preserves the original error, and lets downstream analysis decide what deserves an alert. For a logistics checkout workflow, that signal should include the operation, a correlation identifier, the failure class, and safe context such as carrier and route region. It should not copy a full request body into every record. The decision is deliberately narrow: the boundary records what happened, while a later policy decides whether the event is visible, grouped, or routed to a person. That boundary is where the setup earns its keep: it sees the request context while it is still available, yet it can enforce the same redaction and naming rules for every route. A downstream dashboard cannot repair an event that was emitted without an owner, a correlation ID, or a stable error class.
That trade-off matters because checkout failures are operationally expensive in two different ways: a missed failure can strand an order, while noisy telemetry can hide the few events that need an engineer. I start with a small event contract, test it against known failure cases, and only then connect it to a log or trace exporter.
What should error-tracking middleware capture?
Capture facts that help answer three questions: which operation failed, where did it fail, and can the team act on it? A useful event has a stable event name, a severity, a timestamp, a correlation ID, an HTTP status, and a normalized error type. Add bounded business context: shipment mode, fulfillment region, or a carrier class. Avoid credentials, payment details, complete addresses, and unbounded exception text.
The distinction between an error event and a request log is important. A request log describes traffic. An error event describes an outcome that needs classification. OpenTelemetry treats logs as a signal that can carry timestamped records and contextual attributes; that makes the event contract portable even when the storage or visualization layer changes.
Here is a compact Python model for the boundary logic. It is intentionally framework-neutral: the same sequence can be implemented as Express middleware, ASGI middleware, or a queue consumer wrapper. The important behavior is ordering, redaction, and one-event ownership.
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any, Callable
@dataclass
class Request:
method: str
path: str
correlation_id: str
context: dict[str, str]
class ErrorEventSink:
def emit(self, event: dict[str, Any]) -> None:
raise NotImplementedError
SENSITIVE_KEYS = {"authorization", "card_number", "address", "token"}
def safe_context(values: dict[str, str]) -> dict[str, str]:
return {
key: value[:80]
for key, value in values.items()
if key not in SENSITIVE_KEYS
}
def error_boundary(
request: Request,
handler: Callable[[Request], Any],
sink: ErrorEventSink,
) -> Any:
try:
return handler(request)
except Exception as error:
sink.emit({
"name": "checkout.failure",
"timestamp": datetime.now(timezone.utc).isoformat(),
"correlation_id": request.correlation_id,
"method": request.method,
"path": request.path,
"error_type": type(error).__name__,
"context": safe_context(request.context),
})
raise
In an Express implementation, place the equivalent error-handling function after the checkout routes so it receives propagated failures. Keep the response decision separate from event creation. The middleware can record and rethrow or delegate to the framework's final error handler; it should not turn an unknown failure into a successful checkout. A second boundary around asynchronous work is necessary when that work can reject outside the synchronous route call.
How do you keep signal quality higher than noise?
Classify before alerting. A malformed address, a rejected carrier quote, a payment refusal, and a dependency timeout may all reach the same error boundary, but they do not have the same owner or urgency. Store a normalized class and a retryability flag. Alert on an actionable class and a meaningful rate, not on every stack trace.
I initially treated every 5xx response as a production incident. That produced a tidy chart and a poor queue for humans. The better rule is to separate customer impact from system cause: a predictable business rejection may be visible in a dashboard, while a sudden increase in timeouts deserves an alert and a trace link. In an eval harness, I would assert these outcomes separately because a test that checks only the status code misses the operational contract: who owns the event, whether a retry is safe, and whether the customer-facing response stays honest. This is a choice about signal quality, not a feature of a particular product.
| Failure class | Useful action | Why it should not share one alert rule |
|---|---|---|
| Address validation | Record and return a corrective response | The customer can usually fix it |
| Carrier timeout | Count, trace, and watch the rate | Retryability and dependency health matter |
| Unknown exception | Escalate with correlation context | The cause and impact are uncertain |
Deduplication also needs a deliberate key. Use the operation, normalized error class, and dependency boundary rather than the raw message. Raw messages often contain IDs or changing text, so they create one group per order and make a repeated failure look like many failures. Preserve the original exception for debugging, but aggregate on stable fields.
Where does the data flow after the boundary?
The request enters the checkout route, the route either completes or propagates an error, and the boundary creates one event with the correlation ID. A log or telemetry pipeline then enriches that event with service and deployment metadata. A trace can connect the checkout request to a carrier or inventory call, while the error event remains the concise record used for counting and routing.
This separation keeps the middleware small. It also makes tests clearer: given a handler failure, assert one emitted event, a preserved correlation ID, redacted sensitive values, and the original failure reaching the response layer. Given a normal response, assert zero error events. Test rejected promises as well as synchronous exceptions.
Do not use the middleware as a dumping ground for payloads. The event should have bounded field lengths and an explicit allowlist for context. Sampling can reduce repetitive diagnostic volume, but sample rates should not erase rare checkout failures; keep a complete count or durable metric for the classes that drive customer impact.
A practical rollout checklist
Start with five or six representative failures: an invalid delivery address, a carrier timeout, an unavailable inventory reservation, a payment refusal, a malformed internal response, and an unknown exception. For each one, write down the expected class, owner, retryability, customer response, and alert behavior. That small matrix becomes the eval harness for the middleware.
Run it in a test environment with deliberately noisy input. Verify that correlation IDs survive each hop, sensitive keys never appear, and repeated failures group under a stable fingerprint. Then inspect the exported records as a reader would: can someone identify the affected workflow without opening a raw request?
Before production, define retention, access controls, and a failure policy for the telemetry sink itself. Checkout should not depend on the error tracker accepting a record. If emission is unavailable, preserve the request's normal error path and use a bounded local fallback appropriate to the runtime. Finally, review the event contract when the workflow changes; stale context is quieter than an exception, but it still damages diagnosis.
The implementation is successful when an engineer can find the failing checkout path, distinguish a customer rejection from a system fault, and estimate impact without reading every request. That is the durable target: a small, portable event contract with enough context to act and enough restraint to stay trustworthy.
Further reading
- OpenTelemetry, “Logs signal concepts”: https://opentelemetry.io/docs/concepts/signals/logs/
Top comments (0)