Merge pull request #469 from forcedotcom/sh/pft-telemetry

adds support for sending PDP Events via o11y @W-21179952

Author: shetzel

LICENSE.txt

@@ -1,6 +1,6 @@
 Apache License Version 2.0
 
-Copyright (c) 2025 Salesforce, Inc.
+Copyright (c) 2026 Salesforce, Inc.
 All rights reserved.
 
                                  Apache License

package.json

@@ -46,6 +46,7 @@
     "@salesforce/o11y-reporter": "1.7.3",
     "applicationinsights": "^2.9.8",
     "got": "^11",
+    "o11y_schema": "^260.41.0",
     "proxy-agent": "^6.5.0"
   },
   "devDependencies": {

src/exported.ts

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

src/o11yReporter.ts

@@ -14,7 +14,10 @@
  * limitations under the License.
  */
 import { O11yService, type BatchingOptions } from '@salesforce/o11y-reporter';
-import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore o11y_schema/sf_pdp.d.ts is not a valid module
+import { pdpEventSchema } from 'o11y_schema/sf_pdp';
+import { Attributes, O11ySchema, PdpEvent, Properties, TelemetryOptions } from './types';
 import { BaseReporter } from './baseReporter';
 import { buildPropertiesAndMeasurements } from './utils';
 
@@ -124,6 +127,21 @@ export class O11yReporter extends BaseReporter {
     }
   }
 
+  /**
+   * Sends a PDP event via O11y service.
+   *
+   * @param event - PDP event to send.
+   */
+  public async sendPdpEvent(event: PdpEvent): Promise<void> {
+    await this.initialized;
+
+    this.service.logEventWithSchema(event, pdpEventSchema);
+
+    if (!this._batchingEnabled) {
+      await this.service.forceFlush();
+    }
+  }
+
   public async flush(): Promise<void> {
     // Wait for initialization to complete before using the service
     await this.initialized;

src/telemetryReporter.ts

@@ -23,7 +23,7 @@ import { ProxyAgent } from 'proxy-agent';
 import { AppInsights, TelemetryClient } from './appInsights';
 import { isEnabled } from './enabledCheck';
 import { O11yReporter } from './o11yReporter';
-import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
+import { Attributes, O11ySchema, PdpEvent, Properties, TelemetryOptions } from './types';
 
 /**
  * This is the main telemetry reporter that should be used by consumers.
@@ -176,6 +176,19 @@ export class TelemetryReporter extends AsyncCreatable<TelemetryOptions> {
     }
   }
 
+  /**
+   * Sends a PDP event via O11y.
+   *
+   * @param event - PDP event data to send.
+   */
+  public sendPdpEvent(event: PdpEvent): void {
+    if (this.isSfdxTelemetryEnabled() && this.enableO11y && this.o11yReporter) {
+      void this.o11yReporter.sendPdpEvent(event).catch((error) => {
+        this.logger.debug('Failed to send PDP event to O11y:', error);
+      });
+    }
+  }
+
   /**
    * Sends message to both AppInsights and O11y (if enabled).
    *

src/types.ts

@@ -35,6 +35,50 @@ export type Attributes = {
  */
 export type O11ySchema = Record<string, unknown>;
 
+/**
+ * PDP Product Feature Taxonomy (PFT) event sent via O11y.
+ */
+export type PdpEvent = {
+  /**
+   * Unique identifier for the event. Follows this naming convention:
+   *     <object>.<action>
+   *
+   * object = Specific object within the Product Feature that give us context around the action in lowerCamelCase format.
+   *          Note: The object name can include context around the Product Feature (eg. slackforceMessage).
+   *          Examples: calculatedInsightsRecord,checkoutPaymentmethod, slackforceMessage, promptBuilderTemplate
+   *
+   * action = Action the user takes in past tense. This should only be ONE word, in lower case
+   *          Examples: processed, selected, sent, saved
+   */
+  eventName: `${string}.${string}`;
+  /**
+   * Product Feature ID from GUS.
+   *
+   * Examples:
+   *   Salesforce CLI = aJCEE0000000mHP4AY
+   *   Salesforce Extensions for VS Code = aJCEE0000000mLm4AI
+   */
+  productFeatureId: `aJC${string}`;
+  /**
+   * Populate this if there is a unique component with your Event for which a distinct count would be a relevant metric
+   * E.g., CLI plugin command name (<pluginName.commandName>) or ext command name.
+   */
+  componentId?: string;
+  /**
+   * Populate this if there is a unique quantity with your Event for which a sum would be a relevant metric for your
+   * Product Feature. E.g., rowsProcessed → total Rows processed for Data Streams.
+   */
+  eventVolume?: number;
+  /**
+   * Use this field to specify the name of your flexible attribute (eg. experimentId, buttonColor).
+   */
+  contextName?: string;
+  /**
+   * Use this field to specify the value of your flexible attribute (eg. exp_123, green).
+   */
+  contextValue?: string;
+};
+
 /**
  * Batching configuration for O11y telemetry
  *

test/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "extends": "@salesforce/dev-config/tsconfig-test-strict",
-  "include": ["unit/**/*.ts", "../node_modules/@types/**/*.d.ts"],
+  "include": ["unit/**/*.ts", "../node_modules/@types/**/*.d.ts", "../src/**/*.ts", "../**/*.d.ts"],
   "compilerOptions": {
     "noEmit": true,
     "skipLibCheck": true,

test/unit/telemetryReporter.test.ts

@@ -15,11 +15,14 @@
  */
 import * as os from 'node:os';
 import { ConfigAggregator, Logger } from '@salesforce/core';
+import { O11yService } from '@salesforce/o11y-reporter';
 import got from 'got';
 import { expect } from 'chai';
 import * as sinon from 'sinon';
 import { AppInsights } from '../../src/appInsights';
+import { O11yReporter } from '../../src/o11yReporter';
 import { TelemetryReporter } from '../../src/telemetryReporter';
+import type { PdpEvent } from '../../src/types';
 import * as enabledStubs from '../../src/enabledCheck';
 
 describe('TelemetryReporter', () => {
@@ -48,6 +51,43 @@ describe('TelemetryReporter', () => {
     expect(sendStub.calledOnce).to.be.true;
   });
 
+  it('should send PDPEvent', async () => {
+    sandbox.stub(ConfigAggregator.prototype, 'getPropertyValue').returns('false');
+
+    const mockO11yService = {
+      initialize: sandbox.stub().resolves(),
+      logEvent: sandbox.stub(),
+      logEventWithSchema: sandbox.stub(),
+      forceFlush: sandbox.stub().resolves(),
+      enableAutoBatching: sandbox.stub().returns(() => {}),
+    };
+    sandbox.stub(O11yService, 'getInstance').returns(mockO11yService as unknown as O11yService);
+
+    const sendPdpEventStub = sandbox.stub(O11yReporter.prototype, 'sendPdpEvent').resolves();
+
+    const reporter = await TelemetryReporter.create({
+      project: 'salesforce-cli',
+      key: 'not-used',
+      userId: 'test-user-id-for-pft-testing',
+      waitForConnection: true,
+      enableO11y: true,
+      enableAppInsights: false,
+      o11yUploadEndpoint: 'https://794testsite.my.site.com/byolwr/webruntime/log/metrics',
+    });
+
+    const pdpEvent: PdpEvent = {
+      eventName: 'salesforceCli.executed',
+      productFeatureId: 'aJCEE0000000mHP4AY',
+      componentId: '@salesforce/plugin-auth.org:web:login',
+      contextName: 'orgId::devhubId',
+      contextValue: '00Ded000000VsTxEAK::00D460000019MkyEAE',
+    };
+    reporter.sendPdpEvent(pdpEvent);
+
+    expect(sendPdpEventStub.calledOnce).to.be.true;
+    expect(sendPdpEventStub.firstCall.args[0]).to.deep.equal(pdpEvent);
+  });
+
   it('should send a telemetry exception', async () => {
     const options = { project, key };
     sandbox.stub(ConfigAggregator.prototype, 'getPropertyValue').returns('false');

tsconfig.json

@@ -8,5 +8,5 @@
     "rootDir": "src",
     "baseUrl": "."
   },
-  "include": ["src/**/*.ts"]
+  "include": ["src/**/*.ts", "types/**/*.d.ts"]
 }

types/o11y_schema_sf_pdp.d.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+declare module 'o11y_schema/sf_pdp' {
+  const pdpEventSchema: Record<string, unknown>;
+  export { pdpEventSchema };
+}