wedamija · Oct 29, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 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/node-cron/integration/test.ts',
   'suites/express/**',
   'suites/fs-instrumentation/test.ts',
   'suites/hono/test.ts',

@@ -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.nodeCronIntegration({ excludeJobs: ['excluded-job'] })],
+});
@@ -0,0 +1,25 @@
+import cron from 'node-cron';
+
+const excluded = cron.schedule('0 0 0 1 1 *', () => {}, { name: 'excluded-job' });
+const unnamed = cron.schedule('0 0 0 1 1 *', () => {});
+
+let runs = 0;
+const task = cron.schedule(
+  '0 0 0 1 1 *',
+  () => {
+    runs++;
+    if (runs > 1) {
+      throw new Error('Error in cron job');
+    }
+  },
+  { name: 'my-cron-job', timezone: 'America/New_York' },
+);
+
+// Run the tasks by hand. Their schedules can't fire during the test.
+excluded
+  .execute()
+  .then(() => unnamed.execute())
+  .then(() => task.execute())
+  .then(() => task.execute());
+
+setTimeout(() => process.exit(), 10_000);
@@ -0,0 +1,50 @@
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../../utils/runner';
+
+const MONITOR_CONFIG = {
+  schedule: { type: 'crontab', value: '0 0 1 1 *' },
+  timezone: 'America/New_York',
+};
+
+describe('nodeCronIntegration', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('sends check-ins for named tasks', async () => {
+      await createRunner()
+        .ignore('event')
+        .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) } })
+        .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.node-cron', handled: false },
+                },
+              ],
+            },
+          },
+        })
+        .start()
+        .completed();
+    });
+  });
+});
@@ -47,6 +47,7 @@ export {
   fsIntegration,
   functionToStringIntegration,
   genericPoolIntegration,
+  nodeCronIntegration,
   getActiveSpan,
   getAutoPerformanceIntegrations,
   getClient,

@@ -116,6 +116,7 @@ export {
   firebaseIntegration,
   fsIntegration,
   genericPoolIntegration,
+  nodeCronIntegration,
   graphqlIntegration,
   knexIntegration,
   kafkaIntegration,

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

@@ -183,6 +183,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  nodeCronIntegration,
   tediousIntegration,
   eveConversationHook,
   eveIntegration,

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

@@ -116,6 +116,7 @@ export {
   fastifyIntegration,
   firebaseIntegration,
   genericPoolIntegration,
+  nodeCronIntegration,
   graphqlIntegration,
   knexIntegration,
   kafkaIntegration,

@@ -1,4 +1,4 @@
-import { captureException, type MonitorConfig, withMonitor } from '@sentry/core';
+import { addNonEnumerableProperty, captureException, type MonitorConfig, withMonitor } from '@sentry/core';
 import { replaceCronNames } from './common';
 
 export interface NodeCronOptions {
@@ -78,6 +78,9 @@ export function instrumentNodeCron<T>(
               );
             };
 
+            // Tells `nodeCronIntegration` that this task is already monitored.
+            addNonEnumerableProperty(monitoredCallback, Symbol.for('sentry.cron.monitored'), true);
+
             return target.apply(thisArg, [expression, monitoredCallback, options]);
           },
         });

@@ -11,6 +11,8 @@ export {
   type ExpressIntegrationOptions,
   firebaseIntegration,
   genericPoolIntegration,
+  nodeCronIntegration,
+  type NodeCronIntegrationOptions,
   googleGenAIIntegration,
   graphqlIntegration,
   groqIntegration,

@@ -37,6 +37,7 @@ export {
   flush,
   functionToStringIntegration,
   genericPoolIntegration,
+  nodeCronIntegration,
   getActiveSpan,
   getAutoPerformanceIntegrations,
   getClient,

@@ -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 { nodeCronIntegration } from './integrations/node-cron';
+export type { NodeCronIntegrationOptions } from './integrations/node-cron';
 export { googleGenAIIntegration } from './integrations/google-genai';
 export { graphqlIntegration } from './integrations/graphql';
 export { hapiIntegration } from './integrations/hapi';

@@ -0,0 +1,104 @@
+import type { IntegrationFn, MonitorConfig } from '@sentry/core';
+import { defineIntegration } from '@sentry/core';
+import { CHANNELS } from '../orchestrion/channels';
+import { nodeCronModuleNames } from '../orchestrion/config/node-cron';
+import { invokeOrchestrionInstrumentation } from '../orchestrion/instrumentation';
+import type { AnyFn } from '../utils/cronMonitoring';
+import {
+  cronExpressionToMonitorConfig,
+  shouldMonitorJob,
+  subscribeToJobCreation,
+  wrapScheduledJob,
+} from '../utils/cronMonitoring';
+
+const INTEGRATION_NAME = 'NodeCron' as const;
+
+export interface NodeCronIntegrationOptions {
+  /** Task names not to monitor. Strings must match the name exactly. */
+  excludeJobs?: Array<string | RegExp>;
+}
+
+const _nodeCronIntegration = ((options: NodeCronIntegrationOptions = {}) => {
+  return {
+    name: INTEGRATION_NAME,
+    setup(client) {
+      invokeOrchestrionInstrumentation(client, nodeCronModuleNames, subscribe, [options], {
+        // The binding only parents spans, and this integration creates none.
+        requiresTracingChannelBinding: false,
+      });
+    },
+  };
+}) satisfies IntegrationFn;
+
+/**
+ * Sends Crons check-ins for every named `node-cron` task, with its schedule as the monitor config.
+ * The monitor slug is the task's `name` option. Tasks without a name, or with a schedule Sentry can't express, are not
+ * monitored.
+ */
+export const nodeCronIntegration = defineIntegration(_nodeCronIntegration);
+
+function subscribe(options: NodeCronIntegrationOptions): void {
+  subscribeToJobCreation(CHANNELS.NODE_CRON_CREATE_TASK, INTEGRATION_NAME, args => wrapTask(args, options));
+  subscribeToJobCreation(CHANNELS.NODE_CRON_V4_CREATE_TASK, INTEGRATION_NAME, args =>
+    wrapTask(args, options, isReadAlikeByNodeCron4),
+  );
+  subscribeToJobCreation(CHANNELS.NODE_CRON_V3_CREATE_TASK, INTEGRATION_NAME, args =>
+    wrapTask(args, options, isReadAlikeByNodeCron3),
+  );
+}
+
+// `createTask(expression, func, options)`
+function wrapTask(
+  args: unknown[],
+  options: NodeCronIntegrationOptions,
+  isReadAlike?: (expression: string) => boolean,
+): void {
+  const [expression, func, taskOptions] = args;
+  const { name, timezone } = (taskOptions || {}) as { name?: unknown; timezone?: unknown };
+  if (!shouldMonitorJob(name, func, options.excludeJobs)) {
+    return;
+  }
+  const monitorConfig = getMonitorConfig(String(expression), timezone, isReadAlike);
+  args[1] = wrapScheduledJob(func as AnyFn, name, monitorConfig, 'auto.function.node-cron');
+}
+
+/** The monitor config for a task, or `undefined` if `isReadAlike` says this node-cron version reads it differently. */
+export function getMonitorConfig(
+  expression: string,
+  timezone: unknown,
+  isReadAlike?: (expression: string) => boolean,
+): MonitorConfig | undefined {
+  return isReadAlike && !isReadAlike(expression)
+    ? undefined
+    : cronExpressionToMonitorConfig(expression, timezone, 'and');
+}
+
+const NODE_CRON_3_FIELD_MINIMUMS = [0, 0, 1, 1, 0];
+
+/**
+ * node-cron before 4.6 reads `7` as `0` and swaps reversed ranges, so it runs `sat-sun`, `6-0` and `6-7` every day.
+ * Returns `false` for weekday ranges that could hit that.
+ */
+export function isReadAlikeByNodeCron4(expression: string): boolean {
+  const weekday = expression.trim().split(/\s+/).pop() || '';
+  return !(weekday.includes('-') && (weekday.includes('7') || /-(?:0|sun)/i.test(weekday)));
+}
+
+/**
+ * node-cron 3 keeps the values of a stepped field that are multiples of the step (`*\/2` days are 2, 4, ...)
+ * and reads weekday ranges like node-cron 4 before 4.6. Returns `false` where that differs from standard cron.
+ */
+export function isReadAlikeByNodeCron3(expression: string): boolean {
+  const fields = expression.trim().split(/\s+/);
+  const minimums = fields.length === 6 ? [0, ...NODE_CRON_3_FIELD_MINIMUMS] : NODE_CRON_3_FIELD_MINIMUMS;
+  return (
+    isReadAlikeByNodeCron4(expression) &&
+    fields.every((field, index) => {
+      if (!field.includes('/')) {
+        return true;
+      }
+      const match = /^(?:\*|(\d+)-\d+)\/(\d+)$/.exec(field);
+      return !!match && Number(match[1] ?? minimums[index]) % Number(match[2]) === 0;
+    })
+  );
+}
@@ -26,6 +26,7 @@ import { mysql2Channels } from './config/mysql2';
 import { mysqlChannels } from './config/mysql';
 import { neonChannels } from './config/neon';
 import { nestjsChannels } from './config/nestjs';
+import { nodeCronChannels } from './config/node-cron';
 import { openaiChannels } from './config/openai';
 import { pgChannels } from './config/pg';
 import { piDurableChannels } from './config/pi-durable';
@@ -83,6 +84,7 @@ export const CHANNELS = {
   ...mysqlChannels,
   ...neonChannels,
   ...nestjsChannels,
+  ...nodeCronChannels,
   ...openaiChannels,
   ...pgChannels,
   ...piDurableChannels,

@@ -33,6 +33,7 @@ import { mysqlConfig } from './mysql';
 import { neonConfig } from './neon';
 import { nestjsConfig } from './nestjs';
 import { nitroConfig } from './nitro';
+import { nodeCronConfig } from './node-cron';
 import { openaiConfig } from './openai';
 import { pgConfig } from './pg';
 import { postgresJsConfig } from './postgres';
@@ -91,6 +92,7 @@ export const SENTRY_INSTRUMENTATIONS: InstrumentationConfig[] = [
   ...neonConfig,
   ...nestjsConfig,
   ...nitroConfig,
+  ...nodeCronConfig,
   ...openaiConfig,
   ...pgConfig,
   ...piDurableConfig,

@@ -0,0 +1,52 @@
+import type { InstrumentationConfig } from '../apmTypes';
+import { getModuleNames } from './module-names';
+
+const createTask = { functionName: 'createTask', kind: 'Sync' } as const;
+
+// `schedule()` calls `createTask(expression, func, options)`, so wrapping `createTask` covers both.
+// Before 4.6, node-cron reads weekday ranges like `sat-sun` differently, so those versions get their own channel.
+export const nodeCronConfig = [
+  {
+    channelName: 'createTask',
+    module: { name: 'node-cron', versionRange: '>=4.6.0 <5', filePath: 'dist/node-cron.cjs' },
+    functionQuery: createTask,
+  },
+  {
+    channelName: 'createTask',
+    module: { name: 'node-cron', versionRange: '>=4.6.0 <5', filePath: 'dist/node-cron.js' },
+    functionQuery: createTask,
+  },
+  {
+    channelName: 'v4_createTask',
+    module: { name: 'node-cron', versionRange: '>=4.3.0 <4.6.0', filePath: 'dist/node-cron.cjs' },
+    functionQuery: createTask,
+  },
+  {
+    channelName: 'v4_createTask',
+    module: { name: 'node-cron', versionRange: '>=4.0.0 <4.6.0', filePath: 'dist/node-cron.js' },
+    functionQuery: createTask,
+  },
+  {
+    channelName: 'v4_createTask',
+    module: { name: 'node-cron', versionRange: '>=4.0.0 <4.3.0', filePath: 'dist/cjs/node-cron.js' },
+    functionQuery: createTask,
+  },
+  {
+    channelName: 'v4_createTask',
+    module: { name: 'node-cron', versionRange: '>=4.0.0 <4.3.0', filePath: 'dist/esm/node-cron.js' },
+    functionQuery: createTask,
+  },
+  {
+    channelName: 'v3_createTask',
+    module: { name: 'node-cron', versionRange: '>=3.0.0 <4', filePath: 'src/node-cron.js' },
+    functionQuery: createTask,
+  },
+] satisfies InstrumentationConfig[];
+
+export const nodeCronModuleNames = getModuleNames(nodeCronConfig);
+
+export const nodeCronChannels = {
+  NODE_CRON_CREATE_TASK: 'orchestrion:node-cron:createTask',
+  NODE_CRON_V4_CREATE_TASK: 'orchestrion:node-cron:v4_createTask',
+  NODE_CRON_V3_CREATE_TASK: 'orchestrion:node-cron:v3_createTask',
+} as const;