JavaScript telemetry integration reference

Overview

This topic documents how to get started with the JavaScript telemetry integration, which is compatible with the LaunchDarkly client-side JavaScript-based SDKs.

The LaunchDarkly telemetry integrations provide error monitoring and metric collection. Each telemetry integration is a separate package, which you install in addition to the LaunchDarkly SDK. After you initialize the telemetry integration, you register the LaunchDarkly SDK client with the telemetry instance. The instance collects and sends telemetry data to LaunchDarkly, where you can review metrics, events, and errors from your application.

Prerequisites and dependencies

This reference guide assumes that you are somewhat familiar with the LaunchDarkly JavaScript SDK.

The JavaScript telemetry integration package is compatible with the JavaScript SDK, launchdarkly-js-client-sdk, version 3.4.0 and later.

Get started

After you have the LaunchDarkly JavaScript SDK working in your application, follow these instructions to start using the JavaScript telemetry integration:

• Install the integration
• Initialize the telemetry, and set appropriate options for your application
• Initialize the SDK client
• Register the SDK client with the telemetry instance
• Review telemetry data in LaunchDarkly

Install the integration

The first step is to make the JavaScript telemetry integration available as a dependency:

$
npm install @launchdarkly/browser-telemetry

Then, import the package into your code. Here is an example:

1
import { initialize } from "launchdarkly-js-client-sdk";
2
import { initTelemetry, register } from "@launchdarkly/browser-telemetry";

Initialize the telemetry

Next, initialize the telemetry as early as possible in your application. The telemetry can only record errors if they occur after the telemetry is initialized.

The initTelemetry method takes a set of options.

• For metric collection, you can use the options to specify that breadcrumbs and stack traces should not be sent back to LaunchDarkly. These are not required for metric collection, so including them only increases the amount of data you are sending to LaunchDarkly.
• For error monitoring, we recommend that you leave the breadcrumbs and stack traces enabled. You can use the BreadcrumbsOptions and StackOptions, respectively, to customize the data your application sends back to LaunchDarkly. To learn more, read Limit data sent to LaunchDarkly, below.

Here’s how to initialize telemetry in your application:

1
initTelemetry({breadcrumbs: false, stack: false});

The telemetry data collected using initTelemetry() is stored until the telemetry instance is registered with the SDK client. After registration, the collected events are sent to LaunchDarkly.

For the complete list of available options, read Options.

Limit data sent to LaunchDarkly

To collect error metrics only, you can disable breadcrumbs and stack in the options that you pass to initTelemetry(). This limits the amount of data sent back to LaunchDarkly. To enable both error monitoring and metric collection, you must leave these enabled.

You have several options for limiting the data sent to LaunchDarkly, using filters. These options are available whether you are using telemetry for error metrics only, or for error monitoring and metric collection.

For example, if you want to filter out breadcrumb details, you can use the filters option on the breadcrumb:

1
// redact any click events that include the message 'sneaky-button'
2
const breadcrumbOptions = {
3
  filters: [
4
    (breadcrumb) => {
5
      if(
6
        breadcrumb.class === 'ui' &&
7
        breadcrumb.type === 'click' &&
8
        breadcrumb.message?.includes('sneaky-button')
9
      ) {
10
        // Returning undefined omits the entire breadcrumb.
11
        return undefined;
12
      }
13
     return breadcrumb;
14
    }
15
  ]
16
}
17
18
initTelemetry({breadcrumbs: breadcrumbOptions});

Error types and messages are also included by default. You can use errorFilters to redact or omit information from them:

1
initTelemetry({
2
  errorFilters: [(err) => {
3
    // Here we replace 'secret' in messages with asterisks.
4
    return {...err, message: err.message.replace('secret', '****')}
5
  }]
6
});

To learn more, read BreadcrumbsOptions and errorFilters.

Initialize the SDK client

Next, initialize the JavaScript SDK client.

To create a client instance, you need your LaunchDarkly environment’s client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly.

Feature flag targeting and rollouts are determined by the end user viewing the page. You must pass a context, which describes this end user, to the SDK during initialization before you can request any feature flags. If you fail to pass a valid context to the SDK during initialization, you will receive a 400 error.

To collect error metrics only, no special options are required when you initialize the SDK client. For error monitoring and metric collection, use the inspectors option to allow the telemetry integration to capture feature flag information.

Here’s how to initialize the JavaScript SDK client:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
const client = initialize('client-side-id-123abc', context);

To learn more about the inspectors option, read inspectors. For additional information on initializing the JavaScript SDK, read JavaScript SDK reference.

Register the SDK client with the telemetry instance

Next, register the SDK client with the telemetry instance. This method connects the telemetry to the specific LaunchDarkly client instance, which then collects flag and context data and reports it to LaunchDarkly.

Here’s how:

1
register(client);

After the SDK client is registered, the telemetry integration begins sending custom events to LaunchDarkly. This includes any events stored after the initTelemetry call but before the SDK client is registered.

Manually capturing errors

Unhandled errors are automatically captured by the telemetry integration. You can also use the integration to capture additional errors and report them to LaunchDarkly. This may be useful when you review your telemetry data in LaunchDarkly.

Use captureError to manually capture additional errors:

1
const error = new Error('example error');
2
captureError(error);

To learn more, read captureError and captureErrorEvent.

Working with multiple SDK instances

As a general rule while working with the JavaScript SDK, it’s important to make the SDK client, LDClient, a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

If you have multiple LaunchDarkly projects, you can create one SDK client for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.

If you do have multiple SDK clients, you must use the initTelemetryInstance() method, rather than initTelemetry(), to initialize your telemetry integration.

Here’s a comparison:

1
import { initialize } from "launchdarkly-js-client-sdk";
2
import { initTelemetry, register } from "@launchdarkly/browser-telemetry";
3
4
initTelemetry();
5
6
const context = {
7
  kind: 'user',
8
  key: 'context-key-123abc'
9
};
10
const client = initialize('client-side-id-123abc', context);
11
12
register(client);

Review telemetry data in LaunchDarkly

After you initialize the telemetry and register the SDK client with the telemetry instance, your application automatically starts sending telemetry data back to LaunchDarkly in the form of custom events. You can review this information in the LaunchDarkly user interface.

Specifically, the telemetry data includes events that LaunchDarkly uses to automatically create the following metrics:

• Percentage of randomization unit contexts that experienced an error

To learn more, read Autogenerated metrics.