Merge pull request #483 from forcedotcom/W-21438157-stopAsync-o11y-batching-cleanup

feat: @W-21438157 - add O11yReporter.stop() and TelemetryReporter.stopAsync() for O11y batching cleanup

Author: smuduganti-sf

README.md

@@ -44,6 +44,14 @@ reporter.sendTelemetryEvent('event-name', { foo: 'bar', executionTime: 0.5912 })
 reporter.stop();
 ```
 
+To ensure all buffered events are flushed before process exit (e.g. when using O11y batching), use `stopAsync()`:
+
+```javascript
+// Await shutdown so all events are sent before exiting
+await reporter.stopAsync();
+process.exit(0);
+```
+
 **Note:** For short lived processes, the telemetry can take 0-3 seconds to send all events to the server on stop, and even longer if there is a timeout. It is recommended to send telemetry in a detached spawned process. i.e. `spawn(..., { stdio: 'ignore'}).unref();`
 
 ### O11y (Observability) Telemetry
@@ -159,6 +167,14 @@ You can also manually flush buffered events when needed (e.g., before critical o
 await reporter.flush();
 ```
 
+For graceful shutdown that stops the batching interval and flushes all events, use `stopAsync()`:
+
+```javascript
+// Stop batching, flush remaining events, and dispose
+await reporter.stopAsync();
+process.exit(0);
+```
+
 **Note:** When batching is disabled, events are uploaded immediately after each `sendTelemetryEvent()`, `sendTelemetryException()`, `sendTelemetryTrace()`, or `sendTelemetryMetric()` call for backward compatibility.
 
 ## Env Variables

src/o11yReporter.ts

@@ -162,6 +162,26 @@ export class O11yReporter extends BaseReporter {
     await this.service.forceFlush();
   }
 
+  /**
+   * Stop batching (if enabled), flush any remaining events, and clean up.
+   * Call this before process exit to ensure all events are sent and timers are cleared.
+   *
+   * @example
+   * ```typescript
+   * await reporter.stop();
+   * process.exit(0);
+   * ```
+   */
+  public async stop(): Promise<void> {
+    await this.initialized;
+    if (this._batchingCleanup) {
+      this._batchingCleanup();
+      this._batchingCleanup = null;
+      this._batchingEnabled = false;
+    }
+    await this.service.forceFlush();
+  }
+
   /**
    * Publishes exception to O11y service
    *

src/telemetryReporter.ts

@@ -119,7 +119,22 @@ export class TelemetryReporter extends AsyncCreatable<TelemetryOptions> {
    */
   public stop(): void {
     this.reporter?.stop();
-    void this.o11yReporter?.flush();
+    void this.o11yReporter?.stop();
+  }
+
+  /**
+   * Async version of stop() that awaits O11y cleanup (batching interval stop + flush).
+   * Use this when you need to ensure telemetry is fully shut down before process exit.
+   *
+   * @example
+   * ```typescript
+   * await reporter.stopAsync();
+   * process.exit(0);
+   * ```
+   */
+  public async stopAsync(): Promise<void> {
+    this.reporter?.stop();
+    await this.o11yReporter?.stop();
   }
 
   public async waitForConnection(): Promise<void> {