@salesforce/telemetry 6.2.13 → 6.3.0

package/README.md

@@ -76,6 +76,43 @@ const reporter = await TelemetryReporter.create({
 
 **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
+
+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.
+
+**Step 1: Add `o11y_schema` to your `package.json`:**
+
+```json
+{
+  "dependencies": {
+    "o11y_schema": "^256.154.0"
+  }
+}
+```
+
+**Step 2: Import and pass the schema to the telemetry reporter:**
+
+```javascript
+import TelemetryReporter from '@salesforce/telemetry';
+// Import the schema object from o11y_schema
+import { a4dInstrumentationSchema } from 'o11y_schema/sf_a4dInstrumentation';
+
+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'
+});
+
+reporter.start();
+reporter.sendTelemetryEvent('event-name', { foo: 'bar' });
+```
+
+**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:** 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.
+
 ## 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 } from './types';
+export type { Attributes, O11ySchema } from './types';

package/lib/o11yReporter.d.ts

@@ -1,10 +1,11 @@
-import { Attributes, Properties, TelemetryOptions } from './types';
+import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
 import { BaseReporter } from './baseReporter';
 export declare class O11yReporter extends BaseReporter {
     private service;
     private initialized;
     private commonProperties;
     private extensionName;
+    private customSchema;
     constructor(options: TelemetryOptions);
     init(): Promise<void>;
     sendTelemetryEvent(eventName: string, attributes?: Attributes): Promise<void>;
@@ -31,5 +32,13 @@ 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

@@ -17,17 +17,20 @@ exports.O11yReporter = void 0;
  * limitations under the License.
  */
 const o11y_reporter_1 = require("@salesforce/o11y-reporter");
-const utils_1 = require("./utils");
 const baseReporter_1 = require("./baseReporter");
+const utils_1 = require("./utils");
 class O11yReporter extends baseReporter_1.BaseReporter {
     service;
     initialized;
     commonProperties;
     extensionName = '';
+    customSchema = null; // Schema object provided by consumer
     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);
     }
@@ -38,7 +41,18 @@ class O11yReporter extends baseReporter_1.BaseReporter {
         // Wait for initialization to complete before using the service
         await this.initialized;
         const merged = { ...this.commonProperties, ...attributes };
-        this.service.logEvent({ eventName: `${this.extensionName}/${eventName}`, ...merged });
+        // Create event data
+        const eventData = {
+            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);
+        }
         await this.service.upload();
     }
     async flush() {
@@ -59,14 +73,20 @@ class O11yReporter extends baseReporter_1.BaseReporter {
         const { properties, measurements } = (0, utils_1.buildPropertiesAndMeasurements)(attributes);
         // Create exception event with sanitized error information
         const exceptionEvent = {
-            eventName: 'exception',
+            eventName: `${this.extensionName}/exception`,
             exceptionName: cleanException.name,
             exceptionMessage: cleanException.message,
             exceptionStack: cleanException.stack,
             ...properties,
             ...measurements,
         };
-        this.service.logEvent(exceptionEvent);
+        // Use custom schema if available
+        if (this.customSchema) {
+            this.service.logEventWithSchema(exceptionEvent, this.customSchema);
+        }
+        else {
+            this.service.logEvent(exceptionEvent);
+        }
         await this.service.upload();
     }
     /**
@@ -75,15 +95,20 @@ class O11yReporter extends baseReporter_1.BaseReporter {
      * @param traceMessage {string} - trace message to send to O11y.
      * @param properties {Properties} - map of properties to publish alongside the event.
      */
-    async sendTelemetryTrace(traceMessage, properties) {
-        // Wait for initialization to complete before using the service
+    async sendTelemetryTrace(traceMessage, properties = {}) {
         await this.initialized;
-        const traceEvent = {
-            eventName: 'trace',
+        const merged = { ...this.commonProperties, ...properties };
+        const eventData = {
+            eventName: `${this.extensionName}/trace`,
             message: traceMessage,
-            ...properties,
+            ...merged,
         };
-        this.service.logEvent(traceEvent);
+        if (this.customSchema) {
+            this.service.logEventWithSchema(eventData, this.customSchema);
+        }
+        else {
+            this.service.logEvent(eventData);
+        }
         await this.service.upload();
     }
     /**
@@ -93,18 +118,35 @@ class O11yReporter extends baseReporter_1.BaseReporter {
      * @param value {number} - value of the metric
      * @param properties {Properties} - map of properties to publish alongside the event.
      */
-    async sendTelemetryMetric(metricName, value, properties) {
-        // Wait for initialization to complete before using the service
+    async sendTelemetryMetric(metricName, value, properties = {}) {
         await this.initialized;
-        const metricEvent = {
-            eventName: 'metric',
+        const merged = { ...this.commonProperties, ...properties };
+        const eventData = {
+            eventName: `${this.extensionName}/metric`,
             metricName,
             value,
-            ...properties,
+            ...merged,
         };
-        this.service.logEvent(metricEvent);
+        if (this.customSchema) {
+            this.service.logEventWithSchema(eventData, this.customSchema);
+        }
+        else {
+            this.service.logEvent(eventData);
+        }
         await this.service.upload();
     }
+    /**
+     * 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/types.d.ts

@@ -8,6 +8,13 @@ export type Measurements = {
 export type Attributes = {
     [key: string]: string | number | boolean | null | undefined;
 };
+/**
+ * Basic type for O11y schema objects.
+ * Schemas from o11y_schema package are objects that define the structure
+ * for telemetry events. This type enforces that a schema must be an object
+ * (not a primitive, null, or undefined).
+ */
+export type O11ySchema = Record<string, unknown>;
 export type TelemetryOptions = {
     project: string;
     key: string;
@@ -22,4 +29,5 @@ export type TelemetryOptions = {
     enableO11y?: boolean;
     enableAppInsights?: boolean;
     extensionName?: string;
+    o11ySchema?: O11ySchema;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/telemetry",
-  "version": "6.2.13",
+  "version": "6.3.0",
   "description": "Library for telemetry reporting to Application Insights and O11y",
   "main": "lib/exported",
   "exports": {
@@ -43,7 +43,7 @@
   "dependencies": {
     "@salesforce/core": "^8.23.4",
     "@salesforce/kit": "^3.2.4",
-    "@salesforce/o11y-reporter": "1.3.4",
+    "@salesforce/o11y-reporter": "1.4.0",
     "applicationinsights": "^2.9.8",
     "got": "^11",
     "proxy-agent": "^6.5.0"