JavaScript SDK observability reference

Overview

This topic documents how to get started with the LaunchDarkly observability plugins for the client-side JavaScript SDK.

The JavaScript SDK supports the following observability plugins:

• An Observability plugin for error monitoring, logging, and tracing.
• A Session replay plugin that provides a way to record and replay end-user sessions from your application.

Prerequisites and dependencies

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

The observability plugin is compatible with the JavaScript SDK, version 3.7.0 and later.

Get started

Follow these steps to get started:

• Install the plugins
• Initialize the JavaScript SDK client
• Configure the plugin options
• Explore supported features
• Review observability data in LaunchDarkly

Install the plugins

LaunchDarkly uses plugins to the JavaScript SDK to provide observability. Most customers use both the observability and session replay plugins. However, there is no dependency between them, and you can use only one or the other if you like.

The first step is to make both the SDK and the observability plugins available as dependencies.

Here’s how:

$
npm install @launchdarkly/js-client-sdk
$
npm install @launchdarkly/observability
$
npm install @launchdarkly/session-replay

Then, import the plugin into your code:

1
import { initialize } from "@launchdarkly/js-client-sdk";
2
import Observability, { LDObserve } from "@launchdarkly/observability";
3
import SessionReplay, { LDRecord } from "@launchdarkly/session-replay";

Initialize the client

Next, initialize the SDK and the plugins.

To initialize, you need your LaunchDarkly environment’s client-side ID and, in some versions, the context for which you want to evaluate flags. This authorizes your application to connect to a particular environment within LaunchDarkly. To learn more, read Initialize the client in the JavaScript SDK reference guide.

You can initialize the observability plugins either at the same time you initialize the SDK, or afterwards.

Initialize SDK client and plugins together

Here’s how to initialize the SDK and plugins:

1
const client = initialize('example-client-side-id', {
2
  plugins: [ new Observability(), new SessionReplay() ]
3
});

Initialize the plugins after the SDK client

You can initialize the observability and session replay plugins manually, after the SDK client is initialized.

This approach supports feature-flagged rollouts or dynamic initialization after end user consent. Both plugins use a manualStart option combined with .start() calls.

First, configure the plugins with manualStart: true:

1
const client = initialize('example-client-side-id', {
2
  plugins: [
3
    new Observability({ manualStart: true }),
4
    new SessionReplay({ manualStart: true })
5
  ]
6
});

Then, start the plugins when appropriate, such as after receiving end user consent or when a feature flag enables observability.

Here’s an example starting the observability plugin:

1
// Start observability after user consent or feature flag check
2
if (userConsentReceived || featureFlagEnabled) {
3
  LDObserve.start();
4
}

Here’s an example with the session replay plugin:

1
LDRecord.start({
2
  silent: false // if true, console.warn messages created in this method are skipped
3
});

This approach allows you to:

• Feature-flag the rollout of observability to a subset of end users
• Wait for end user consent before starting data collection
• Dynamically enable observability based on runtime conditions
• Maintain compliance with privacy regulations

Configure the plugin options

You can configure options for the observability plugins when you initialize the SDK. The plugin constructors take an optional object with the configuration details.

Here is an example:

1
const client = initialize('example-client-side-id', {
2
  plugins: [
3
    new Observability({
4
      tracingOrigins: true, // attribute frontend requests to backend domains
5
      networkRecording: {
6
        enabled: true,
7
        recordHeadersAndBody: true
8
      }
9
    }),
10
    new SessionReplay({
11
      privacySetting: 'strict',
12
      // or 'default' to redact text matching common regex for PII
13
      // or 'none' to turn off obfuscation
14
    })
15
  ]
16
});

For more information on plugin options, read Configuration for client-side observability and Configuration for session replay.

Configure product analytics event collection

By default, the JavaScript client-side SDK observability plugin automatically records these product analytics events as OpenTelemetry span events:

• Page clicks, with details about the click location and URL where the click occurred.
• Page views, with details of the current and previous URLs.
• Custom metric events that you generate using the track() method. The OpenTelemetry span events for track() calls include the URL and metric event key, as well as any optional numeric value provided for a numeric event.

All of the above OpenTelemetry span events also include information about the LaunchDarkly context that generated the event.

You can use the generated span events to create custom product analytic charts, such as time series and funnels. You can also view the raw span data directly from the observability Traces view. To learn more, read Traces.

Use the productAnalytics: false setting in plugin options to disable collecting product analytics events, or specify individual event types to exclude.

Here is an example:

1
const client = initialize('example-client-side-id', {
2
  plugins: [
3
    new Observability({
4
      tracingOrigins: true, 
5
      productAnalytics: { // enable all product analytics events except for clicks
6
        pageViews: true,
7
        trackEvents: true,
8
        clicks: false
9
      }
10
    }),
11
  ]
12
});

Set Context-Security-Policy (CSP)

If your application runs in an environment that enforces content security policies, you must set the Content-Security-Policy (CSP) in your application to tell the browser how your page can interact with third-party scripts.

Here are the policies you need to set to use the observability plugin:

• connect-src: https://pub.observability.app.launchdarkly.com https://otel.observability.app.launchdarkly.com: This policy allows connecting with LaunchDarkly servers to send recorded observability data.
• worker-src: data: blob:: This policy allows creating an inline web worker initialized by the npm package for this plugin.

Your CSP definition may look something like this:

1
<meta
2
  http-equiv="Content-Security-Policy"
3
  content="connect-src: https://pub.observability.app.launchdarkly.com https://otel.observability.app.launchdarkly.com; worker-src data: blob:;"
4
/>

Alternatively, you can set the CSP in the HTML document response header Content-Security-Policy. Check your initial app HTML document load for the header to make sure you are setting it to the desired value.

Explore supported features

The observability plugin supports the following features. After the SDK and plugins are initialized, you can access these from within your application:

• Configuration for client-side observability
• Configuration for session replay
• Errors
• Logs
• Metrics
• Tracing

Review observability data in LaunchDarkly

After you initialize the SDK and observability plugins, your application automatically starts sending observability data back to LaunchDarkly in the form of custom events. You can review this information in the LaunchDarkly user interface. To learn how, read Observability.

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

• Average, P95, and P99 Cumulative Layout Shift (CLS) per context (LaunchDarkly)
• Average, P95, and P99 Document Load Latency per context (LaunchDarkly)
• Percentage of users with errors (LaunchDarkly)
• Average, P95, and P99 First Contentful Paint (FCP) per context (LaunchDarkly)
• Average, P95, and P99 First Input Delay (FID) per context (LaunchDarkly)
• Average, P95, and P99 Interaction to Next Paint (INP) per context (LaunchDarkly)
• Average, P95, and P99 Largest Contentful Paint (LCP) (LaunchDarkly)
• Average, P95, and P99 Time to First Byte (TTFB) per context (LaunchDarkly)

To learn more, read Observability autogenerated metrics.