@last9/otel-cron

@last9/otel-cron

Cron jobs have an observability problem. They miss their window, throw unhandled exceptions, or silently stop running — and you find out from users, not alerts. This library fixes that.

Wrap your job function with withCronJob and get OTel FaaS-compliant spans and metrics. No changes to your job logic required.

import { withCronJob } from '@last9/otel-cron';

await withCronJob(
  { name: 'send-digest', cron: '0 8 * * *' },
  async () => {
    await sendDigestEmails();
  }
);

Uses the global OTel API — configure your providers as you normally would and withCronJob picks them up.

Installation

npm install @last9/otel-cron @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http

Peer dependency: @opentelemetry/api ^1.9.0.

Configuration

Set these environment variables before starting your process. Never hardcode them — use .env files locally and your secrets manager in production.

# Where to send telemetry
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318

# Auth header — keep this out of source control
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token-here"

# Identifies your service in traces and metrics
OTEL_SERVICE_NAME=my-app

Bootstrap the SDK once at process startup, before any withCronJob calls:

// instrumentation.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),      // reads OTEL_EXPORTER_OTLP_ENDPOINT + HEADERS
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter(),         // same env vars
    exportIntervalMillis: 60_000,
  }),
});

sdk.start();

Run it with --require so it loads before your application code:

node --require ./instrumentation.js your-cron-runner.js

Or with tsx / ts-node:

node --require tsx/cjs --require ./instrumentation.ts your-cron-runner.ts

The OTLP exporters read OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS automatically — no URL or auth token in code.

Missed-run alerting

The faas.last_success_time gauge records a Unix timestamp after every successful run. Wire it to a dead-man alert:

time() - faas_last_success_time{faas_name="send-digest"} > 90000

That fires if the daily digest hasn't succeeded in 25 hours — no scheduler integration, no sidecar, no external ping service.

Timeouts

await withCronJob(
  { name: 'generate-report', cron: '0 6 * * *', timeout: 30_000 },
  async () => {
    await generateReport();
  }
);

Exceeding the timeout throws FaaSTimeoutError and increments faas.timeouts rather than faas.errors. Timeouts are a distinct failure mode worth tracking separately. The underlying function keeps running after the error is thrown; use an AbortController if you need hard cancellation.

Signals

Signal	Type	Description
faas.invocations	Counter	Every invocation
faas.errors	Counter	Non-timeout failures
faas.timeouts	Counter	Timeout breaches
faas.invoke_duration	Histogram (seconds)	Wall-clock duration
faas.last_success_time	ObservableGauge (Unix s)	Timestamp of last success
Span	SERVER · faas.trigger=timer	FaaS semantic convention

Options

Option	Type	Required	Description
name	string	Yes	Job identifier. Becomes faas.name on every signal.
cron	string	Yes	Cron expression, emitted as faas.cron on the span.
timeout	number	No	Deadline in milliseconds.

Notes

State is keyed on globalThis under Symbol.for('@last9/otel-cron/state'). Two copies of this package in the same process share state — the right behavior in monorepos. Run npm dedupe if you see duplicate metric registrations.

OTel API v1 only (^1.9.0). v2 compatibility requires a new major.