@runsignal/node 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,30 @@
 # RunSignal for Node.js
 
-Monitor Node.js background work that no HTTP status code describes, such as BullMQ queues, job schedulers and
-sync loops, with OpenTelemetry. It emits the same signals and manifest as every other RunSignal SDK, so the
-`runsignal` CLI provisions the same New Relic alerts for Node.js services as for .NET and Go ones. See the
-[main README](../../README.md) for the concepts and the alerts.
+[![npm](https://img.shields.io/npm/v/@runsignal/node)](https://www.npmjs.com/package/@runsignal/node)
+[![npm downloads](https://img.shields.io/npm/dm/@runsignal/node)](https://www.npmjs.com/package/@runsignal/node)
+[![license](https://img.shields.io/npm/l/@runsignal/node)](https://github.com/gokhanertogan/RunSignal/blob/main/LICENSE)
+
+**Cron job and background job monitoring for Node.js, on OpenTelemetry.** Get an alert when a scheduled job
+does not run, fails, runs too long or processes nothing, and when a BullMQ worker or sync loop stops making
+progress: the failures no HTTP status code describes. Works with node-cron, croner, cron, node-schedule and
+BullMQ, with no hosted service and no ping URLs.
+
+RunSignal records runs, items and heartbeats as OpenTelemetry metrics, with the same names as every other
+RunSignal SDK, so the `runsignal` CLI provisions the same alerts for Node.js services as for .NET, Go, Java and
+Rust ones: New Relic alerts and dashboards, or Prometheus rules and a Grafana dashboard. The
+[main README](https://github.com/gokhanertogan/RunSignal#readme) covers the concepts, the alerts and the
+backends.
+
+## Installation
 
 ```bash
-npm install @runsignal/node @opentelemetry/api   # once published; until then, build from source
+npm install @runsignal/node @opentelemetry/api
 ```
 
-Requires Node.js 20 or later. The package is ESM only and ships its own TypeScript types.
+Requires Node.js 20 or later. The package is ESM only, ships its own TypeScript types, and depends only on
+`@opentelemetry/api` (peer). BullMQ 5.16+ is an optional peer for the BullMQ integration.
 
-## Usage
+## Quick start
 
 ```ts
 import { defaultRegistry } from '@runsignal/node';
@@ -23,45 +36,55 @@ const invoices = defaultRegistry.workload('nightly-invoice', {
   severity: 'critical',
 });
 
-// One run: succeeds when fn resolves, is cancelled if the signal was aborted, fails otherwise.
-await invoices.run(async (signal) => {
+await invoices.run(async () => {
   for (const order of await unbilledOrders()) {
-    await createInvoice(order, { signal });
+    await createInvoice(order);
     invoices.processed();
   }
-}, { signal: shutdown.signal });
+});
 ```
 
-A long-running loop sends heartbeats, so a loop that is alive but stuck is noticed:
-
-```ts
-const sync = defaultRegistry.workload('stock-sync', { expectEvery: '5m' });
-setInterval(async () => {
-  await syncStock();
-  sync.beat();
-}, 60_000);
-```
+The registry follows the global meter provider, so it works even when it is created by an import before the
+OpenTelemetry SDK starts. For an explicit provider, use `new WorkloadRegistry({ meterProvider })`.
 
-Manual runs, and failures without an error:
+## Recording work
 
-```ts
-const run = imports.start();
-const file = await fetchStatement();
-if (!file) {
-  run.failCode('statement_missing', 'no bank statement today');
-} else {
-  run.succeed();
-}
-```
+| Call | Records |
+|---|---|
+| `w.run(fn, { signal })` | One run. It succeeds when `fn` resolves, is cancelled when `signal` was aborted, and fails otherwise. The run's span is active inside `fn` (with a context manager, which `NodeSDK` registers). |
+| `const run = w.start()` then `run.succeed()` / `fail(err)` / `failCode(code, msg)` / `cancel()` | A run ended by hand. Later calls are ignored. |
+| `w.processed(n)` / `w.itemFailed(n)` | Items handled. |
+| `w.beat()` | A heartbeat from a long-running loop. |
 
 `error.type` is the error's `errorType` property if it has one, then its `code` if that is a string (such as
 `ECONNREFUSED`), then its class name.
 
-The registry follows the global meter provider. It works even when it is created, for example by an import,
-before the OpenTelemetry SDK starts. Run spans are nested under the active span when a context manager is
-registered, which `NodeSDK` does for you.
+## Cron libraries
 
-### BullMQ
+Since 0.2.0, `cronJob` declares a scheduled job once, with its schedule, and gives you a tick handler for any cron library.
+The workload is registered immediately, so a job that never fires still gets a `missed` alert.
+
+```ts
+import { cronJob } from '@runsignal/node/cron';
+
+const invoices = cronJob('nightly-invoice', { schedule: '0 2 * * *', maxDuration: '30m', minProcessed: 100 }, async (w) => {
+  for (const order of await unbilledOrders()) {
+    await createInvoice(order);
+    w.processed();
+  }
+});
+
+cron.schedule(invoices.schedule, invoices.run);                                 // node-cron
+new Cron(invoices.schedule, invoices.run);                                      // croner
+CronJob.from({ cronTime: invoices.schedule, onTick: invoices.run, start: true }); // cron
+schedule.scheduleJob(invoices.schedule, invoices.run);                          // node-schedule
+```
+
+- **Failures:** a failed tick is recorded with its error type and passed to `onError` (default `console.error`). It is not rethrown, because most cron libraries turn a rejected tick into an unhandled rejection.
+- **Options:** everything `workload()` takes, plus `registry` and `onError`. Declaring the same name twice throws.
+- **Time zones:** if your scheduler runs the pattern in a time zone, pass the same one to the CLI with `--time-zone`.
+
+## BullMQ
 
 ```ts
 import { discoverSchedulers, instrument, workloadOf } from '@runsignal/node/bullmq';
@@ -75,20 +98,20 @@ await queue.upsertJobScheduler('Daily Sales Report', { pattern: '0 0 6 * * *' },
 await discoverSchedulers(queue);   // registers schedulers before they first fire
 ```
 
-- **What gets recorded:** every job, including success, failure with its error type, cancellation (when BullMQ aborts the job) and duration. Results and errors pass through, so retries work as before.
+- **What is recorded:** every job, including success, failure with its error type, cancellation (when BullMQ aborts the job) and duration. Results and errors pass through, so retries work as before.
 - **Naming:** jobs from a job scheduler are named after the scheduler (`Daily Sales Report` becomes `daily-sales-report`). Other jobs are named after their queue and job name (`emails.send-welcome`).
-- **Discovery:** `discoverSchedulers` takes each scheduler's cron pattern as its schedule, so a scheduler that never fires gets a `missed` alert. Schedulers that use `every` get no schedule.
-- **Redis client:** in ESM, BullMQ 6 needs a constructed Redis client, such as `connection: new Redis({ maxRetriesPerRequest: null })` from `ioredis`, instead of connection options.
+- **Discovery:** `discoverSchedulers` takes each scheduler's cron pattern as its schedule, so a scheduler that never fires gets a `missed` alert.
+- **Redis client:** in ESM, BullMQ 6 needs a constructed client, such as `connection: new Redis({ maxRetriesPerRequest: null })` from `ioredis`.
 
-### Manifest
+## Manifest
 
 ```ts
 defaultRegistry.writeManifestFromEnv('billing-service'); // writes to RUNSIGNAL_MANIFEST_PATH when it is set
 ```
 
-### Exporting to New Relic
+## Exporting
 
-Use delta temporality. With cumulative, a stopped workload never looks stopped:
+**New Relic** needs delta temporality. With cumulative, a stopped workload never looks stopped:
 
 ```ts
 new OTLPMetricExporter({
@@ -98,12 +121,15 @@ new OTLPMetricExporter({
 });
 ```
 
-A complete program is in [examples/worker](examples/worker).
+**Prometheus 3** receives OTLP at `/api/v1/otlp/v1/metrics` with the default (cumulative) temporality. Generate
+its rules with `runsignal export prometheus`.
+
+A complete program is in [examples/worker](https://github.com/gokhanertogan/RunSignal/tree/main/src/RunSignal.Node/examples/worker).
 
 ## Performance
 
 Measured on Apple Silicon with Node.js 26 and the OpenTelemetry metrics SDK attached; the times include its
-aggregation. Run with `npm run bench`.
+aggregation. Run `npm run bench`.
 
 | Operation | Time |
 |---|---|
@@ -115,6 +141,10 @@ create the registry with `new WorkloadRegistry({ tracing: false })`.
 
 ## Development
 
-```bash
-npm test      # needs redis-server on the PATH; the BullMQ tests start their own instance
-```
+`npm test` needs `redis-server` on the `PATH`; the BullMQ tests start their own instance.
+
+## Links
+
+[Specification](https://github.com/gokhanertogan/RunSignal/blob/main/spec/README.md) ·
+[Changelog](https://github.com/gokhanertogan/RunSignal/blob/main/CHANGELOG.md) ·
+[Other languages](https://github.com/gokhanertogan/RunSignal#quick-start)

package/dist/cron.d.ts

@@ -0,0 +1,33 @@
+import { type Workload, type WorkloadOptions, type WorkloadRegistry } from './registry.js';
+export interface CronJobOptions extends WorkloadOptions {
+    /** Cron expression the job runs on. Pass `job.schedule` to your scheduler so the alert and the job agree. */
+    schedule: string;
+    /** The registry to record on. Defaults to `defaultRegistry`. */
+    registry?: WorkloadRegistry;
+    /**
+     * Called with the error of a failed run, after the failure is recorded. Defaults to `console.error`. The error
+     * is not rethrown, because most cron libraries turn a rejected tick into an unhandled rejection.
+     */
+    onError?: (error: unknown, workload: Workload) => void;
+}
+export interface CronJob {
+    /** The workload each tick runs as, for counting items or heartbeats outside `fn`. */
+    readonly workload: Workload;
+    /** The cron expression the job was declared with. */
+    readonly schedule: string;
+    /** Runs `fn` once as a run of the workload. Pass it to your cron library as the tick handler. */
+    readonly run: () => Promise<void>;
+}
+/**
+ * Declares a scheduled job as a workload with `options.schedule` as its schedule, so it gets a missed alert from
+ * startup, even before it first fires. Works with any cron library: node-cron, croner, cron or node-schedule.
+ *
+ * ```ts
+ * const invoices = cronJob('nightly-invoice', { schedule: '0 2 * * *', maxDuration: '30m' }, async (w) => {
+ *   for (const order of await unbilledOrders()) { await createInvoice(order); w.processed(); }
+ * });
+ * cron.schedule(invoices.schedule, invoices.run);   // node-cron
+ * new Cron(invoices.schedule, invoices.run);        // croner
+ * ```
+ */
+export declare function cronJob(name: string, options: CronJobOptions, fn: (workload: Workload) => unknown): CronJob;

package/dist/cron.js

@@ -0,0 +1,33 @@
+import { defaultRegistry } from './registry.js';
+/**
+ * Declares a scheduled job as a workload with `options.schedule` as its schedule, so it gets a missed alert from
+ * startup, even before it first fires. Works with any cron library: node-cron, croner, cron or node-schedule.
+ *
+ * ```ts
+ * const invoices = cronJob('nightly-invoice', { schedule: '0 2 * * *', maxDuration: '30m' }, async (w) => {
+ *   for (const order of await unbilledOrders()) { await createInvoice(order); w.processed(); }
+ * });
+ * cron.schedule(invoices.schedule, invoices.run);   // node-cron
+ * new Cron(invoices.schedule, invoices.run);        // croner
+ * ```
+ */
+export function cronJob(name, options, fn) {
+    const { registry = defaultRegistry, onError = defaultOnError, ...expectations } = options;
+    const workload = registry.workload(name, expectations);
+    return {
+        workload,
+        schedule: options.schedule,
+        run: async () => {
+            try {
+                await workload.run(() => fn(workload));
+            }
+            catch (error) {
+                onError(error, workload);
+            }
+        },
+    };
+}
+function defaultOnError(error, workload) {
+    console.error(`runsignal: a run of ${workload.name} failed`, error);
+}
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA8D,MAAM,eAAe,CAAC;AAuB5G;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,OAAuB,EAAE,EAAmC;IAChG,MAAM,EAAE,QAAQ,GAAG,eAAe,EAAE,OAAO,GAAG,cAAc,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC;IAC1F,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACvD,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,GAAG,EAAE,KAAK,IAAI,EAAE;YACd,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,QAAkB;IACxD,OAAO,CAAC,KAAK,CAAC,uBAAuB,QAAQ,CAAC,IAAI,SAAS,EAAE,KAAK,CAAC,CAAC;AACtE,CAAC"}

package/dist/telemetry.d.ts

@@ -3,7 +3,7 @@
  * SDK (see spec/README.md in the repository), so one set of alert rules covers every language.
  */
 export declare const SCOPE_NAME = "RunSignal";
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 export declare const Metrics: {
     readonly runs: 'runsignal.workload.runs';
     readonly duration: 'runsignal.workload.duration';

package/dist/telemetry.js

@@ -3,7 +3,7 @@
  * SDK (see spec/README.md in the repository), so one set of alert rules covers every language.
  */
 export const SCOPE_NAME = 'RunSignal';
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';
 export const Metrics = {
     runs: 'runsignal.workload.runs',
     duration: 'runsignal.workload.duration',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@runsignal/node",
-  "version": "0.1.0",
-  "description": "Monitor Node.js background work that no HTTP status code describes (scheduled jobs, BullMQ queues, sync loops) with OpenTelemetry, and alert on missed, overrunning, stalled or low-output jobs.",
+  "version": "0.2.0",
+  "description": "Cron job and background job monitoring for Node.js with OpenTelemetry: alert when a scheduled job is missed, fails, overruns or stalls, or a BullMQ queue stops processing. Works with node-cron, croner, cron, node-schedule and BullMQ; alerts for New Relic, Prometheus and Grafana.",
   "license": "MIT",
   "author": "Gokhan Ertogan",
   "repository": {
@@ -10,15 +10,29 @@
     "directory": "src/RunSignal.Node"
   },
   "keywords": [
-    "observability",
-    "opentelemetry",
-    "monitoring",
-    "alerting",
-    "background-jobs",
+    "cron-monitoring",
     "cron",
+    "job-monitoring",
+    "background-jobs",
+    "scheduled-jobs",
     "heartbeat",
+    "dead-mans-switch",
+    "healthcheck",
     "bullmq",
-    "newrelic"
+    "node-cron",
+    "croner",
+    "node-schedule",
+    "queue-monitoring",
+    "worker",
+    "opentelemetry",
+    "otel",
+    "observability",
+    "monitoring",
+    "alerting",
+    "prometheus",
+    "grafana",
+    "newrelic",
+    "typescript"
   ],
   "type": "module",
   "engines": {
@@ -32,6 +46,10 @@
     "./bullmq": {
       "types": "./dist/bullmq.d.ts",
       "default": "./dist/bullmq.js"
+    },
+    "./cron": {
+      "types": "./dist/cron.d.ts",
+      "default": "./dist/cron.js"
     }
   },
   "files": [