feat(nestjs): Add an option to monitor every @Cron method

dev-packages/e2e-tests/test-applications/nestjs-basic/src/app.controller.ts

@@ -92,6 +92,12 @@ export class AppController {
     return {};
   }
 
+  @Get('test-auto-monitored-cron')
+  async testAutoMonitoredCron() {
+    await this.appService.testAutoMonitoredCron();
+    return {};
+  }
+
   @Get('kill-test-cron/:job')
   async killTestCron(@Param('job') job: string) {
     this.appService.killTestCron(job);

dev-packages/e2e-tests/test-applications/nestjs-basic/src/app.service.ts

@@ -120,6 +120,12 @@ export class AppService {
     console.log('Test derived cron!');
   }
 
+  // Monitored through `monitorCronJobs`, without `@SentryCron`.
+  @Cron('0 0 * * *', { name: 'test-auto-monitored-cron', timeZone: 'America/New_York', disabled: true })
+  async testAutoMonitoredCron() {
+    console.log('Test auto-monitored cron!');
+  }
+
   async killTestCron(job: string) {
     this.schedulerRegistry.deleteCronJob(job);
   }

dev-packages/e2e-tests/test-applications/nestjs-basic/src/instrument.ts

@@ -5,6 +5,7 @@ Sentry.init({
   dsn: process.env.E2E_TEST_DSN,
   tunnel: `http://localhost:3031/`, // proxy server
   tracesSampleRate: 1,
+  integrations: [Sentry.nestIntegration({ monitorCronJobs: true })],
   transportOptions: {
     // We expect the app to send a lot of events in a short time
     bufferSize: 1000,

dev-packages/e2e-tests/test-applications/nestjs-basic/tests/cron-decorator.test.ts

@@ -91,6 +91,29 @@ test('Sends the schedule and time zone of @Cron with the check-in', async ({ bas
   );
 });
 
+test('Monitors @Cron methods without @SentryCron when monitorCronJobs is enabled', async ({ baseURL }) => {
+  const inProgressEnvelopePromise = waitForEnvelopeItem('nestjs-basic', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      envelope[1]['monitor_slug'] === 'test-auto-monitored-cron' &&
+      envelope[1]['status'] === 'in_progress'
+    );
+  });
+
+  await fetch(`${baseURL}/test-auto-monitored-cron`);
+
+  expect((await inProgressEnvelopePromise)[1]).toEqual(
+    expect.objectContaining({
+      monitor_slug: 'test-auto-monitored-cron',
+      status: 'in_progress',
+      monitor_config: {
+        schedule: { type: 'crontab', value: '0 0 * * *' },
+        timezone: 'America/New_York',
+      },
+    }),
+  );
+});
+
 test('Sends exceptions to Sentry on error in async cron job', async ({ baseURL }) => {
   const errorEventPromise = waitForError('nestjs-basic', event => {
     return (

packages/nestjs/src/decorators.ts

@@ -6,7 +6,7 @@ import { startSpan } from '@sentry/node';
 import { DEBUG_BUILD } from './debug-build';
 import { isExpectedError } from './helpers';
 import type { ReflectWithMetadata } from './integrations/helpers';
-import { copyReflectMetadata, getNestScheduleVersion } from './integrations/helpers';
+import { copyReflectMetadata, getNestScheduleVersion, markSentryCronMethod } from './integrations/helpers';
 
 /**
  * Monitor settings for `@SentryCron` whose schedule and time zone come from the `@Cron()` decorator
@@ -60,6 +60,8 @@ export const SentryCron = (
     };
 
     descriptor.value = wrappedMethod;
+    markSentryCronMethod(originalMethod);
+    markSentryCronMethod(wrappedMethod);
 
     copyFunctionNameAndMetadata({ originalMethod, descriptor });
 
@@ -138,7 +140,7 @@ function getMonitorConfigFromNestCron(candidates: unknown[]): MonitorConfig | un
  * Converts the options `@Cron()` stores as metadata into a Sentry monitor config.
  * Returns `undefined` for schedules Sentry can't represent.
  */
-function nestCronOptionsToMonitorConfig(
+export function nestCronOptionsToMonitorConfig(
   cronOptions: NestCronOptions,
   scheduleVersion: string | undefined,
 ): MonitorConfig | undefined {

packages/nestjs/src/index.ts

@@ -4,6 +4,7 @@
 export * from '@sentry/node';
 
 export { nestIntegration } from './integrations/nest';
+export type { NestIntegrationOptions } from './integrations/nest';
 
 export { getDefaultIntegrations, init } from './sdk';
 

packages/nestjs/src/integrations/cron-monitoring.ts

@@ -0,0 +1,105 @@
+import type { Client, MonitorConfig } from '@sentry/core';
+import { debug, getClient, stringMatchesSomePattern } from '@sentry/core';
+import { DEBUG_BUILD } from '../debug-build';
+import { nestCronOptionsToMonitorConfig } from '../decorators';
+import type { AnyFn } from './helpers';
+import { isSentryCronMethod } from './helpers';
+
+export interface NestCronMonitoringOptions {
+  /**
+   * Send check-ins for every `@Cron()` method of `@nestjs/schedule`. The monitor slug is the `name`
+   * option of `@Cron()`, or `ClassName.methodName`. Methods with `@SentryCron()` keep their own slug.
+   * Methods whose schedule Sentry can't represent, like every 10 seconds, are not monitored.
+   *
+   * Defaults to `false`.
+   */
+  monitorCronJobs?: boolean;
+
+  /**
+   * Monitor slugs not to monitor when `monitorCronJobs` is enabled. Strings must match the slug exactly.
+   */
+  excludeCronJobs?: Array<string | RegExp>;
+}
+
+interface CronMonitor {
+  slug: string;
+  config: MonitorConfig;
+}
+
+const MONITORING_OPTIONS = new WeakMap<Client, NestCronMonitoringOptions>();
+
+/** Enables `@Cron()` monitoring for the client. */
+export function setCronMonitoringOptions(client: Client, options: NestCronMonitoringOptions): void {
+  if (options.monitorCronJobs) {
+    MONITORING_OPTIONS.set(client, options);
+  }
+}
+
+/**
+ * Returns a function that resolves the monitor for a `@Cron()` method on each run,
+ * or `undefined` if the run should not be monitored.
+ */
+export function makeCronMonitorResolver(
+  cronArgs: unknown[],
+  target: unknown,
+  propertyKey: string | symbol | undefined,
+  scheduleVersion?: string,
+): (handler: AnyFn, wrapped: AnyFn) => CronMonitor | undefined {
+  let monitor: CronMonitor | null | undefined;
+
+  return (handler, wrapped) => {
+    const client = getClient();
+    const options = client && MONITORING_OPTIONS.get(client);
+    if (!options || isSentryCronMethod(handler) || isSentryCronMethod(wrapped)) {
+      return undefined;
+    }
+
+    if (monitor === undefined) {
+      try {
+        monitor = getCronMonitor(cronArgs, target, propertyKey, scheduleVersion);
+      } catch (e) {
+        DEBUG_BUILD && debug.error('[Nest] Failed to set up the cron monitor:', e);
+        monitor = null;
+      }
+    }
+
+    if (!monitor || stringMatchesSomePattern(monitor.slug, options.excludeCronJobs, true)) {
+      return undefined;
+    }
+    return monitor;
+  };
+}
+
+function getCronMonitor(
+  [cronTime, cronOptions]: unknown[],
+  target: unknown,
+  propertyKey: string | symbol | undefined,
+  scheduleVersion: string | undefined,
+): CronMonitor | null {
+  // A `Date` runs once, so there is nothing to monitor.
+  if (typeof cronTime !== 'string') {
+    return null;
+  }
+
+  const options = (cronOptions && typeof cronOptions === 'object' ? cronOptions : {}) as Record<string, unknown>;
+  const className = (target as { constructor?: { name?: unknown } } | undefined)?.constructor?.name;
+  const slug =
+    typeof options.name === 'string' && options.name
+      ? options.name
+      : typeof className === 'string' && className && propertyKey !== undefined
+        ? `${className}.${String(propertyKey)}`
+        : undefined;
+
+  if (!slug) {
+    DEBUG_BUILD && debug.warn('[Nest] Not monitoring a @Cron() method without a name.');
+    return null;
+  }
+
+  const config = nestCronOptionsToMonitorConfig({ ...options, cronTime }, scheduleVersion);
+  if (!config) {
+    DEBUG_BUILD && debug.log(`[Nest] Not monitoring ${slug}: Sentry can't represent its schedule.`);
+    return null;
+  }
+
+  return { slug, config };
+}

packages/nestjs/src/integrations/helpers.ts

@@ -9,7 +9,13 @@ import {
 } from '@sentry/conventions/attributes';
 import { FUNCTION, MIDDLEWARE, QUEUE_PROCESS } from '@sentry/conventions/op';
 import type { Span } from '@sentry/core';
-import { addNonEnumerableProperty, getClient, hasSpanStreamingEnabled, withActiveSpan } from '@sentry/core';
+import {
+  addNonEnumerableProperty,
+  getClient,
+  hasSpanStreamingEnabled,
+  isObjectLike,
+  withActiveSpan,
+} from '@sentry/core';
 import type { CatchTarget, InjectableTarget, NextFunction, Observable, Subscription } from './types';
 
 /** A function of unknown signature, matching the methods/handlers we wrap. */
@@ -33,17 +39,54 @@ export function markWrapped(fn: AnyFn): void {
 
 // `@nestjs/schedule`'s metadata key for the `@Cron()` options.
 const SCHEDULE_CRON_OPTIONS = 'SCHEDULE_CRON_OPTIONS';
+const SENTRY_CRON_METADATA = 'sentry:nestjs:sentry_cron';
+
+const SENTRY_CRON_METHODS = new WeakSet<object>();
+
+/** The options `@Cron()` stored as metadata on `fn`, if any. */
+export function getCronOptions(fn: object): object | undefined {
+  const R = Reflect as ReflectWithMetadata;
+  const options = typeof R.getMetadata === 'function' ? R.getMetadata(SCHEDULE_CRON_OPTIONS, fn) : undefined;
+  return isObjectLike(options) ? options : undefined;
+}
+
+/**
+ * Marks a method that `@SentryCron()` monitors, so `@Cron()` monitoring skips it. Other decorators may wrap the
+ * method on either side of `@SentryCron()`, so this also sets metadata they copy outward and marks the `@Cron()`
+ * options that are already there.
+ */
+export function markSentryCronMethod(fn: object): void {
+  SENTRY_CRON_METHODS.add(fn);
+  const R = Reflect as ReflectWithMetadata;
+  if (typeof R.defineMetadata === 'function') {
+    R.defineMetadata(SENTRY_CRON_METADATA, true, fn);
+  }
+  const cronOptions = getCronOptions(fn);
+  if (cronOptions) {
+    SENTRY_CRON_METHODS.add(cronOptions);
+  }
+}
+
+/** Whether `fn` is monitored by `@SentryCron()` (see {@link markSentryCronMethod}). */
+export function isSentryCronMethod(fn: object): boolean {
+  const R = Reflect as ReflectWithMetadata;
+  const cronOptions = getCronOptions(fn);
+  return (
+    SENTRY_CRON_METHODS.has(fn) ||
+    (typeof R.getMetadata === 'function' && R.getMetadata(SENTRY_CRON_METADATA, fn) === true) ||
+    (!!cronOptions && SENTRY_CRON_METHODS.has(cronOptions))
+  );
+}
 
 const NEST_SCHEDULE_VERSIONS = new WeakMap<object, string>();
 
 /** Remembers the `@nestjs/schedule` version whose `@Cron()` stored the options on `method`. */
 export function setNestScheduleVersion(method: unknown, version: string | undefined): void {
-  const R = Reflect as ReflectWithMetadata;
-  if (typeof method !== 'function' || !version || typeof R.getMetadata !== 'function') {
+  if (typeof method !== 'function' || !version) {
     return;
   }
-  const cronOptions = R.getMetadata(SCHEDULE_CRON_OPTIONS, method);
-  if (cronOptions && typeof cronOptions === 'object') {
+  const cronOptions = getCronOptions(method);
+  if (cronOptions) {
     NEST_SCHEDULE_VERSIONS.set(cronOptions, version);
   }
 }

packages/nestjs/src/integrations/nest.ts

@@ -1,16 +1,23 @@
 import { defineIntegration } from '@sentry/core';
+import type { NestCronMonitoringOptions } from './cron-monitoring';
+import { setCronMonitoringOptions } from './cron-monitoring';
 import { subscribeToNestChannels } from './orchestrion-subscriber';
 
 const INTEGRATION_NAME = 'Nest' as const;
 
+export type NestIntegrationOptions = NestCronMonitoringOptions;
+
 /**
  * Integration capturing tracing data for NestJS.
  */
-export const nestIntegration = defineIntegration(() => {
+export const nestIntegration = defineIntegration((options: NestIntegrationOptions = {}) => {
   return {
     name: INTEGRATION_NAME,
     setupOnce() {
       subscribeToNestChannels();
     },
+    setup(client) {
+      setCronMonitoringOptions(client, options);
+    },
   };
 });

packages/nestjs/src/integrations/orchestrion-subscriber.ts

@@ -1,5 +1,5 @@
 import * as diagnosticsChannel from 'node:diagnostics_channel';
-import { debug, startInactiveSpan, waitForTracingChannelBinding } from '@sentry/core';
+import { addNonEnumerableProperty, debug, startInactiveSpan, waitForTracingChannelBinding } from '@sentry/core';
 import type { OrchestrionChannelContext } from '@sentry/server-utils';
 import { bindTracingChannelToSpan } from '@sentry/server-utils';
 import { nestjsChannels as CHANNELS } from '@sentry/server-utils/orchestrion/config';
@@ -10,11 +10,13 @@ import type { CatchTarget, InjectableTarget, MinimalNestJsExecutionContext } fro
 import { patchCatchTarget, patchInjectableTarget } from './wrap-components';
 import {
   extractQueueName,
-  MECHANISM_CRON,
+  linkCronOptionsToMonitor,
   MECHANISM_INTERVAL,
   MECHANISM_TIMEOUT,
   patchMethodDescriptor,
   patchProcessorTarget,
+  sendsCronCheckIns,
+  wrapCronHandler,
   wrapEventHandler,
   wrapScheduleHandler,
 } from './wrap-handlers';
@@ -50,7 +52,10 @@ function subscribeDecoratorChannel<T>(channelName: string, patch: (target: T) =>
  * `descriptor.value` with a wrapped handler before delegating to the
  * original decorator.
  */
-function makeMethodDecorator(original: AnyFn, wrapHandler: (handler: AnyFn) => AnyFn): AnyFn {
+function makeMethodDecorator(
+  original: AnyFn,
+  wrapHandler: (handler: AnyFn, target: unknown, propertyKey: string | symbol | undefined) => AnyFn,
+): AnyFn {
   return function (this: unknown, ...args: unknown[]): unknown {
     patchMethodDescriptor(
       args[0] as { __SENTRY_INTERNAL__?: boolean } | undefined,
@@ -185,13 +190,30 @@ export function subscribeToNestChannels(): void {
 
   // @Cron/@Interval/@Timeout (schedule), @OnEvent (event), @Processor (bullmq)
   subscribeFactoryDecorator(CHANNELS.NESTJS_SCHEDULE_CRON, (decorator, data) => {
-    const cronDecorator = makeMethodDecorator(decorator, handler => wrapScheduleHandler(handler, MECHANISM_CRON));
+    const cronDecorator = makeMethodDecorator(decorator, (handler, target, propertyKey) =>
+      wrapCronHandler(handler, [...(data.arguments || [])], target, propertyKey, data.moduleVersion),
+    );
     return function (this: unknown, ...args: unknown[]): unknown {
       const result = cronDecorator.apply(this, args);
-      setNestScheduleVersion((args[2] as PropertyDescriptor | undefined)?.value, data.moduleVersion);
+      const method = (args[2] as PropertyDescriptor | undefined)?.value;
+      setNestScheduleVersion(method, data.moduleVersion);
+      linkCronOptionsToMonitor(method);
       return result;
     };
   });
+  // `@nestjs/schedule` passes this function to `CronJob` as `onTick`. Mark it when the method already
+  // sends check-ins, so `cronJobIntegration` doesn't send a second set.
+  diagnosticsChannel.tracingChannel<OrchestrionChannelContext>(CHANNELS.NESTJS_SCHEDULE_EXPLORER_WRAP).subscribe({
+    start: NOOP,
+    end(data) {
+      if (typeof data.result === 'function' && sendsCronCheckIns(data.arguments?.[0])) {
+        addNonEnumerableProperty(data.result, Symbol.for('sentry.cron.monitored'), true);
+      }
+    },
+    asyncStart: NOOP,
+    asyncEnd: NOOP,
+    error: NOOP,
+  });
   subscribeFactoryDecorator(CHANNELS.NESTJS_SCHEDULE_INTERVAL, decorator =>
     makeMethodDecorator(decorator, handler => wrapScheduleHandler(handler, MECHANISM_INTERVAL)),
   );