Enhance ANR integration documentation and add detailed comments

Co-authored-by: aprasad <[email protected]>

Author: cursoragent

packages/node/src/integrations/anr/common.ts

@@ -1,43 +1,73 @@
 import type { Contexts, DsnComponents, Primitive, SdkMetadata } from '@sentry/core';
 
 /**
+ * Configuration options for the ANR (Application Not Responding) integration.
+ *
+ * These options control how the ANR detection system monitors the Node.js event loop
+ * and reports blocking events.
+ *
  * @deprecated The ANR integration has been deprecated. Use `eventLoopBlockIntegration` from `@sentry/node-native` instead.
+ * @see {@link https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/application-not-responding/}
  */
 export interface AnrIntegrationOptions {
   /**
-   * Interval to send heartbeat messages to the ANR worker.
+   * Interval to send heartbeat messages to the ANR worker thread.
    *
-   * Defaults to 50ms.
+   * The main thread sends heartbeat messages to the worker thread at this interval
+   * to indicate that the event loop is still responsive. Lower values provide more
+   * precise detection but may increase overhead.
+   *
+   * @default 50 (milliseconds)
    */
   pollInterval: number;
+
   /**
    * Threshold in milliseconds to trigger an ANR event.
    *
-   * Defaults to 5000ms.
+   * When the worker thread doesn't receive a heartbeat message for this duration,
+   * it considers the main thread to be blocked and triggers an ANR event.
+   *
+   * @default 5000 (milliseconds)
    */
   anrThreshold: number;
+
   /**
    * Whether to capture a stack trace when the ANR event is triggered.
    *
-   * Defaults to `false`.
+   * When enabled, uses the Node.js inspector API to capture the stack trace
+   * of the blocking code. This provides more detailed information about what
+   * caused the ANR but requires the debugger to be enabled.
+   *
+   * **Note:** This opens the inspector API and required ports.
    *
-   * This uses the node debugger which enables the inspector API and opens the required ports.
+   * @default false
    */
   captureStackTrace: boolean;
+
   /**
-   * Maximum number of ANR events to send.
+   * Maximum number of ANR events to send per application session.
+   *
+   * Once this limit is reached, the ANR worker thread will exit to prevent
+   * sending duplicate events. This helps avoid spamming Sentry with repeated
+   * ANR events from the same blocking issue.
    *
-   * Defaults to 1.
+   * @default 1
    */
   maxAnrEvents: number;
+
   /**
-   * Tags to include with ANR events.
+   * Static tags to include with all ANR events.
+   *
+   * These tags will be attached to every ANR event sent by this integration,
+   * useful for categorizing or filtering ANR events in Sentry.
    */
   staticTags: { [key: string]: Primitive };
+
   /**
    * @ignore Internal use only.
    *
    * If this is supplied, stack frame filenames will be rewritten to be relative to this path.
+   * This is used internally for better stack trace readability.
    */
   appRootPath: string | undefined;
 }

packages/node/src/integrations/anr/index.ts

@@ -117,7 +117,55 @@ const _anrIntegration = ((options: Partial<AnrIntegrationOptions> = {}) => {
 type AnrReturn = (options?: Partial<AnrIntegrationOptions>) => Integration & AnrInternal;
 
 /**
+ * Application Not Responding (ANR) integration for Node.js applications.
+ *
+ * Detects when the Node.js main thread event loop is blocked for more than the configured
+ * threshold (5 seconds by default) and reports these as Sentry events.
+ *
+ * ## How it works
+ *
+ * ANR detection uses a worker thread to monitor the event loop in the main app thread.
+ * The main app thread sends a heartbeat message to the ANR worker thread every 50ms by default.
+ * If the ANR worker does not receive a heartbeat message for the configured threshold duration,
+ * it triggers an ANR event.
+ *
+ * ## Requirements
+ *
+ * - Node.js 16.17.0 or higher
+ * - Only supported in the Node.js runtime (not browsers)
+ * - Not supported for Node.js clusters
+ *
+ * ## Performance Impact
+ *
+ * Overhead should be minimal:
+ * - Main thread: Only polling the ANR worker over IPC every 50ms
+ * - Worker thread: Consumes around 10-20 MB of RAM
+ * - When ANR detected: Brief pause in debugger to capture stack trace (negligible compared to the blocking)
+ *
+ * ## Configuration Options
+ *
+ * - `pollInterval`: Interval to send heartbeat messages (default: 50ms)
+ * - `anrThreshold`: Threshold in milliseconds to trigger an ANR event (default: 5000ms)
+ * - `captureStackTrace`: Whether to capture stack traces using the Node.js inspector API (default: false)
+ * - `maxAnrEvents`: Maximum number of ANR events to send (default: 1)
+ * - `staticTags`: Tags to include with ANR events
+ *
+ * @example
+ * ```javascript
+ * Sentry.init({
+ *   dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
+ *   integrations: [
+ *     Sentry.anrIntegration({
+ *       anrThreshold: 5000,
+ *       captureStackTrace: true,
+ *       pollInterval: 50,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
  * @deprecated The ANR integration has been deprecated. Use `eventLoopBlockIntegration` from `@sentry/node-native` instead.
+ * @see {@link https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/application-not-responding/}
  */
 export const anrIntegration = defineIntegration(_anrIntegration) as AnrReturn;
 
@@ -232,8 +280,48 @@ async function _startWorker(
 export function disableAnrDetectionForCallback<T>(callback: () => T): T;
 export function disableAnrDetectionForCallback<T>(callback: () => Promise<T>): Promise<T>;
 /**
- * Disables ANR detection for the duration of the callback
+ * Temporarily disables ANR detection for the duration of a callback function.
+ *
+ * This utility function allows you to disable ANR detection during operations that
+ * are expected to block the event loop, such as intensive computational tasks or
+ * synchronous I/O operations.
+ *
+ * ## Use Cases
+ *
+ * - CPU-intensive operations that legitimately block the event loop
+ * - Synchronous file operations or database queries
+ * - Intentional blocking operations during application startup
+ * - Long-running computations that should not trigger ANR events
+ *
+ * ## Behavior
+ *
+ * - **Synchronous callbacks**: ANR detection is disabled before the callback runs
+ *   and re-enabled immediately after it completes
+ * - **Asynchronous callbacks**: ANR detection is disabled before the callback runs
+ *   and re-enabled after the Promise resolves or rejects
+ * - **No ANR integration**: If the ANR integration is not active, the callback
+ *   runs normally without any modifications
+ *
+ * @example
+ * ```javascript
+ * // For synchronous operations
+ * const result = disableAnrDetectionForCallback(() => {
+ *   // Perform CPU-intensive work that might block for several seconds
+ *   return performHeavyComputation();
+ * });
+ *
+ * // For asynchronous operations
+ * const result = await disableAnrDetectionForCallback(async () => {
+ *   // Perform async work without ANR detection
+ *   return await heavyAsyncOperation();
+ * });
+ * ```
+ *
+ * @param callback - The function to execute with ANR detection disabled
+ * @returns The result of the callback function
+ *
  * @deprecated The ANR integration has been deprecated. Use `eventLoopBlockIntegration` from `@sentry/node-native` instead.
+ * @see {@link https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/application-not-responding/}
  */
 export function disableAnrDetectionForCallback<T>(callback: () => T | Promise<T>): T | Promise<T> {
   const integration = getClient()?.getIntegrationByName(INTEGRATION_NAME) as AnrInternal | undefined;