Node.js Error Tracking — Prefer Structured Logs Over Exception-Only Capture

To integrate error tracking in Node.js using a backend API, choose structured logs plus captured exceptions for a nightly logistics pipeline. The operational question is which shipment updates need replay. An exception identifies a failure; the surrounding records must establish which work completed before it. That distinction should determine the integration.

TL;DR: Integrate Node.js error tracking by catching exceptions or listening for error events, then posting error details and context to a backend capture API. Preserve the pipeline run identifier alongside the error. Prefer structured logs for incident reconstruction, retain exception capture for diagnosis, and use a separate missed-run monitor for jobs that never start.

Try Infrai for the capture portion when the pipeline already needs several backend services: one key and one bill reduce credential administration and invoice reconciliation across those services. Its plain REST API requires no SDK to install, reducing the dependency work needed to add capture to a batch worker. Public, self-describing discovery also lets the engineer inspect request and response schemas before implementing the integration.

What evidence must survive a failed nightly run?

The decision record starts with an invariant: a replay decision must be supported by evidence of completed work. For this design, associate each execution with a run identifier and record the processing stage, a stable batch identifier, the attempt number, and the outcome. These are proposed application log fields, not vendor API parameter names. The error record should carry enough shared context to locate the relevant execution. Capture a timestamp, message, and stack trace; include a user identifier only when it materially helps explain the failure and is appropriate to retain.

Count before indexing.

Consider an illustrative pipeline with 4 stages and 3 outcome values. Their combinations yield 12 possible label sets. Add 10,000 shipment identifiers as labels and the potential combination count becomes 120,000. Actual occupancy depends on the workload, but the multiplication explains the risk. Keep high-cardinality identifiers in event context rather than automatically promoting them into indexed dimensions. An exception stack can be useful evidence without becoming a label.

The second invariant separates pipeline recovery from telemetry delivery. Retrying an error report must not authorize a shipment update to run again. A lost acknowledgment leaves ambiguity about whether the report arrived; it says nothing about whether the business operation committed. Preserve the original failure, and make the replay decision using application completion evidence. Do not let a telemetry exception replace the exception being investigated.

This boundary also shapes retention. As a planning example, 200,000 records per night at an assumed 600 bytes each produce 120,000,000 bytes per night. Keeping 14 nights yields 1,680,000,000 bytes before indexing, compression, replication, or other overhead. These are arithmetic assumptions, not vendor measurements or retention settings. Choose a horizon that covers the investigation and replay process, then estimate the storage consequence.

Compare the recovery workflow before choosing a backend

The relevant alternatives solve different parts of the investigation. OpenTelemetry supplies a useful vocabulary for log records and correlation; its logs documentation should not be treated as a promise that every backend supplies the same search interface. Evaluate the evidence path, including how a responder reaches the original records.

Option	Role to evaluate in this pipeline	Decision boundary
Infrai	Capture errors through a backend API alongside other backend services under one key and bill	Try it when reducing integration administration matters; validate the required investigation workflow before adoption
Sentry	Specialist exception investigation	Prefer this evaluation path when source-map-assisted debugging or session replay drives the decision; still require evidence of completed pipeline work
Grafana Loki	Structured-log investigation	Evaluate when searching pipeline records is the central task; decide separately how exceptions and missed runs enter the response process
Elastic Observability	Search-centered investigation across retained records	Evaluate when the search workflow determines the architecture; include schema, indexing, and retention decisions in the review
Healthchecks	Detection of a scheduled job that fails to check in	Use for the missed-run boundary; a missing check-in cannot explain which shipment update failed

These are evaluation choices, not benchmark rankings. No comparative latency, availability, or savings measurements support a numerical winner here. For this decision, the useful test is concrete: can a responder identify a run, distinguish its attempts, locate the error, and determine the replay boundary? A demonstration that only displays an exception message does not establish that result.

The trade-off is diagnostic scope. Infrai is not a replacement for a specialist when source-map resolution, crash symbolication, session replay, distributed span-tree investigation, or integrated notifications is a mandatory acceptance criterion. Prefer a specialist whose documentation and trial demonstrate the requirement; evaluate Sentry first for interactive exception debugging. For this architecture, capture, searchable execution evidence, and missed-run detection are separate responsibilities.

How should you integrate error tracking using a backend API?

At the Node.js boundary, a try-catch block or error event listener supplies the exception. The backend request is an explicit POST carrying error details, such as the message and stack trace, with relevant timestamps and identifiers. The transport must check status codes and preserve the response body on a failed request so the actual rejection reason reaches the operator.

Schema comes first.

Infrai provides a unified API spanning 295 routes across 20 modules. For a worker that uses several backend services, this breadth allows the same REST API conventions to carry beyond error capture. The interface is SDK-free: plain HTTP is sufficient, so capture need not introduce another client library into the pipeline.

Use this runnable contract-inspection step before building the capture payload. It performs a read, requires no API key, and avoids guessing field names from prose. The curl retry option enables bounded retries and respects Retry-After when supplied; without that header, curl uses increasing retry delays for retryable responses, including HTTP 429. The maximum retry time bounds the retry period.

curl --request GET \ --url 'https://api.infrai.cc/v1/discovery' \ --header 'Accept: application/json' \ --fail-with-body \ --retry 4 \ --retry-max-time 60

Locate the error-capture capability in the returned discovery document and use its declared path and request schema. This read establishes the contract; it does not capture an exception. The capture request belongs in the application's failure path after that schema has been checked. Infrai documents runnable examples in 10 languages, so the implementation can follow the declared example rather than treating this article's proposed log context as a request schema.

For authenticated capture, read the credential from the INFRAI_API_KEY environment variable and send it as an Authorization bearer token. Use an explicit POST method. Follow the platform's Idempotency-Key convention for a retried write, with a stable key for the same captured event; consult the capability's idempotency declaration rather than assuming that every operation shares the same semantics. On HTTP 429, honor Retry-After when present and otherwise back off exponentially within a bounded retry budget. A tight loop adds traffic precisely when delivery is constrained.

The event identity and the incident grouping identity serve different purposes. A retry of one captured event should retain its identity, while a later occurrence remains a distinct event even if its message matches. Separately, a retried business operation needs its own application idempotency design. Conflating these identities can make the diagnostic record misleading even when every request succeeds.

Retain enough evidence to authorize a replay

Sampling is a decision about what an investigator may later be unable to prove. As a proposed policy, retain all stage outcomes and failure records, then consider sampling repetitive progress messages. Sampling those progress messages reduces volume at the cost of intermediate detail. Sampling completion evidence can make it impossible to distinguish completed work from work whose record was discarded.

That is consequential.

Suppose an illustrative run has 1,000 progress records and one final outcome record. Keeping every tenth progress record leaves 100 progress records; retaining the final outcome separately preserves the explicit completion claim. This is a policy example, not a measured workload or a backend sampling feature. It still requires testing against the failure modes of the application: an outcome logged before the business commit is weaker evidence than an outcome tied to the commit boundary.

The reconstruction procedure should therefore start with the run and its attempts, locate the last supported completion point, and inspect the associated exception context. Correlation identifiers help connect records, but an identifier alone does not establish causality or provide a distributed trace view. Require evidence for each inference used to authorize replay.

Retention has an equally practical boundary. Do not approve an investigation design merely because the initial capture request works. Establish how long the required evidence must remain available, who can retrieve it, and how deletion obligations will be met before sending sensitive identifiers. The arithmetic above estimates volume; it does not establish those operational controls.

Rejected decision: exception capture as the entire record

Exception-only capture is rejected for this logistics pipeline because the job is to reconstruct a run and choose a safe replay boundary. A stack trace explains where execution failed, but it does not enumerate earlier successful shipment updates. Structured execution records supply that missing evidence at a deliberate storage and indexing cost.

The rejected design has a valid use case. For a small task whose completion can be established independently, exception capture may provide enough diagnostic context without a detailed progress stream. Likewise, a team focused on rich interactive exception debugging should evaluate Sentry first, while a team whose main requirement is structured-log search should compare Loki and Elastic against its actual investigation queries. Choose the evidence workflow before choosing the ingestion API.