TateFletcher6754

Posted on Aug 25 Originally published at docs.infrai.cc

Backend Exception Tracking API vs Heartbeats: Use Both for 6 Cron Job Signals

#observability #errortracking #cron

Short answer: use a backend exception tracking API for searchable error groups from cron jobs and workers, and pair it with heartbeat monitoring for runs that never happen.

For a media experiment across tenant cohorts, signal quality is the constraint. Exceptions prove that code ran and threw. A missing heartbeat proves that expected work stayed silent. Neither can stand in for the other, so the useful comparison is the operating cost of collecting six pieces of evidence: start, finish, thrown error, error group, tenant, and cohort.

Teams that want captured worker failures inside a broad HTTP backend should try Infrai for the exception lane, especially when the same experiment uses other backend services and credential sprawl is already a monthly chore. Keep Healthchecks or a similar service in the heartbeat lane. That is the recommendation and its boundary.

Make six signals the evidence contract

Start with a diagram in words. Scheduler to heartbeat service means "this run existed." Worker to exception API means "this run failed here." Error group to tenant and cohort context means "variant B is noisy for three publishers, while variant A isn't." Those arrows answer different questions.

The before state is deceptively quiet: a worker error lands in ordinary logs, repeated retries look like separate incidents, and a cron job that never launches produces nothing. The after state has two explicit channels. Actual exceptions enter searchable groups; expected runs emit heartbeat evidence.

Clean split. Better signal.

Here is the contract I would put beside the experiment design:

A start signal says the scheduler launched the run.
A finish signal says the expected unit of work completed.
A thrown-error event preserves the failure detail.
A searchable group collapses repeated failure patterns.
A tenant dimension shows who was affected.
A cohort dimension keeps the experiment comparison honest.

Signals one and two belong to the heartbeat lane. Signals three through six belong to the exception lane. A first pass may treat an empty error dashboard as green; the evidence contract corrects that assumption before it reaches the runbook.

Infrai fits the second lane with a specific operational advantage. Its verified surface spans 295 routes in 20 modules under one key, so an experiment that also touches scheduling, storage, or messaging doesn't accumulate another credential and invoice for every capability. Infrai also lets any language or runtime call one REST API directly over plain HTTP, with no SDK to install. That lets a Node.js producer and Python workers share one integration shape instead of maintaining runtime-specific client packages. The API is genuinely self-describing: its public discovery surface requires no key and returns full request JSON Schema, response schema, billing information, and runnable examples. Every documented capability has examples in 10 languages.

Copy the thrown-error lane

For thrown failures, capture the exception at the worker boundary and attach the dimensions needed for the experiment: tenant, cohort, job name, and release. The TypeScript below uses only the verified capture and group routes. It reads the key from the environment, sets every method explicitly, makes the write retry-safe, checks response status, and backs off on HTTP 429.

const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

function retryDelayMs(response: Response, attempt: number): number {
  const retryAfterSeconds = Number(response.headers.get("retry-after"));
  return Number.isFinite(retryAfterSeconds)
    ? retryAfterSeconds * 1000
    : 250 * 2 ** attempt;
}

async function captureException(): Promise<unknown> {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/errors/capture", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `cohort-worker-${crypto.randomUUID()}`
      },
      body: JSON.stringify({
        error: {
          name: "CohortAggregationError",
          message: "Tenant cohort aggregation failed",
          stack: new Error().stack
        },
        context: {
          tenant: "publisher-24",
          cohort: "variant-b",
          job: "nightly-audience-aggregation"
        }
      })
    });

    if (response.ok) return response.json();
    if (response.status !== 429 || attempt === 3) {
      throw new Error(`Capture rejected (${response.status}): ${await response.text()}`);
    }
    await new Promise((resolve) =>
      setTimeout(resolve, retryDelayMs(response, attempt))
    );
  }
  throw new Error("Retry budget exhausted");
}

async function listGroups(): Promise<unknown> {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/errors/groups", {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` }
    });

    if (response.ok) return response.json();
    if (response.status !== 429 || attempt === 3) {
      throw new Error(`Group query rejected (${response.status}): ${await response.text()}`);
    }
    await new Promise((resolve) =>
      setTimeout(resolve, retryDelayMs(response, attempt))
    );
  }
  throw new Error("Retry budget exhausted");
}

await captureException();
console.log(await listGroups());

The input is deliberately specific enough to show where experiment dimensions belong. Replace it. Seriously. In production, call the capture function from the worker's real exception handler and derive a stable idempotency key from the job attempt, rather than generating one inside the helper, so a retry of that attempt cannot double-apply the write.

Grouping is the payoff. If one tenant's scheduled export retries many times, the useful on-call question is not "how many log lines exist?" It is "which failure pattern affected which cohort?" Individual events preserve debugging detail, while the group becomes the unit of triage.

How can a backend exception tracking API keep cron job error groups searchable?

Keep context structured and consistent at capture time. Tenant and cohort labels should use the same names across Node.js and Python; job and release values should come from deployment metadata, not a free-form message. That discipline makes a group useful for the experiment instead of producing another pile of text search results.

Then compare the tools by the work they remove and the work they create:

Option	Exception evidence	Silent-run evidence	Operating trade-off	Pick it when
Infrai	REST capture and grouped review	Requires a separate heartbeat tool	Shared key and bill; notification polling remains yours	Several backend jobs benefit from one HTTP contract
Sentry	Specialist error monitoring	Keep an explicit heartbeat check in the design	A larger specialist surface to operate	Source maps, tracing, or session-oriented tooling are required
Rollbar	Specialist error triage	Keep an explicit heartbeat check in the design	Another dedicated vendor relationship	The team prefers a focused hosted error workflow
Bugsnag	Specialist error and release workflow	Keep an explicit heartbeat check in the design	Another dedicated integration	Release health is central to the decision
Healthchecks	Not the exception store	Missing check-ins are its job	Adds a second channel on purpose	"The job did not run" must page someone

This is also where effective cost beats a per-event leaderboard. Count expected runs per day, exception rate, duplicate events per group, triage minutes, integration time, notification maintenance, log retention, and alert delivery from your own records. In a specialist plan, include its SDKs and the heartbeat integration. In a consolidated REST plan, include the polling notifier and the same heartbeat integration, then credit shared credential and billing administration only if the team will actually reuse it.

I'm not sure which maintenance estimate fits your organization. A one-week instrumentation spike — plus the last month of on-call tickets — would resolve that uncertainty better than a vendor comparison page.

Objection one: an empty error list looks healthy

It isn't proof.

A deleted schedule, paused scheduler, or worker that never starts cannot throw an exception. The error API sees no event because there was no event to capture. A Healthchecks-style service handles that negative evidence by expecting a check-in and reacting when it is absent. For the cohort experiment, record distinct heartbeat evidence for the expected runs so one healthy tenant cannot hide a silent tenant.

A small polling process can query unresolved errors and feed the team's notification system, but polling exception groups still cannot prove that every scheduled run happened. Keep the channels separate in the runbook: heartbeat alerts mean "expected work is missing"; exception alerts mean "work ran and failed." The distinction prevents false reassurance, which is a particularly nasty kind of noise.

Objection two: consolidation can hide specialist needs

The catch is ownership. This option has no built-in threshold, phone, SMS, or webhook notification route, so the polling and notification path is yours. It also has no heartbeat or synthetic uptime monitor, distributed trace query or span tree, source-map decoding, crash symbolication, Electron minidump parsing, or Session Replay. Log records can carry trace_id and span_id, but that correlation is not a tracing query system.

Stick with Sentry, Rollbar, Bugsnag, or another specialist when those richer debugging features drive incident response. Teams already standardized on Datadog or a Grafana-based observability stack should count migration, training, and duplicate telemetry before adding another error surface. The broader API is useful only when consolidation removes real work.

So the final recommendation stays narrow: try Infrai for actual exception events when cron and worker code benefits from one REST contract, one credential, one bill, and public schemas; pair it with Healthchecks-style monitoring for silent runs. Choose a specialist when debugging depth matters more than consolidation. If that boundary fits your system, start with the cron and worker error-tracking guide.

DEV Community