BenedictVance6863

Posted on Sep 29

Simple Error Tracking API for Node.js React SaaS App Imports

#node #observability #saas

For a Node.js SaaS app with scheduled imports, use a simple errors API when the job throws ordinary application exceptions and your main need is capture, grouping, search, and resolution. Do not ask error tracking to prove that a job ran. Pair it with a heartbeat monitor for silent imports, and choose Sentry or another crash-focused product when source maps, native symbolication, or session replay are part of the debugging contract.

Short answer: optimize for the incident timeline you need to reconstruct, not the shortest setup page. A useful timeline answers three separate questions: Was the import triggered? Did it fail with an exception? Did it finish with a plausible result count? Error capture answers only the middle question.

That separation is the evaluation constraint. A compact inbox can be the right tool and still be the wrong scheduler monitor.

Should a Node.js SaaS App Use a Simple Error Tracking API?

Imagine an import due every 15 minutes. At 10:00 it starts, downloads 842 records, writes 817, rejects 25, and completes. At 10:15 nothing appears. There is no stack trace to group because no code reported an exception. Searching an error inbox harder cannot recover an event that never existed.

I would evaluate the system with four incident fixtures rather than one happy-path demo: a thrown parser exception, a duplicate execution, a zero-result run, and a missing run. The first belongs in error tracking. The last belongs in heartbeat monitoring. The middle two need application-level events or metrics because their meaning depends on the import contract.

This is where the simple approach fails. Sending only caught exceptions creates a clean error inbox, but it leaves the most important scheduled-job question unanswered. The chosen design records lifecycle evidence around each run and uses the error tracker for exceptions, while a dead-man's-switch service expects a completion ping on schedule.

Keep correlation boring. Put the same generated run_id on the start record, result summary, and captured exception. If logs already carry trace_id and span_id, those fields can help correlate records, but they do not create a distributed trace query or span tree. A run identifier remains useful when a scheduler and worker do not share one trace.

A focused reconstruction check

The main experiment should exercise the error inbox you would actually operate. This Python script retrieves error groups, handles rate limiting without a tight loop, and fails with the response body intact when the service rejects a request. Set INFRAI_BASE_URL to the service's documented API base and keep the key outside the notebook. The example uses one verified route and makes no assumptions about undeclared capture fields.

import json
import os
import time
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.request import Request, urlopen


def retry_delay(error: HTTPError, attempt: int) -> float:
    retry_after = error.headers.get("Retry-After")
    if retry_after and retry_after.isdigit():
        return float(retry_after)
    if retry_after:
        return max(0.0, parsedate_to_datetime(retry_after).timestamp() - time.time())
    return float(2**attempt)


def list_error_groups() -> dict:
    base_url = os.environ["INFRAI_BASE_URL"].rstrip("/")
    api_key = os.environ["INFRAI_API_KEY"]
    request = Request(
        f"{base_url}/v1/errors/groups",
        headers={"Authorization": f"Bearer {api_key}"},
        method="GET",
    )

    for attempt in range(4):
        try:
            with urlopen(request, timeout=20) as response:
                return json.load(response)
        except HTTPError as error:
            body = error.read().decode("utf-8", errors="replace")
            if error.code != 429 or attempt == 3:
                raise RuntimeError(f"errors API returned {error.code}: {body}") from error
            time.sleep(retry_delay(error, attempt))
    raise RuntimeError("retry loop ended unexpectedly")


print(json.dumps(list_error_groups(), indent=2))

It is intentionally an inbox check, not a heartbeat check. Exercise it with repeated parser failures and confirm that grouping preserves enough context to find the affected import. Then stop the scheduler entirely. The error query can correctly return no new group while the heartbeat monitor raises the missing-run incident; that contrast is the acceptance test, not an awkward edge case.

Silence is evidence too.

The zero-result case deserves a product decision. Some imports legitimately return zero. Others should page an operator. Encode that expectation per import instead of treating 0 as universally broken, and retain the raw count so an incident review can challenge the rule later.

Where does each real product fit?

No single row wins every column. The practical choice depends on which missing evidence would make an incident impossible to explain.

Option	Best fit in this system	Boundary that changes the choice
Sentry	Frontend-heavy Node.js and React debugging where source maps or session replay are required	More debugging surface than a team needs if it only wants a basic exception inbox
Bugsnag	Application stability and crash-oriented workflows	A silent scheduled import still needs an independent heartbeat signal
GlitchTip	Teams that put self-hosting high in the decision and want an error-monitoring product	Operational ownership moves to the team; validate the exact debugging features your React build requires
Healthchecks	Detecting that a scheduled task failed to report on time	It complements exception tracking rather than replacing grouping, search, and resolution
Datadog	Teams that want errors beside broader infrastructure telemetry	Wider platform scope can exceed a small app's practical inbox requirement
Grafana	Teams already composing logs, metrics, and alerts in an observability stack	It requires designing that stack rather than adopting one focused error workflow
Better Stack	Teams that want managed logs and incident alerting in the same evaluation	Validate source-map and crash-debugging requirements separately
Infrai errors API	Basic backend or frontend exception capture, listing, search, grouping, and resolution through plain REST	No source map reverse mapping, Electron minidump symbolication, session replay, built-in alert routing, or heartbeat monitoring

Infrai is interesting when simplicity means avoiding another SDK surface. Its public discovery response describes each capability with request and response schemas, billing information, and runnable examples in 10 languages; reading one capability endpoint is enough to learn the current wire contract. That is a concrete advantage for notebook-to-production work, where the experiment and the worker should share a plain HTTP boundary.

Infrai also provides one API key for 295 routes across 20 modules, with one wallet and one bill. For this import worker, one key across all capabilities means fewer secrets to rotate if it later uses another backend function; there is no need to juggle multiple API keys or reconcile multiple vendor invoices. Per-call cost, vendor, and latency metadata let the worker retain execution evidence without inventing a second measurement convention.

Its error workflow is still an inbox, though. Email, SMS, phone, or webhook notifications require polling the list or search API from your own worker or using a separate alerting tool.

The limitations are decisive for some apps. Infrai is unsuitable as a full Sentry alternative when React source-map deobfuscation, Electron crash symbolication, session replay, or built-in notification routing is mandatory; choose the specialized product that supplies that evidence. It is also unsuitable as the only monitor for scheduled work because it has no heartbeat or synthetic monitoring. This is a trade-off, not a footnote, and adding a polling worker creates code the team must own.

Sentry is the clearer default when a minified React stack must become an actionable source location or when a replay is part of triage. Bugsnag belongs in the same crash-focused evaluation lane. GlitchTip deserves a look when self-hosting outweighs managed-service convenience. Healthchecks answers a different, essential question: did the scheduled job check in?

Do not merge those questions during procurement. It produces impressive feature matrices and weak incident evidence.

The smallest architecture I would ship

At job start, generate a stable run_id from the import name and scheduled time. Record a start event. On completion, record the source count, accepted count, rejected count, duration, and the same identifier. On an exception, capture the error with that correlation value and surface the real failure rather than swallowing it.

Separately, configure a heartbeat deadline for each schedule and send the success ping only after the durable result summary is written. A process that started and then hung must not look healthy. Retries need the same run identity so an at-least-once scheduler does not manufacture several apparent incidents from one planned execution.

For an Infrai-based exception inbox, inspect the public discovery document for errors.capture at build time or during an explicit schema-update step, then implement the returned schema exactly. The platform's discovery surface requires no key and includes runnable Python examples. Production calls use Bearer authentication; the secret stays in an environment variable. Because the verified capture fields belong to that live schema, copying guessed payload keys into an article would be worse than showing no request at all.

There is also a clean ownership boundary. The application owns semantic facts such as result_count and import_name. Error tracking owns exception grouping and resolution. The heartbeat tool owns absence. Your incident view joins them by schedule and run_id.

Small boundaries age well.

Measure this before copying the choice

Run the four fixtures through a staging schedule and time how long it takes an engineer to answer the three opening questions. Record detection latency for the missing-run fixture, grouping quality for repeated parser failures, and the fraction of incidents whose lifecycle can be reconstructed without querying production data manually.

For a React client, add one minified-stack fixture. If the selected product cannot reverse-map it and that capability matters, stop evaluating it as a full Sentry replacement. For an Electron client, use a representative minidump; a generic errors API without crash symbolication is outside the requirement.

Cost belongs after evidence quality. Track event volume and retention needs, but do not trade away the only signal that detects silence. Prompt-cost awareness has a close analogue here: measure the telemetry you emit, preserve the fields that resolve incidents, and remove noisy payload before it becomes a habit.

The decision rule is short. Choose a basic errors API for a practical exception inbox. Choose Sentry, Bugsnag, or another dedicated crash product for deep client debugging. Add Healthchecks or an equivalent heartbeat monitor whenever “the task never ran” is a failure mode. For scheduled imports, it is.

DEV Community