O11y Reporter

A lightweight telemetry reporting service for Salesforce extensions that enables sending metrics and events to Salesforce's observability platform.

Usage

The O11y Reporter service provides a simple way to send telemetry events and metrics to Salesforce's observability platform. Here's how to use it:

1. Initialize the Service

import { O11yService } from "@salesforce/o11y-reporter";

// Get the singleton instance
const o11yService = O11yService.getInstance(extensionName);

// Initialize with your extension name and upload endpoint
await o11yService.initialize(
  "your-extension-name",
  "https://your-upload-endpoint",
);

2. Send Telemetry Events

// Send a telemetry event with properties
o11yService.logEvent({
  name: "extension/eventName",
  properties: {
    // Add your custom properties here
    customProperty: "value",
  },
  measurements: {
    // Optional measurements
    duration: 100,
  },
});

// Send an exception event
o11yService.logEvent({
  exception: new Error("Error message"),
  properties: {
    // Add your custom properties here
    errorType: "RuntimeError",
  },
  measurements: {
    // Optional measurements
    errorCount: 1,
  },
});

// Upload the events to the server
await o11yService.upload();

3. Automatic Upload

The service uploads events when:

You explicitly call upload()
The service is disposed

Configuration

The service can be configured with the following options:

o11yUploadEndpoint: The endpoint URL for uploading telemetry data

Best Practices

Initialize Early: Initialize the service as early as possible in your extension's lifecycle.
Error Handling: Always wrap telemetry calls in try-catch blocks to prevent them from affecting your main application flow.
Property Naming: Use consistent property names and avoid sending sensitive information.
Regular Uploads: Call upload() periodically to ensure data is sent to the server.

Example Implementation

Here's a complete example of how to use the O11y Reporter in your extension:

import { O11yService } from "@salesforce/o11y-reporter";

class YourExtension {
  private o11yService: O11yService;

  constructor() {
    this.o11yService = O11yService.getInstance(extensionName);
  }

  async initialize() {
    await this.o11yService.initialize(
      "your-extension",
      "https://your-endpoint",
    );
  }

  async trackUserAction(actionName: string, properties: Record<string, any>) {
    try {
      this.o11yService.logEvent({
        name: `user/${actionName}`,
        properties: {
          ...properties,
          timestamp: new Date().toISOString(),
        },
      });

      // Upload immediately for important events
      await this.o11yService.upload();
    } catch (error) {
      // Log error but don't throw
      console.error("Failed to send telemetry:", error);
    }
  }

  async trackError(error: Error, context: Record<string, any>) {
    try {
      this.o11yService.logEvent({
        exception: error,
        properties: {
          ...context,
          timestamp: new Date().toISOString(),
        },
      });

      await this.o11yService.upload();
    } catch (err) {
      console.error("Failed to send error telemetry:", err);
    }
  }
}

License

This project is licensed under the Terms of Use. See the LICENSE.txt file for details.

Package detail

@salesforce/o11y-reporter

readme