@salesforce/telemetry 6.3.1 → 6.4.1

package/README.md

@@ -113,6 +113,51 @@ reporter.sendTelemetryEvent('event-name', { foo: 'bar' });
 
 **Note:** The `o11y_schema` package doesn't provide TypeScript declarations. If your TypeScript configuration doesn't include `skipLibCheck: true`, you may need to add type declarations or use `@ts-expect-error` comments. However, with proper TypeScript configuration, the import should work without additional annotations.
 
+#### O11y Telemetry Batching
+
+O11y telemetry supports automatic batching of events to improve performance and reduce network overhead. By default, batching is enabled with a 30-second flush interval. Events are automatically uploaded when:
+- The buffer reaches 50KB in size, or
+- The flush interval (default: 30 seconds) elapses, or
+- The process exits (via shutdown hooks)
+
+You can configure batching options during initialization:
+
+```javascript
+const reporter = await TelemetryReporter.create({
+  project: 'my-project-name',
+  enableO11y: true,
+  o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
+  o11yBatching: {
+    enableAutoBatching: true, // Default: true
+    flushInterval: 60_000, // 60 seconds (default: 30_000)
+    enableShutdownHook: true, // Default: true
+    enableBeforeExitHook: true // Default: true (may not fire for STDIO servers)
+  }
+});
+```
+
+To disable batching and upload events immediately after each event:
+
+```javascript
+const reporter = await TelemetryReporter.create({
+  project: 'my-project-name',
+  enableO11y: true,
+  o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
+  o11yBatching: {
+    enableAutoBatching: false // Events will be uploaded immediately
+  }
+});
+```
+
+You can also manually flush buffered events when needed (e.g., before critical operations or shutdown):
+
+```javascript
+// Manually flush buffered events
+await reporter.flush();
+```
+
+**Note:** When batching is disabled, events are uploaded immediately after each `sendTelemetryEvent()`, `sendTelemetryException()`, `sendTelemetryTrace()`, or `sendTelemetryMetric()` call for backward compatibility.
+
 ## Env Variables
 
 `SF_DISABLE_TELEMETRY`: Set to `true` if you want to disable telemetry.

package/lib/exported.d.ts

@@ -2,4 +2,4 @@ import { TelemetryReporter } from './telemetryReporter';
 export * from './telemetryReporter';
 export { isEnabled } from './enabledCheck';
 export default TelemetryReporter;
-export type { Attributes, O11ySchema } from './types';
+export type { Attributes, O11ySchema, O11yBatchingConfig } from './types';

package/lib/o11yReporter.d.ts

@@ -1,3 +1,4 @@
+import { type BatchingOptions } from '@salesforce/o11y-reporter';
 import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
 import { BaseReporter } from './baseReporter';
 export declare class O11yReporter extends BaseReporter {
@@ -6,8 +7,34 @@ export declare class O11yReporter extends BaseReporter {
     private commonProperties;
     private extensionName;
     private customSchema;
+    private _batchingCleanup;
+    private _batchingEnabled;
     constructor(options: TelemetryOptions);
     init(): Promise<void>;
+    /**
+     * Enable automatic batching with periodic flush and shutdown hooks
+     *
+     * Consumers can call this method to enable batching with custom options.
+     * If batching is not enabled, events will be buffered but not automatically uploaded.
+     * Use flush() to manually upload events when batching is disabled.
+     *
+     * @param options - Batching configuration options
+     * @returns Cleanup function to stop batching and remove hooks
+     *
+     * @example
+     * ```typescript
+     * await reporter.init();
+     * const cleanup = reporter.enableAutoBatching({
+     *   flushInterval: 30_000, // 30 seconds
+     *   enableShutdownHook: true,
+     * });
+     * ```
+     */
+    enableAutoBatching(options?: BatchingOptions): () => void;
+    /**
+     * Check if auto-batching is currently enabled
+     */
+    isBatchingEnabled(): boolean;
     sendTelemetryEvent(eventName: string, attributes?: Attributes): Promise<void>;
     flush(): Promise<void>;
     /**

package/lib/o11yReporter.js

@@ -25,6 +25,8 @@ class O11yReporter extends baseReporter_1.BaseReporter {
     commonProperties;
     extensionName = '';
     customSchema = null; // Schema object provided by consumer
+    _batchingCleanup = null; // Cleanup function for auto-batching
+    _batchingEnabled = false; // Track if batching is enabled
     constructor(options) {
         super(options);
         this.extensionName = options.extensionName ?? options.project;
@@ -37,6 +39,36 @@ class O11yReporter extends baseReporter_1.BaseReporter {
     async init() {
         await this.initialized;
     }
+    /**
+     * Enable automatic batching with periodic flush and shutdown hooks
+     *
+     * Consumers can call this method to enable batching with custom options.
+     * If batching is not enabled, events will be buffered but not automatically uploaded.
+     * Use flush() to manually upload events when batching is disabled.
+     *
+     * @param options - Batching configuration options
+     * @returns Cleanup function to stop batching and remove hooks
+     *
+     * @example
+     * ```typescript
+     * await reporter.init();
+     * const cleanup = reporter.enableAutoBatching({
+     *   flushInterval: 30_000, // 30 seconds
+     *   enableShutdownHook: true,
+     * });
+     * ```
+     */
+    enableAutoBatching(options) {
+        this._batchingEnabled = true;
+        this._batchingCleanup = this.service.enableAutoBatching(options);
+        return this._batchingCleanup;
+    }
+    /**
+     * Check if auto-batching is currently enabled
+     */
+    isBatchingEnabled() {
+        return this._batchingEnabled;
+    }
     async sendTelemetryEvent(eventName, attributes = {}) {
         // Wait for initialization to complete before using the service
         await this.initialized;
@@ -53,12 +85,18 @@ class O11yReporter extends baseReporter_1.BaseReporter {
         else {
             this.service.logEvent(eventData);
         }
-        await this.service.upload();
+        // If batching is not enabled, upload immediately for backward compatibility
+        if (!this._batchingEnabled) {
+            await this.service.forceFlush();
+        }
+        // If batching is enabled, events will be automatically uploaded based on
+        // threshold (50KB) or periodic flush interval.
     }
     async flush() {
         // Wait for initialization to complete before using the service
         await this.initialized;
-        await this.service.upload();
+        // Use forceFlush for explicit manual flush
+        await this.service.forceFlush();
     }
     /**
      * Publishes exception to O11y service
@@ -87,7 +125,12 @@ class O11yReporter extends baseReporter_1.BaseReporter {
         else {
             this.service.logEvent(exceptionEvent);
         }
-        await this.service.upload();
+        // If batching is not enabled, upload immediately for backward compatibility
+        if (!this._batchingEnabled) {
+            await this.service.forceFlush();
+        }
+        // If batching is enabled, events will be automatically uploaded based on
+        // threshold (50KB) or periodic flush interval.
     }
     /**
      * Publishes diagnostic information to O11y service
@@ -98,18 +141,21 @@ class O11yReporter extends baseReporter_1.BaseReporter {
     async sendTelemetryTrace(traceMessage, properties = {}) {
         await this.initialized;
         const merged = { ...this.commonProperties, ...properties };
-        const eventData = {
+        const traceEvent = {
             eventName: `${this.extensionName}/trace`,
             message: traceMessage,
             ...merged,
         };
         if (this.customSchema) {
-            this.service.logEventWithSchema(eventData, this.customSchema);
+            this.service.logEventWithSchema(traceEvent, this.customSchema);
         }
         else {
-            this.service.logEvent(eventData);
+            this.service.logEvent(traceEvent);
+        }
+        // If batching is not enabled, upload immediately for backward compatibility
+        if (!this._batchingEnabled) {
+            await this.service.forceFlush();
         }
-        await this.service.upload();
     }
     /**
      * Publishes metric to O11y service
@@ -121,19 +167,22 @@ class O11yReporter extends baseReporter_1.BaseReporter {
     async sendTelemetryMetric(metricName, value, properties = {}) {
         await this.initialized;
         const merged = { ...this.commonProperties, ...properties };
-        const eventData = {
+        const metricEvent = {
             eventName: `${this.extensionName}/metric`,
             metricName,
             value,
             ...merged,
         };
         if (this.customSchema) {
-            this.service.logEventWithSchema(eventData, this.customSchema);
+            this.service.logEventWithSchema(metricEvent, this.customSchema);
         }
         else {
-            this.service.logEvent(eventData);
+            this.service.logEvent(metricEvent);
+        }
+        // If batching is not enabled, upload immediately for backward compatibility
+        if (!this._batchingEnabled) {
+            await this.service.forceFlush();
         }
-        await this.service.upload();
     }
     /**
      * Gets the currently loaded schema object

package/lib/telemetryReporter.d.ts

@@ -1,4 +1,5 @@
 import { AsyncCreatable } from '@salesforce/kit';
+import type { BatchingOptions } from '@salesforce/o11y-reporter';
 import { TelemetryClient } from './appInsights';
 import { Attributes, Properties, TelemetryOptions } from './types';
 /**
@@ -74,4 +75,42 @@ export declare class TelemetryReporter extends AsyncCreatable<TelemetryOptions>
      * NOT be used to send events as it will by pass disabled checks.
      */
     getTelemetryClient(): TelemetryClient;
+    /**
+     * Enable automatic batching for O11y telemetry events.
+     *
+     * This method allows consumers to configure batching options for O11y telemetry.
+     * If batching is not enabled, events will be buffered but not automatically uploaded.
+     * Use flush() to manually upload events when batching is disabled.
+     *
+     * Note: Auto-batching is enabled by default with 30-second flush interval during init().
+     * Calling this method will override the default batching configuration.
+     *
+     * @param options - Batching configuration options
+     * @returns Cleanup function to stop batching and remove hooks, or undefined if O11y is not enabled
+     *
+     * @example
+     * ```typescript
+     * const cleanup = reporter.enableAutoBatching({
+     *   flushInterval: 60_000, // 60 seconds
+     *   enableShutdownHook: true,
+     * });
+     * ```
+     */
+    enableAutoBatching(options?: BatchingOptions): (() => void) | undefined;
+    /**
+     * Force an immediate flush of buffered O11y telemetry events.
+     *
+     * This method triggers an immediate upload of all currently buffered telemetry events.
+     * It's useful for ensuring critical events are sent immediately, or for
+     * flushing remaining events before an application exits.
+     *
+     * @returns Promise that resolves when the upload completes, or undefined if O11y is not enabled
+     *
+     * @example
+     * ```typescript
+     * // Flush events before critical operation
+     * await reporter.flush();
+     * ```
+     */
+    flush(): Promise<void>;
 }

package/lib/telemetryReporter.js

@@ -105,7 +105,25 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
             if (this.options.o11yUploadEndpoint) {
                 try {
                     this.o11yReporter = new o11yReporter_1.O11yReporter(this.options);
-                    this.logger.debug('O11y reporter initialized successfully');
+                    await this.o11yReporter.init();
+                    // Configure batching - enabled by default unless explicitly disabled
+                    const batchingConfig = this.options.o11yBatching;
+                    // Batching is enabled by default. Only disable if explicitly set to false
+                    const enableAutoBatching = batchingConfig?.enableAutoBatching !== false;
+                    if (enableAutoBatching) {
+                        // Enable auto-batching with provided options or defaults
+                        const batchingOptions = {
+                            flushInterval: batchingConfig?.flushInterval ?? 30_000, // 30 seconds default
+                            enableShutdownHook: batchingConfig?.enableShutdownHook ?? true,
+                            enableBeforeExitHook: batchingConfig?.enableBeforeExitHook,
+                        };
+                        this.o11yReporter.enableAutoBatching(batchingOptions);
+                        this.logger.debug('O11y reporter initialized with auto-batching enabled (default)');
+                    }
+                    else {
+                        // Batching explicitly disabled - events will be uploaded immediately after each event
+                        this.logger.debug('O11y reporter initialized with auto-batching disabled (immediate uploads)');
+                    }
                 }
                 catch (error) {
                     this.logger.warn('Failed to initialize O11y reporter:', error);
@@ -273,6 +291,56 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
         }
         return this.reporter.appInsightsClient;
     }
+    /**
+     * Enable automatic batching for O11y telemetry events.
+     *
+     * This method allows consumers to configure batching options for O11y telemetry.
+     * If batching is not enabled, events will be buffered but not automatically uploaded.
+     * Use flush() to manually upload events when batching is disabled.
+     *
+     * Note: Auto-batching is enabled by default with 30-second flush interval during init().
+     * Calling this method will override the default batching configuration.
+     *
+     * @param options - Batching configuration options
+     * @returns Cleanup function to stop batching and remove hooks, or undefined if O11y is not enabled
+     *
+     * @example
+     * ```typescript
+     * const cleanup = reporter.enableAutoBatching({
+     *   flushInterval: 60_000, // 60 seconds
+     *   enableShutdownHook: true,
+     * });
+     * ```
+     */
+    enableAutoBatching(options) {
+        if (!this.o11yReporter) {
+            this.logger.debug('O11y reporter is not initialized. enableAutoBatching() has no effect.');
+            return undefined;
+        }
+        return this.o11yReporter.enableAutoBatching(options);
+    }
+    /**
+     * Force an immediate flush of buffered O11y telemetry events.
+     *
+     * This method triggers an immediate upload of all currently buffered telemetry events.
+     * It's useful for ensuring critical events are sent immediately, or for
+     * flushing remaining events before an application exits.
+     *
+     * @returns Promise that resolves when the upload completes, or undefined if O11y is not enabled
+     *
+     * @example
+     * ```typescript
+     * // Flush events before critical operation
+     * await reporter.flush();
+     * ```
+     */
+    async flush() {
+        if (!this.o11yReporter) {
+            this.logger.debug('O11y reporter is not initialized. flush() has no effect.');
+            return;
+        }
+        await this.o11yReporter.flush();
+    }
 }
 exports.TelemetryReporter = TelemetryReporter;
 //# sourceMappingURL=telemetryReporter.js.map

package/lib/types.d.ts

@@ -15,6 +15,32 @@ export type Attributes = {
  * (not a primitive, null, or undefined).
  */
 export type O11ySchema = Record<string, unknown>;
+/**
+ * Batching configuration for O11y telemetry
+ *
+ * Batching is enabled by default. Set enableAutoBatching to false to disable batching
+ * and upload events immediately after each event.
+ */
+export type O11yBatchingConfig = {
+    /**
+     * Enable automatic batching of events (default: true)
+     * Set to false to disable batching and upload events immediately after each event.
+     * If not specified, batching is enabled by default.
+     */
+    enableAutoBatching?: boolean;
+    /**
+     * Periodic flush interval in milliseconds (default: 30000)
+     */
+    flushInterval?: number;
+    /**
+     * Enable shutdown hooks (default: true)
+     */
+    enableShutdownHook?: boolean;
+    /**
+     * Enable beforeExit hook (default: true). Note: beforeExit won't fire for STDIO servers where stdin stays open
+     */
+    enableBeforeExitHook?: boolean;
+};
 export type TelemetryOptions = {
     project: string;
     key: string;
@@ -30,4 +56,10 @@ export type TelemetryOptions = {
     enableAppInsights?: boolean;
     extensionName?: string;
     o11ySchema?: O11ySchema;
+    /**
+     * Batching configuration for O11y telemetry
+     * Batching is enabled by default. Set o11yBatching.enableAutoBatching to false to disable batching
+     * and upload events immediately after each event.
+     */
+    o11yBatching?: O11yBatchingConfig;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/telemetry",
-  "version": "6.3.1",
+  "version": "6.4.1",
   "description": "Library for telemetry reporting to Application Insights and O11y",
   "main": "lib/exported",
   "exports": {