Skip to content

README.md

Latest commit

 

History

History
152 lines (120 loc) · 7.4 KB

README.md

File metadata and controls

152 lines (120 loc) · 7.4 KB
Raw

LaunchDarkly React Native Observability Plugin

NPM Actions Status NPM NPM Documentation

NB: APIs are subject to change until a 1.x version is released.

Installation

Basic Installation

npm install @launchdarkly/observability-react-native
# or
yarn add @launchdarkly/observability-react-native

Usage

import { LDClient } from '@launchdarkly/react-native-client-sdk';
import { Observability } from '@launchdarkly/observability-react-native';

const client = new LDClient(
  mobileKey,
  user,
  {
    // ... other options
  },
  [
    new Observability({
      serviceName: 'my-react-native-app',
      serviceVersion: '1.0.0',
    })
  ]
);

Attributes on all telemetry

Use setAttributes to tag every span, log, error and metric recorded after the call with values known only at runtime, including network spans and flag evaluation spans the SDK records automatically. removeAttributes (or a null value) stops adding a key:

import { LDObserve } from '@launchdarkly/observability-react-native';

LDObserve.setAttributes({ utm_campaign: 'spring_promo', utm_source: 'email' });

// Later:
LDObserve.removeAttributes(['utm_campaign']);

Attributes are kept in memory for the current app process only and are never persisted, so set them again after the app restarts. Attributes passed to an individual call take precedence, and keys in the SDK's own namespaces (highlight.*, context.contextKeys.*, launchdarkly.*, session.*) are ignored. Attributes are also added to metrics, where each distinct value creates a new series, so avoid high-cardinality values such as user ids.

Manual tracing

Use the LDObserve singleton to create spans by hand. withSpan runs your callback inside a span and ends it automatically — even across awaits, where React Native only tracks the active context synchronously. Use scope.child to parent nested spans off the captured context:

import { LDObserve } from '@launchdarkly/observability-react-native';

await LDObserve.withSpan('LoadProducts', async (scope) => {
  scope.span.setAttribute('source', 'api');

  // `scope.child` parents off LoadProducts even after the await above.
  const products = await scope.child('FetchFromApi', async (fetchScope) => {
    const response = await fetch('https://api.example.com/products');
    fetchScope.span.setAttribute('http.status_code', response.status);
    return response.json();
  });

  scope.span.setAttribute('product_count', products.length);
});

Using the OpenTelemetry API directly

If you prefer to follow the standard OpenTelemetry JS documentation, or you need to hand a Tracer to a third-party library, LDObserve.getTracer() returns an LDTracer — a standard OpenTelemetry Tracer plus the async-safe withSpan helper. It is wired to the same exporter and sampler as the rest of the SDK. It is always safe to call — before the SDK finishes initializing (or when disableTraces is set) it returns a no-op tracer.

import { LDObserve } from '@launchdarkly/observability-react-native';

const tracer = LDObserve.getTracer();

// Standard OpenTelemetry API
const span = tracer.startSpan('checkout');
span.setAttribute('cart.id', 'cart-7');
span.end();

// Async-safe nested spans (React Native) — same helper as LDObserve.withSpan
await tracer.withSpan('LoadProducts', async (scope) => {
  const products = await scope.child('FetchFromApi', async (fetchScope) => {
    const response = await fetch('https://api.example.com/products');
    fetchScope.span.setAttribute('http.status_code', response.status);
    return response.json();
  });
  scope.span.setAttribute('product_count', products.length);
});

Context propagation in React Native. React Native tracks the active span only synchronously (there is no AsyncLocalStorage), so it is not restored after an await. Use tracer.withSpan / scope.child (or LDObserve.withSpan) for nested async work. See the Tracing Guide for details.

Guides

  • Tracing Guide — a cookbook of common tracing patterns (spans, nested operations, error handling, correlated logs, and end-to-end mobile-to-backend traces).

About LaunchDarkly

  • LaunchDarkly Observability provides a way to collect and send errors, logs, traces to LaunchDarkly. Correlate latency or exceptions with your releases to safely ship code.
  • LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
    • Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
    • Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
    • Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
    • Grant access to certain features based on user attributes, like payment plan (eg: users on the 'gold' plan get access to more features than users in the 'silver' plan).
    • Disable parts of your application to facilitate maintenance, without taking everything offline.
  • LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Read our documentation for a complete list.
  • Explore LaunchDarkly