@salesforce/o11y-reporter/README.md

A wrapper service around o11y and o11y_schema for telemetry reporting.

# 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

```typescript
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

```typescript
// 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

1. **Initialize Early**: Initialize the service as early as possible in your extension's lifecycle.

2. **Error Handling**: Always wrap telemetry calls in try-catch blocks to prevent them from affecting your main application flow.

3. **Property Naming**: Use consistent property names and avoid sending sensitive information.

4. **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:

```typescript
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](LICENSE.txt) file for details.