feat(core): Add cron monitor wrapper helper (#9395)

This PR adds `Sentry.withMonitor`, a wrapping function similar to
`Sentry.startSpan` that wraps a callback with a cron monitor. Under the
hood it uses `Sentry.captureCheckIn`, but having this as a callback
means that users don't have to think about passing `checkInId` around.

```ts
import * as Sentry from '@sentry/node';

// with monitor will send checkin when callback is started/finished
// works with async and sync callbacks.
const result = Sentry.withMonitor(
  'dailyEmail',
  () => {
    // withCheckIn return value is same return value here
    return sendEmail();
  },
  {
    schedule: {
      type: 'crontab',
      value: '0 * * * *',
    },
    // 🇨🇦🫡
    timezone: 'Canada/Eastern',
  },
);
```

packages/astro/src/index.server.ts

@@ -13,6 +13,7 @@ export {
   captureEvent,
   captureMessage,
   captureCheckIn,
+  withMonitor,
   configureScope,
   createTransport,
   extractTraceparentData,

packages/bun/src/index.ts

@@ -55,6 +55,7 @@ export {
   trace,
   withScope,
   captureCheckIn,
+  withMonitor,
   setMeasurement,
   getActiveSpan,
   startSpan,

packages/core/src/exports.ts

@@ -7,14 +7,15 @@ import type {
   EventHint,
   Extra,
   Extras,
+  FinishedCheckIn,
   MonitorConfig,
   Primitive,
   Severity,
   SeverityLevel,
   TransactionContext,
   User,
 } from '@sentry/types';
-import { logger, uuid4 } from '@sentry/utils';
+import { isThenable, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 
 import type { Hub } from './hub';
 import { getCurrentHub } from './hub';
@@ -210,6 +211,49 @@ export function captureCheckIn(checkIn: CheckIn, upsertMonitorConfig?: MonitorCo
   return uuid4();
 }
 
+/**
+ * Wraps a callback with a cron monitor check in. The check in will be sent to Sentry when the callback finishes.
+ *
+ * @param monitorSlug The distinct slug of the monitor.
+ * @param upsertMonitorConfig An optional object that describes a monitor config. Use this if you want
+ * to create a monitor automatically when sending a check in.
+ */
+export function withMonitor<T>(
+  monitorSlug: CheckIn['monitorSlug'],
+  callback: () => T,
+  upsertMonitorConfig?: MonitorConfig,
+): T {
+  const checkInId = captureCheckIn({ monitorSlug, status: 'in_progress' }, upsertMonitorConfig);
+  const now = timestampInSeconds();
+
+  function finishCheckIn(status: FinishedCheckIn['status']): void {
+    captureCheckIn({ monitorSlug, status, checkInId, duration: timestampInSeconds() - now });
+  }
+
+  let maybePromiseResult: T;
+  try {
+    maybePromiseResult = callback();
+  } catch (e) {
+    finishCheckIn('error');
+    throw e;
+  }
+
+  if (isThenable(maybePromiseResult)) {
+    Promise.resolve(maybePromiseResult).then(
+      () => {
+        finishCheckIn('ok');
+      },
+      () => {
+        finishCheckIn('error');
+      },
+    );
+  } else {
+    finishCheckIn('ok');
+  }
+
+  return maybePromiseResult;
+}
+
 /**
  * Call `flush()` on the current client, if there is one. See {@link Client.flush}.
  *

packages/core/src/index.ts

@@ -7,6 +7,7 @@ export * from './tracing';
 export {
   addBreadcrumb,
   captureCheckIn,
+  withMonitor,
   captureException,
   captureEvent,
   captureMessage,

packages/deno/src/index.ts

@@ -53,6 +53,7 @@ export {
   trace,
   withScope,
   captureCheckIn,
+  withMonitor,
   setMeasurement,
   getActiveSpan,
   startSpan,

packages/node-experimental/src/index.ts

@@ -51,6 +51,7 @@ export {
   trace,
   withScope,
   captureCheckIn,
+  withMonitor,
 } from '@sentry/node';
 
 export type {

packages/node/src/index.ts

@@ -55,6 +55,7 @@ export {
   trace,
   withScope,
   captureCheckIn,
+  withMonitor,
   setMeasurement,
   getActiveSpan,
   startSpan,

packages/remix/src/index.server.ts

@@ -13,6 +13,7 @@ export {
   addGlobalEventProcessor,
   addBreadcrumb,
   captureCheckIn,
+  withMonitor,
   captureException,
   captureEvent,
   captureMessage,

packages/serverless/src/index.ts

@@ -21,6 +21,7 @@ export {
   captureException,
   captureMessage,
   captureCheckIn,
+  withMonitor,
   configureScope,
   createTransport,
   getActiveTransaction,

packages/sveltekit/src/server/index.ts

@@ -11,6 +11,7 @@ export {
   captureEvent,
   captureMessage,
   captureCheckIn,
+  withMonitor,
   configureScope,
   createTransport,
   extractTraceparentData,

packages/types/src/checkin.ts

@@ -43,7 +43,7 @@ export interface SerializedCheckIn {
   };
 }
 
-interface InProgressCheckIn {
+export interface InProgressCheckIn {
   // The distinct slug of the monitor.
   monitorSlug: SerializedCheckIn['monitor_slug'];
   // The status of the check-in.

packages/types/src/index.ts

@@ -125,4 +125,4 @@ export type { Instrumenter } from './instrumenter';
 export type { HandlerDataFetch, HandlerDataXhr, SentryXhrData, SentryWrappedXMLHttpRequest } from './instrument';
 
 export type { BrowserClientReplayOptions, BrowserClientProfilingOptions } from './browseroptions';
-export type { CheckIn, MonitorConfig, SerializedCheckIn } from './checkin';
+export type { CheckIn, MonitorConfig, FinishedCheckIn, InProgressCheckIn, SerializedCheckIn } from './checkin';

packages/vercel-edge/src/index.ts

@@ -54,6 +54,7 @@ export {
   trace,
   withScope,
   captureCheckIn,
+  withMonitor,
   setMeasurement,
   getActiveSpan,
   startSpan,