@salesforce/telemetry 6.4.8 → 6.5.0

package/README.md

@@ -56,7 +56,7 @@ const reporter = await TelemetryReporter.create({
   key: 'my-instrumentation-key', // Required for Application Insights
   enableO11y: true,
   o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
-  extensionName: 'my-extension' // Optional, defaults to project name
+  extensionName: 'my-extension', // Optional, defaults to project name
 });
 ```
 
@@ -70,15 +70,15 @@ const reporter = await TelemetryReporter.create({
   enableO11y: true,
   enableAppInsights: false, // Disable AppInsights
   o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
-  extensionName: 'my-extension' // Optional, defaults to project name
+  extensionName: 'my-extension', // Optional, defaults to project name
 });
 ```
 
 **Note:** O11y telemetry respects the same telemetry enablement settings as Application Insights. If telemetry is disabled via `SF_DISABLE_TELEMETRY` or other configuration, O11y events will not be sent.
 
-#### Custom Schema Support
+#### Custom Schema Support (sendTelemetryEventWithSchema)
 
-The telemetry reporter supports consumer-provided O11y schemas. This allows consumers to use custom schemas from the `o11y_schema` package instead of the default `sf_a4dInstrumentation` schema.
+To send events that conform to a specific O11y schema (e.g. PFT/pdpEventSchema), use `sendTelemetryEventWithSchema` instead of passing a schema in config. This keeps default events on the default schema and restricts schema-specific events (e.g. PFT) to the method that accepts a schema per call.
 
 **Step 1: Add `o11y_schema` to your `package.json`:**
 
@@ -90,32 +90,35 @@ The telemetry reporter supports consumer-provided O11y schemas. This allows cons
 }
 ```
 
-**Step 2: Import and pass the schema to the telemetry reporter:**
+**Step 2: Send events with a schema only when needed:**
 
 ```javascript
 import TelemetryReporter from '@salesforce/telemetry';
-// Import the schema object from o11y_schema
-import { a4dInstrumentationSchema } from 'o11y_schema/sf_a4dInstrumentation';
+// Import the schema object from o11y_schema (e.g. for PFT events)
+import { pdpEventSchema } from 'o11y_schema/sf_pdpEvent';
 
 const reporter = await TelemetryReporter.create({
   project: 'my-project-name',
   enableO11y: true,
   o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
-  o11ySchema: a4dInstrumentationSchema, // Pass the schema object
-  extensionName: 'my-extension'
+  extensionName: 'my-extension',
 });
 
 reporter.start();
+// Default events use the default schema
 reporter.sendTelemetryEvent('event-name', { foo: 'bar' });
+// PFT or other schema-specific events: pass schema per call
+reporter.sendTelemetryEventWithSchema('pftEventName', { userId: 'user-1', action: 'view' }, pdpEventSchema);
 ```
 
-**Note:** When `o11ySchema` is provided, the reporter will use `logEventWithSchema()` to log events with your custom schema. If `o11ySchema` is not provided, it falls back to the default `sf_a4dInstrumentation` schema.
+**Note:** `sendTelemetryEventWithSchema` sends only to O11y (not AppInsights). Use it for events that must conform to a given schema; use `sendTelemetryEvent` for all other events.
 
-**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.
+**Note:** The `o11y_schema` package may not provide TypeScript declarations. If your TypeScript configuration doesn't include `skipLibCheck: true`, you may need type declarations or `@ts-expect-error` for schema imports.
 
 #### 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)
@@ -131,8 +134,8 @@ const reporter = await TelemetryReporter.create({
     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)
-  }
+    enableBeforeExitHook: true, // Default: true (may not fire for STDIO servers)
+  },
 });
 ```
 
@@ -144,8 +147,8 @@ const reporter = await TelemetryReporter.create({
   enableO11y: true,
   o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
   o11yBatching: {
-    enableAutoBatching: false // Events will be uploaded immediately
-  }
+    enableAutoBatching: false, // Events will be uploaded immediately
+  },
 });
 ```
 

package/lib/o11yReporter.d.ts

@@ -6,7 +6,6 @@ export declare class O11yReporter extends BaseReporter {
     private initialized;
     private commonProperties;
     private extensionName;
-    private customSchema;
     private _batchingCleanup;
     private _batchingEnabled;
     constructor(options: TelemetryOptions);
@@ -36,6 +35,17 @@ export declare class O11yReporter extends BaseReporter {
      */
     isBatchingEnabled(): boolean;
     sendTelemetryEvent(eventName: string, attributes?: Attributes): Promise<void>;
+    /**
+     * Sends a telemetry event with a specific O11y schema.
+     * Use this method when you need to send events that conform to a particular schema
+     * (e.g. PFT/pdpEventSchema). Only the events you send via this method use the given schema;
+     * all other events use the default schema via sendTelemetryEvent.
+     *
+     * @param eventName - Name of the event
+     * @param attributes - Properties and measurements to publish alongside the event
+     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     */
+    sendTelemetryEventWithSchema(eventName: string, attributes: Attributes, schema: O11ySchema): Promise<void>;
     flush(): Promise<void>;
     /**
      * Publishes exception to O11y service
@@ -59,13 +69,5 @@ export declare class O11yReporter extends BaseReporter {
      * @param properties {Properties} - map of properties to publish alongside the event.
      */
     sendTelemetryMetric(metricName: string, value: number, properties?: Properties): Promise<void>;
-    /**
-     * Gets the currently loaded schema object
-     */
-    getCurrentSchema(): O11ySchema | null;
-    /**
-     * Checks if a custom schema is being used
-     */
-    hasCustomSchema(): boolean;
     private buildO11yCommonProperties;
 }

package/lib/o11yReporter.js

@@ -24,15 +24,12 @@ class O11yReporter extends baseReporter_1.BaseReporter {
     initialized;
     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;
         this.service = o11y_reporter_1.O11yService.getInstance(this.extensionName);
-        // Store the schema object provided by consumer (if any)
-        this.customSchema = options.o11ySchema ?? null;
         this.initialized = this.service.initialize(this.extensionName, options.o11yUploadEndpoint);
         this.commonProperties = this.buildO11yCommonProperties(options.commonProperties);
     }
@@ -78,13 +75,7 @@ class O11yReporter extends baseReporter_1.BaseReporter {
             eventName: `${this.extensionName}/${eventName}`,
             ...merged,
         };
-        // Use logEventWithSchema if custom schema is loaded, otherwise use default logEvent
-        if (this.customSchema) {
-            this.service.logEventWithSchema(eventData, this.customSchema);
-        }
-        else {
-            this.service.logEvent(eventData);
-        }
+        this.service.logEvent(eventData);
         // If batching is not enabled, upload immediately for backward compatibility
         if (!this._batchingEnabled) {
             await this.service.forceFlush();
@@ -92,6 +83,28 @@ class O11yReporter extends baseReporter_1.BaseReporter {
         // If batching is enabled, events will be automatically uploaded based on
         // threshold (50KB) or periodic flush interval.
     }
+    /**
+     * Sends a telemetry event with a specific O11y schema.
+     * Use this method when you need to send events that conform to a particular schema
+     * (e.g. PFT/pdpEventSchema). Only the events you send via this method use the given schema;
+     * all other events use the default schema via sendTelemetryEvent.
+     *
+     * @param eventName - Name of the event
+     * @param attributes - Properties and measurements to publish alongside the event
+     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     */
+    async sendTelemetryEventWithSchema(eventName, attributes, schema) {
+        await this.initialized;
+        const merged = { ...this.commonProperties, ...attributes };
+        const eventData = {
+            eventName: `${this.extensionName}/${eventName}`,
+            ...merged,
+        };
+        this.service.logEventWithSchema(eventData, schema);
+        if (!this._batchingEnabled) {
+            await this.service.forceFlush();
+        }
+    }
     async flush() {
         // Wait for initialization to complete before using the service
         await this.initialized;
@@ -118,13 +131,7 @@ class O11yReporter extends baseReporter_1.BaseReporter {
             ...properties,
             ...measurements,
         };
-        // Use custom schema if available
-        if (this.customSchema) {
-            this.service.logEventWithSchema(exceptionEvent, this.customSchema);
-        }
-        else {
-            this.service.logEvent(exceptionEvent);
-        }
+        this.service.logEvent(exceptionEvent);
         // If batching is not enabled, upload immediately for backward compatibility
         if (!this._batchingEnabled) {
             await this.service.forceFlush();
@@ -146,12 +153,7 @@ class O11yReporter extends baseReporter_1.BaseReporter {
             message: traceMessage,
             ...merged,
         };
-        if (this.customSchema) {
-            this.service.logEventWithSchema(traceEvent, this.customSchema);
-        }
-        else {
-            this.service.logEvent(traceEvent);
-        }
+        this.service.logEvent(traceEvent);
         // If batching is not enabled, upload immediately for backward compatibility
         if (!this._batchingEnabled) {
             await this.service.forceFlush();
@@ -173,29 +175,12 @@ class O11yReporter extends baseReporter_1.BaseReporter {
             value,
             ...merged,
         };
-        if (this.customSchema) {
-            this.service.logEventWithSchema(metricEvent, this.customSchema);
-        }
-        else {
-            this.service.logEvent(metricEvent);
-        }
+        this.service.logEvent(metricEvent);
         // If batching is not enabled, upload immediately for backward compatibility
         if (!this._batchingEnabled) {
             await this.service.forceFlush();
         }
     }
-    /**
-     * Gets the currently loaded schema object
-     */
-    getCurrentSchema() {
-        return this.customSchema;
-    }
-    /**
-     * Checks if a custom schema is being used
-     */
-    hasCustomSchema() {
-        return this.customSchema !== null;
-    }
     buildO11yCommonProperties(extra) {
         const baseProperties = this.buildCommonProperties(extra);
         baseProperties['common.extensionName'] = this.extensionName;

package/lib/telemetryReporter.d.ts

@@ -1,7 +1,7 @@
 import { AsyncCreatable } from '@salesforce/kit';
 import type { BatchingOptions } from '@salesforce/o11y-reporter';
 import { TelemetryClient } from './appInsights';
-import { Attributes, Properties, TelemetryOptions } from './types';
+import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
 /**
  * This is the main telemetry reporter that should be used by consumers.
  * It will check if telemetry is disabled and do GDPR checks.
@@ -34,6 +34,16 @@ export declare class TelemetryReporter extends AsyncCreatable<TelemetryOptions>
     stop(): void;
     waitForConnection(): Promise<void>;
     testConnection(): Promise<boolean>;
+    /**
+     * Sends a telemetry event to O11y only with a specific schema.
+     * Use this for events that must conform to a given schema (e.g. PFT/pdpEventSchema).
+     * Does not send to AppInsights. Only sends when O11y is enabled and reporter is initialized.
+     *
+     * @param eventName - Name of the event
+     * @param attributes - Properties and measurements to publish alongside the event
+     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     */
+    sendTelemetryEventWithSchema(eventName: string, attributes: Attributes, schema: O11ySchema): void;
     /**
      * Sends message to both AppInsights and O11y (if enabled).
      *

package/lib/telemetryReporter.js

@@ -187,6 +187,22 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
             return false;
         }
     }
+    /**
+     * Sends a telemetry event to O11y only with a specific schema.
+     * Use this for events that must conform to a given schema (e.g. PFT/pdpEventSchema).
+     * Does not send to AppInsights. Only sends when O11y is enabled and reporter is initialized.
+     *
+     * @param eventName - Name of the event
+     * @param attributes - Properties and measurements to publish alongside the event
+     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     */
+    sendTelemetryEventWithSchema(eventName, attributes, schema) {
+        if (this.isSfdxTelemetryEnabled() && this.enableO11y && this.o11yReporter) {
+            void this.o11yReporter.sendTelemetryEventWithSchema(eventName, attributes, schema).catch((error) => {
+                this.logger.debug('Failed to send event with schema to O11y:', error);
+            });
+        }
+    }
     /**
      * Sends message to both AppInsights and O11y (if enabled).
      *

package/lib/types.d.ts

@@ -63,7 +63,6 @@ export type TelemetryOptions = {
     enableO11y?: boolean;
     enableAppInsights?: boolean;
     extensionName?: string;
-    o11ySchema?: O11ySchema;
     /**
      * Batching configuration for O11y telemetry
      * Batching is enabled by default. Set o11yBatching.enableAutoBatching to false to disable batching

package/package.json

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