Observability plugin

Overview

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

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 using the observability plugin:

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

Install the plugin

LaunchDarkly uses a plugin to the JavaScript SDK to provide observability.

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

The session replay plugin is available separately. To learn more, read Session replay plugin.

Here’s how:

$
npm install launchdarkly-js-client-sdk
>
npm install @launchdarkly/observability

Then, import the plugin into your code:

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

Initialize the client

Next, initialize the SDK and the observability plugin. As usual, you’ll need your LaunchDarkly environment’s client-side ID for this. To learn more, read Initialize the client in the JavaScript SDK reference guide.

You will also need your observability project ID. To request your observability project ID, start a Support ticket or contact your LaunchDarkly account representative.

Here’s how:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
6
const client = initialize('client-side-id-123abc', context, {
7
  plugins: [
8
    new Observability('observability-project-id')
9
  ]
10
});

You can also initialize the plugin before you initialize the SDK if you like. This may be helpful if you need observability data very early in your application’s lifecycle.

Here’s how:

1
import { Observability, LDObserve } from "@launchdarkly/observability";
2
3
LDObserve.init('observability-project-id');

Finally, you can optionally register the plugin after you initialize the SDK:

1
import { Observability, LDObserve } from "@launchdarkly/observability";
2
3
LDObserve.register(client);

We do not recommend this option because you will miss observability data generated before you register the plugin.

Configure the plugin options

You can configure options for the observability plugin when you initialize the SDK if you like. The plugin constructor takes an optional object with the configuration details.

Here is an example:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
6
const client = initialize('client-side-id-123abc', context, {
7
  plugins: [
8
    new Observability('observability-project-id', {
9
      tracingOrigins: true, // attribute frontend requests to backend domains
10
      networkRecording: {
11
        enabled: true,
12
        recordHeadersAndBody: true
13
      },
14
      privacySetting: 'strict' // or 'default' or 'none', obfuscates text and images
15
    })
16
  ]
17
});

For more information on plugin options, read Client-side observability.

Explore supported features

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

Errors

The observability plugin automatically sends errors to LaunchDarkly.

You can also use recordError to manually send a custom error:

1
LDObserve.recordError(error, 'optional message', {
2
  component: 'ExampleComponent.tsx',
3
});

The message and payload arguments are optional. To learn more, read recordError.

Logs

The observability plugin automatically sends errors to LaunchDarkly.

You can also use recordLog to manually create and send a log record:

1
LDObserve.recordLog('Example log message', Severity.DEBUG);

To learn more, read recordLog.

Tracing

The observability plugin provides two options for starting new spans:

• startSpan() ends the span automatically after the callback function completes, whether it returns normally or throws an error
• startManualSpan() ends the span when you call span.end()

To start a new span:

1
// This span ends automatically after the callback completes
2
LDObserve.startSpan('fetchData', (span) => {
3
  // Your code here
4
});

To learn more, read startSpan and startManualSpan

Metrics

The observability plugin provides different functions depending on what kind of data you want to record. The recorded data is available as an $ld:telemetry:metric event, and you can review it in the LaunchDarkly UI. To learn more about metric events, read Autogenerated metrics. To learn more about reviewing this data in the LaunchDarkly UI, read Observability.

Here are the options for recording metrics:

1
const onClick = () => {
2
  const start = Date.now();
3
  doInterestingWork();
4
  const elapsed = Date.now() - start;
5
  LDObserve.recordGauge({name: "elapsedTimeMs", value: elapsed});
6
};

To learn more, read LDObserve.

Review observability data in LaunchDarkly

After you initialize the SDK and observability plugin, 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 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 Metrics autogenerated from observability events.