wedamija · Oct 17, 2026 · Oct 17, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
@@ -62,6 +62,7 @@ const NO_FETCH_INSTRUMENTATION = [
 // instrumentation creates no spans. Apps must be built with `@sentry/bun/plugin`.
 // See https://github.com/getsentry/sentry-javascript/issues/23882
 export const NO_AUTO_INSTRUMENTATION = [
+  'suites/cron/cron-integration/test.ts',
   'suites/cron/node-cron/integration/test.ts',
   'suites/cron/node-schedule-integration/test.ts',
   'suites/express/**',

@@ -67,7 +67,7 @@
     "body-parser": "^2.3.0",
     "consola": "^3.2.3",
     "cors": "^2.8.5",
-    "cron": "^3.1.6",
+    "cron": "^4.4.0",
     "dataloader": "2.2.2",
     "express": "^4.21.2",
     "fastify": "^5.12.5",

@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  transport: loggingTransport,
+  integrations: [Sentry.cronJobIntegration({ excludeJobs: ['excluded-job'] })],
+});
@@ -0,0 +1,37 @@
+import { CronJob, CronTime } from 'cron';
+
+const excluded = CronJob.from({ cronTime: '0 0 * * *', onTick: () => {}, name: 'excluded-job' });
+const unnamed = new CronJob('0 0 * * *', () => {});
+const oneOff = CronJob.from({ cronTime: new Date(Date.now() + 86_400_000), onTick: () => {}, name: 'one-off-job' });
+const offset = CronJob.from({ cronTime: '0 0 * * *', utcOffset: 60, onTick: () => {}, name: 'offset-job' });
+const subMinute = CronJob.from({ cronTime: '*/10 * * * * *', onTick: () => {}, name: 'sub-minute-job' });
+
+let runs = 0;
+const job = CronJob.from({
+  cronTime: '0 30 9 * * 1-5',
+  timeZone: 'Europe/Vienna',
+  name: 'my-cron-job',
+  waitForCompletion: true,
+  errorHandler: () => {},
+  onTick: async () => {
+    runs++;
+    if (runs === 2) {
+      throw new Error('Error in cron job');
+    }
+  },
+});
+
+// Run the jobs without waiting for their schedule.
+(async () => {
+  await excluded.fireOnTick();
+  await unnamed.fireOnTick();
+  await oneOff.fireOnTick();
+  await offset.fireOnTick();
+  await subMinute.fireOnTick();
+  await job.fireOnTick();
+  await job.fireOnTick();
+  job.setTime(new CronTime('0 8 * * *', 'UTC'));
+  await job.fireOnTick();
+})();
+
+setTimeout(() => process.exit(), 10_000);
@@ -0,0 +1,68 @@
+import type { SerializedCheckIn } from '@sentry/core';
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+const MONITOR_CONFIG = {
+  schedule: { type: 'crontab', value: '30 9 * * 1-5' },
+  timezone: 'Europe/Vienna',
+};
+
+const expectNoConfig = (slug: string) => (checkIn: SerializedCheckIn) => {
+  expect(checkIn).toMatchObject({ monitor_slug: slug, status: 'in_progress' });
+  expect(checkIn.monitor_config).toBeUndefined();
+};
+
+describe('cronJobIntegration', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('sends check-ins for named jobs', async () => {
+      await createRunner()
+        .ignore('event')
+        .expect({ check_in: expectNoConfig('offset-job') })
+        .expect({ check_in: { monitor_slug: 'offset-job', status: 'ok' } })
+        .expect({ check_in: expectNoConfig('sub-minute-job') })
+        .expect({ check_in: { monitor_slug: 'sub-minute-job', status: 'ok' } })
+        .expect({
+          check_in: { monitor_slug: 'my-cron-job', status: 'in_progress', monitor_config: MONITOR_CONFIG },
+        })
+        .expect({ check_in: { monitor_slug: 'my-cron-job', status: 'ok', duration: expect.any(Number) } })
+        .expect({
+          check_in: { monitor_slug: 'my-cron-job', status: 'in_progress', monitor_config: MONITOR_CONFIG },
+        })
+        .expect({ check_in: { monitor_slug: 'my-cron-job', status: 'error', duration: expect.any(Number) } })
+        .expect({
+          check_in: {
+            monitor_slug: 'my-cron-job',
+            status: 'in_progress',
+            monitor_config: { schedule: { type: 'crontab', value: '0 8 * * *' }, timezone: 'UTC' },
+          },
+        })
+        .expect({ check_in: { monitor_slug: 'my-cron-job', status: 'ok', duration: expect.any(Number) } })
+        .start()
+        .completed();
+    });
+
+    test('captures job errors', async () => {
+      await createRunner()
+        .unordered()
+        .expect({
+          event: {
+            exception: {
+              values: [
+                {
+                  type: 'Error',
+                  value: 'Error in cron job',
+                  mechanism: { type: 'auto.function.cron', handled: false },
+                },
+              ],
+            },
+          },
+        })
+        .start()
+        .completed();
+    });
+  });
+});
@@ -28,11 +28,11 @@ cron.start();
 // is enough to hit it, and the job is left scheduled for nothing: no ticks, no check-ins, and the
 // scenario exits on the timeout below having sent nothing at all. Starting again re-reads the clock
 // away from the boundary.
-for (let attempt = 0; attempt < 5 && !cron.running; attempt++) {
+for (let attempt = 0; attempt < 5 && !cron.isActive; attempt++) {
   cron.start();
 }
 
-if (!cron.running) {
+if (!cron.isActive) {
   throw new Error('`cron` refused to schedule the job');
 }
 

@@ -47,6 +47,7 @@ export {
   fsIntegration,
   functionToStringIntegration,
   genericPoolIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   getActiveSpan,

@@ -116,6 +116,7 @@ export {
   firebaseIntegration,
   fsIntegration,
   genericPoolIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   graphqlIntegration,

@@ -138,6 +138,7 @@ export {
   // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   genericPoolIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   graphqlIntegration,

@@ -183,6 +183,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   tediousIntegration,

@@ -117,6 +117,7 @@ export {
   // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   genericPoolIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   graphqlIntegration,

@@ -116,6 +116,7 @@ export {
   fastifyIntegration,
   firebaseIntegration,
   genericPoolIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   graphqlIntegration,

@@ -1,4 +1,4 @@
-import { captureException, withMonitor } from '@sentry/core';
+import { addNonEnumerableProperty, captureException, withMonitor } from '@sentry/core';
 import { replaceCronNames } from './common';
 
 export type CronJobParams = {
@@ -51,6 +51,8 @@ export type CronJobConstructor = {
   ): CronJob;
 };
 
+const MONITORED = Symbol.for('sentry.cron.monitored');
+
 const ERROR_TEXT = 'Automatic instrumentation of CronJob only supports crontab string';
 
 /**
@@ -115,6 +117,9 @@ export function instrumentCron<T>(lib: T & CronJobConstructor, monitorSlug: stri
         );
       }
 
+      // Tells `cronJobIntegration` that this job is already monitored.
+      addNonEnumerableProperty(monitoredTick, MONITORED, true);
+
       return new target(cronTime, monitoredTick, onComplete, start, timeZone, ...rest);
     },
     get(target, prop: keyof CronJobConstructor) {
@@ -157,6 +162,8 @@ export function instrumentCron<T>(lib: T & CronJobConstructor, monitorSlug: stri
             );
           };
 
+          addNonEnumerableProperty(param.onTick, MONITORED, true);
+
           return target.from(param);
         };
       } else {

@@ -11,6 +11,8 @@ export {
   type ExpressIntegrationOptions,
   firebaseIntegration,
   genericPoolIntegration,
+  cronJobIntegration,
+  type CronJobIntegrationOptions,
   nodeCronIntegration,
   type NodeCronIntegrationOptions,
   nodeScheduleIntegration,

@@ -37,6 +37,7 @@ export {
   flush,
   functionToStringIntegration,
   genericPoolIntegration,
+  cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,
   getActiveSpan,

@@ -38,6 +38,8 @@ export { anthropicAIIntegration } from './integrations/anthropic';
 export { awsIntegration } from './integrations/aws-sdk';
 export { dataloaderIntegration } from './integrations/dataloader';
 export { genericPoolIntegration } from './integrations/generic-pool';
+export { cronJobIntegration } from './integrations/cron';
+export type { CronJobIntegrationOptions } from './integrations/cron';
 export { nodeCronIntegration } from './integrations/node-cron';
 export type { NodeCronIntegrationOptions } from './integrations/node-cron';
 export { nodeScheduleIntegration } from './integrations/node-schedule';

@@ -0,0 +1,70 @@
+import type { IntegrationFn, MonitorConfig } from '@sentry/core';
+import { defineIntegration } from '@sentry/core';
+import { CHANNELS } from '../orchestrion/channels';
+import { cronModuleNames } from '../orchestrion/config/cron';
+import { invokeOrchestrionInstrumentation } from '../orchestrion/instrumentation';
+import type { AnyFn, ScheduleChange } from '../utils/cronMonitoring';
+import {
+  cronExpressionToMonitorConfig,
+  shouldMonitorJob,
+  subscribeToJobCreation,
+  subscribeToScheduleChange,
+  updateMonitorConfig,
+  wrapScheduledJob,
+} from '../utils/cronMonitoring';
+
+const INTEGRATION_NAME = 'CronJob' as const;
+
+export interface CronJobIntegrationOptions {
+  /** Job names not to monitor. Strings must match the name exactly. */
+  excludeJobs?: Array<string | RegExp>;
+}
+
+const _cronJobIntegration = ((options: CronJobIntegrationOptions = {}) => {
+  return {
+    name: INTEGRATION_NAME,
+    setup(client) {
+      invokeOrchestrionInstrumentation(client, cronModuleNames, subscribe, [options], {
+        requiresTracingChannelBinding: false,
+      });
+    },
+  };
+}) satisfies IntegrationFn;
+
+/**
+ * Sends Crons check-ins for every `CronJob` of the `cron` package (4.3+) that has a `name`.
+ * The monitor slug is the job name; jobs without a name, and one-off jobs, are not monitored.
+ */
+export const cronJobIntegration = defineIntegration(_cronJobIntegration);
+
+function subscribe(options: CronJobIntegrationOptions): void {
+  subscribeToJobCreation(CHANNELS.CRON_JOB_CONSTRUCTOR, INTEGRATION_NAME, args => wrapJob(args, options));
+  subscribeToScheduleChange(CHANNELS.CRON_JOB_SET_TIME, INTEGRATION_NAME, onSetTime);
+}
+
+/** Sends the new time's config after `job.setTime(cronTime)`. */
+export function onSetTime({ arguments: [cronTime], self }: ScheduleChange): void {
+  const job = self as { cronTime?: unknown; _callbacks?: unknown[] } | undefined;
+  // `setTime` throws and keeps the old time when it isn't given a `CronTime`.
+  if (!job || job.cronTime !== cronTime) {
+    return;
+  }
+  const { source, timeZone, utcOffset } = cronTime as { source?: unknown; timeZone?: unknown; utcOffset?: unknown };
+  const monitorConfig: MonitorConfig | undefined =
+    typeof source === 'string' && utcOffset == null ? cronExpressionToMonitorConfig(source, timeZone, 'or') : undefined;
+  for (const callback of job._callbacks || []) {
+    updateMonitorConfig(callback, monitorConfig);
+  }
+}
+
+// `new CronJob(cronTime, onTick, onComplete, start, timeZone, context, runOnInit, utcOffset, ..., name)`
+function wrapJob(args: unknown[], options: CronJobIntegrationOptions): void {
+  const [cronTime, onTick, , , timeZone] = args;
+  const utcOffset = args[7];
+  const name = args[11];
+  if (typeof cronTime !== 'string' || !shouldMonitorJob(name, onTick, options.excludeJobs)) {
+    return;
+  }
+  const monitorConfig = utcOffset == null ? cronExpressionToMonitorConfig(cronTime, timeZone, 'or') : undefined;
+  args[1] = wrapScheduledJob(onTick as AnyFn, name, monitorConfig, 'auto.function.cron');
+}
@@ -1,6 +1,7 @@
 import { amqplibChannels } from './config/amqplib';
 import { anthropicAiChannels } from './config/anthropic-ai';
 import { awsSdkChannels } from './config/aws-sdk';
+import { cronChannels } from './config/cron';
 import { dataloaderChannels } from './config/dataloader';
 import { expressChannels } from './config/express';
 import { firebaseChannels } from './config/firebase';
@@ -60,6 +61,7 @@ export const CHANNELS = {
   ...amqplibChannels,
   ...anthropicAiChannels,
   ...awsSdkChannels,
+  ...cronChannels,
   ...dataloaderChannels,
   ...expressChannels,
   ...firebaseChannels,

@@ -0,0 +1,23 @@
+import type { InstrumentationConfig } from '../apmTypes';
+import { getModuleNames } from './module-names';
+
+// `CronJob.from()` calls the constructor. Job names were added in 4.3.0.
+export const cronConfig = [
+  {
+    channelName: 'cronJobConstructor',
+    module: { name: 'cron', versionRange: '>=4.3.0 <5', filePath: 'dist/job.js' },
+    functionQuery: { className: 'CronJob' },
+  },
+  {
+    channelName: 'cronJobSetTime',
+    module: { name: 'cron', versionRange: '>=4.3.0 <5', filePath: 'dist/job.js' },
+    functionQuery: { className: 'CronJob', methodName: 'setTime', kind: 'Sync' },
+  },
+] satisfies InstrumentationConfig[];
+
+export const cronModuleNames = getModuleNames(cronConfig);
+
+export const cronChannels = {
+  CRON_JOB_CONSTRUCTOR: 'orchestrion:cron:cronJobConstructor',
+  CRON_JOB_SET_TIME: 'orchestrion:cron:cronJobSetTime',
+} as const;
@@ -5,6 +5,7 @@ import { uniq } from '@sentry/core';
 import { awsSdkConfig } from './aws-sdk';
 import { amqplibConfig } from './amqplib';
 import { anthropicAiConfig } from './anthropic-ai';
+import { cronConfig } from './cron';
 import { dataloaderConfig } from './dataloader';
 import { expressConfig } from './express';
 import { firebaseConfig } from './firebase';
@@ -66,6 +67,7 @@ export const SENTRY_INSTRUMENTATIONS: InstrumentationConfig[] = [
   ...amqplibConfig,
   ...anthropicAiConfig,
   ...awsSdkConfig,
+  ...cronConfig,
   ...dataloaderConfig,
   ...expressConfig,
   ...firebaseConfig,