@salesforce/telemetry 6.1.1 → 6.2.0

package/README.md

@@ -1,6 +1,6 @@
 # sfdx-telemetry
 
-This package serves an interface for [Microsoft's Application Insights npm module](https://www.npmjs.com/package/applicationinsights).
+This package serves an interface for [Microsoft's Application Insights npm module](https://www.npmjs.com/package/applicationinsights) and supports O11y (Observability) telemetry.
 
 ## Install
 
@@ -46,6 +46,36 @@ reporter.stop();
 
 **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
+
+The telemetry reporter also supports O11y telemetry alongside Application Insights. To enable O11y telemetry, provide the `enableO11y` and `o11yUploadEndpoint` options:
+
+```javascript
+const reporter = await TelemetryReporter.create({
+  project: 'my-project-name',
+  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
+});
+```
+
+#### O11y-Only Mode
+
+For O11y-only telemetry (without Application Insights), you can disable AppInsights explicitly:
+
+```javascript
+const reporter = await TelemetryReporter.create({
+  project: 'my-project-name',
+  enableO11y: true,
+  enableAppInsights: false, // Disable AppInsights
+  o11yUploadEndpoint: 'https://your-o11y-endpoint.com/upload',
+  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.
+
 ## Env Variables
 
 `SF_DISABLE_TELEMETRY`: Set to `true` if you want to disable telemetry.

package/lib/telemetryReporter.d.ts

@@ -9,8 +9,9 @@ export declare class TelemetryReporter extends AsyncCreatable<TelemetryOptions>
     private enabled;
     private options;
     private logger;
-    private reporter;
+    private reporter?;
     private enableO11y;
+    private enableAppInsights;
     private o11yReporter?;
     constructor(options: TelemetryOptions);
     /**

package/lib/telemetryReporter.js

@@ -61,11 +61,13 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
     logger;
     reporter;
     enableO11y;
+    enableAppInsights;
     o11yReporter;
     constructor(options) {
         super(options);
         this.options = options;
         this.enableO11y = options.enableO11y ?? false; // default to false for backward compatibility
+        this.enableAppInsights = options.enableAppInsights ?? true; // default to true for backward compatibility
     }
     /**
      * @deprecated Use the standalone function isEnabled() instead.
@@ -78,9 +80,17 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
     async init() {
         this.enabled = await (0, enabledCheck_1.isEnabled)();
         this.logger = await core_1.Logger.child('TelemetryReporter');
-        if (this.options.waitForConnection)
-            await this.waitForConnection();
-        this.reporter = await appInsights_1.AppInsights.create(this.options);
+        // Initialize AppInsights only if enabled and we have a valid key
+        if (this.enableAppInsights && this.options.key && this.options.key.trim() !== '') {
+            if (this.options.waitForConnection)
+                await this.waitForConnection();
+            this.reporter = await appInsights_1.AppInsights.create(this.options);
+        }
+        else if (this.enableAppInsights && (!this.options.key || this.options.key.trim() === '')) {
+            // If AppInsights is enabled but no key provided, log a warning and skip initialization
+            this.logger.warn('AppInsights is enabled but no valid key provided. Skipping AppInsights initialization.');
+        }
+        // If AppInsights is disabled, this.reporter remains undefined
         // Only initialize O11yReporter if telemetry is enabled, enableO11y is true AND o11yUploadEndpoint is provided
         if (this.isSfdxTelemetryEnabled() && this.enableO11y) {
             if (this.options.o11yUploadEndpoint) {
@@ -103,14 +113,14 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      * processes can call send*Event directly then finish it by TelemetryReporter.stop().
      */
     start() {
-        this.reporter.start();
+        this.reporter?.start();
     }
     /**
      * Immediately flush and dispose of the reporter. This can usually take 1-3 seconds
      * not counting timeouts.
      */
     stop() {
-        this.reporter.stop();
+        this.reporter?.stop();
         void this.o11yReporter?.flush();
     }
     async waitForConnection() {
@@ -155,8 +165,8 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      * @param attributes {Attributes} - map of properties to publish alongside the event.
      */
     sendTelemetryEvent(eventName, attributes = {}) {
-        // Send to AppInsights only if SFDX telemetry is enabled
-        if (this.isSfdxTelemetryEnabled()) {
+        // Send to AppInsights only if SFDX telemetry is enabled and AppInsights is enabled
+        if (this.isSfdxTelemetryEnabled() && this.enableAppInsights && this.reporter) {
             this.reporter.sendTelemetryEvent(eventName, attributes);
         }
         // Send to O11y if telemetry is enabled and O11y is enabled
@@ -174,13 +184,13 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      */
     sendTelemetryException(exception, attributes = {}) {
         // Send to AppInsights only if SFDX telemetry is enabled
-        if (this.isSfdxTelemetryEnabled()) {
+        if (this.isSfdxTelemetryEnabled() && this.enableAppInsights && this.reporter) {
             // Scrub stack for GDPR
             const sanitizedException = new Error(exception.message);
             sanitizedException.name = exception.name;
             sanitizedException.stack = exception.stack?.replace(new RegExp(os.homedir(), 'g'), appInsights_1.AppInsights.GDPR_HIDDEN);
             // Send to AppInsights
-            this.reporter.sendTelemetryException(sanitizedException, attributes);
+            this.reporter?.sendTelemetryException(sanitizedException, attributes);
         }
         // Send to O11y if telemetry is enabled and O11y is enabled
         if (this.isSfdxTelemetryEnabled() && this.enableO11y && this.o11yReporter) {
@@ -197,7 +207,7 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      */
     sendTelemetryTrace(traceMessage, properties) {
         // Send to AppInsights only if SFDX telemetry is enabled
-        if (this.isSfdxTelemetryEnabled()) {
+        if (this.isSfdxTelemetryEnabled() && this.enableAppInsights && this.reporter) {
             // Send to AppInsights
             this.reporter.sendTelemetryTrace(traceMessage, properties);
         }
@@ -217,7 +227,7 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      */
     sendTelemetryMetric(metricName, value, properties) {
         // Send to AppInsights only if SFDX telemetry is enabled
-        if (this.isSfdxTelemetryEnabled()) {
+        if (this.isSfdxTelemetryEnabled() && this.enableAppInsights && this.reporter) {
             // Send to AppInsights
             this.reporter.sendTelemetryMetric(metricName, value, properties);
         }
@@ -249,6 +259,9 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      * NOT be used to send events as it will by pass disabled checks.
      */
     getTelemetryClient() {
+        if (!this.reporter) {
+            throw new Error('AppInsights is not initialized. Check if enableAppInsights is true and a valid key is provided.');
+        }
         return this.reporter.appInsightsClient;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/telemetry",
-  "version": "6.1.1",
+  "version": "6.2.0",
   "description": "Library for telemetry reporting to Application Insights and O11y",
   "main": "lib/exported",
   "exports": {
@@ -43,7 +43,7 @@
   "dependencies": {
     "@salesforce/core": "^8.8.0",
     "@salesforce/kit": "^3.2.3",
-    "@salesforce/o11y-reporter": "1.1.2",
+    "@salesforce/o11y-reporter": "1.3.0",
     "applicationinsights": "^2.9.6",
     "got": "^11",
     "proxy-agent": "^6.5.0"