Skip to main content
This topic documents how to get started with the LaunchDarkly observability plugin for the Node.js (server-side) SDK. The Node.js (server-side) SDK supports the observability plugin for error monitoring, logging, and tracing.
SDK quick linksLaunchDarkly SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:
ResourceLocation
SDK API documentationObservability plugin API docs
GitHub repository@launchdarkly/observability-node
Sample applicationExample Express app
Published modulenpm
For use in server-side applications onlyThe observability-node plugin is intended for use in multi-user Node.js server applications. If you want to set up LaunchDarkly in JavaScript in a browser environment, read the JavaScript SDK reference and JavaScript SDK observability reference.To learn more about the different LaunchDarkly SDK types, read Choosing an SDK type.

Prerequisites and dependencies

This reference guide assumes that you are somewhat familiar with the LaunchDarkly Node.js (server-side) SDK. The observability plugin is compatible with the Node.js (server-side) SDK, version 9.10.0 and later.

Get started

Follow these steps to get started:

Install the plugin

LaunchDarkly uses a plugin to the Node.js (server-side) SDK to provide observability. The first step is to make both the SDK and the observability plugins available as dependencies. Here’s how:
Then, import the plugin into your code:

Initialize the client

Next, initialize the SDK and the plugin. To initialize, you need your LaunchDarkly environment’s SDK key. This authorizes your application to connect to a particular environment within LaunchDarkly. To learn more, read Initialize the client in the Node.js (server-side) SDK reference guide. Here’s how to initialize the SDK and plugin:

Import the plugin before other libraries

The observability plugin instruments supported libraries, such as Express and database drivers, by hooking into the Node.js CommonJS module loader. Importing @launchdarkly/observability-node installs those hooks. The plugin instruments only the libraries that your application loads after the hooks are in place. If your application loads Express before it imports the plugin, the plugin does not capture Express routes or middleware. Your application does not need to wait for the LaunchDarkly client to finish initializing before it loads other libraries. To control the order, initialize the SDK in a dedicated module, then load that module before your application loads anything else. How you load it depends on whether your application uses CommonJS or ECMAScript modules (ESM).
Automatic instrumentation is limited in ESM applicationsThe hooks only intercept CommonJS module loading. Unless you preload the plugin’s register entry point, the plugin does not instrument libraries that your application loads with an ESM import. This means that ESM applications do not receive spans for Express routes, middleware, or database clients.Most frameworks load the Node.js http module internally through CommonJS. As a result, ESM applications still receive spans for incoming and outgoing HTTP requests, along with the metrics that LaunchDarkly generates from those spans. If your application does not load http this way, the plugin captures no automatic spans.To instrument libraries that load with import, use version 1.5.0 or later of the observability plugin and preload its register entry point. To learn more, read Instrument ES modules. You can also record spans, metrics, logs, and errors manually with LDObserve. To learn more, read Tracing.
Here is the dedicated module:
Then load that module from the first line of your application’s entry point, before you require any other library:
Alternatively, preload the module with the Node.js --require option. This keeps the ordering requirement out of your application code:
If you write your application in TypeScript and compile it to CommonJS, the same ordering applies to the compiled output. Put the initialization in its own source file, such as launchdarkly.ts, and import that file first.
In an ESM application, Node.js evaluates every import statement in a file before it runs any of that file’s own code. Initializing the SDK in the body of your entry point is too late, because your application has already loaded Express and your other libraries by that point. Put the initialization in its own module instead.Ordering determines whether an ESM application produces any telemetry at all. If the plugin loads first, it captures HTTP request spans through the imports your framework makes internally. If it loads later, it captures nothing.Here is the dedicated module:
Then preload the module with the Node.js --import option:
To also instrument the libraries that your application loads with import, preload the plugin’s register entry point before your initialization module. To learn more, read Instrument ES modules.You can also load the module as the first import in your entry point. We recommend the --import option instead, because bundlers and automatic import sorting can reorder import statements:

Instrument ES modules

This section explains how to instrument libraries that your application loads with an ESM import. This requires version 1.5.0 or later of the observability plugin, and Node.js 18.19, 20.6, or later. Preload the register entry point if either of these applies:
  • Your application is an ESM application.
  • Your application, or one of its dependencies, loads an instrumented library that ships only as ES modules.
If database or HTTP client spans, such as pg query spans, are missing even though you initialized the plugin, this is the likely cause. CommonJS applications whose libraries load with require do not need the register entry point. To preload the entry point, pass it to Node.js with the --import option, before your application’s entry point:
If you can’t change your application’s start command, such as on some hosting platforms, set the NODE_OPTIONS environment variable instead:
If you also preload your SDK initialization module, list the register entry point first. Here is an example package.json script:
If you run TypeScript through a loader, such as tsx or @swc-node/register, list the register entry point before the loader. On Node.js 22, listing @swc-node/register first causes module resolution errors. Here is how:
If you compile your TypeScript to JavaScript before you run it, such as with swc, preload the register entry point the same way you would for any JavaScript application. The register entry point only installs the module hooks. You still need to initialize the client with the observability plugin, because the plugin applies its options, such as serviceName, when the SDK client registers it. Consider these limitations before you use the register entry point:
  • Startup time: The entry point wraps every ES module that your application loads, not only the instrumented libraries. This adds some time to application startup.
  • Node.js version: On Node.js versions earlier than 18.19 or 20.6, the entry point logs a warning and does not instrument libraries that load with import. Libraries that load with require are still instrumented.
  • Framework support: The entry point instruments only the libraries that OpenTelemetry instrumentation supports. For example, NestJS 12 does not produce framework spans yet, but the libraries it uses, such as database clients, are instrumented.

Configure the plugin options

You can configure options for the observability plugin when you initialize the SDK. The plugin constructor takes an optional object with the configuration details. Here is an example:
For more information on plugin options, as well as how they interact with environment variables and existing OpenTelemetry configuration, read Configuration for server-side observability.

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:

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:
  • User HTTP error rate (OpenTelemetry)
  • User HTTP 5XX response rate (OpenTelemetry)
  • User non-HTTP exception rate (OpenTelemetry)
  • Average, P95, and P99 request latency (OpenTelemetry)
To learn more, read OpenTelemetry autogenerated metrics.