Flutter SDK observability reference

This topic documents how to get started with the LaunchDarkly observability plugin for the Flutter SDK.

The launchdarkly_flutter_observability package provides error monitoring, logging, tracing, and session replay through a single public facade named LDObserve.

Prerequisites and dependencies

This reference guide assumes you are familiar with the LaunchDarkly Flutter SDK.

The observability plugin requires the LaunchDarkly Flutter SDK version 4.17.0 or later.

The Flutter observability plugin is compatible with iOS, Android, and web platforms. Session replay is supported only on iOS and Android. Web session replay is not yet available.

Get started

Follow these steps to get started:

• Install the package
• Initialize observability
• Configure plugin options
• Configure session replay
• Explore supported features
• Review observability data in LaunchDarkly

Install the package

Add both the LaunchDarkly Flutter SDK and the observability package to your pubspec.yaml:

1
dependencies:
2
  launchdarkly_flutter_client_sdk: ^4.17.0
3
  launchdarkly_flutter_observability: ^0.2.0

Then run:

$
flutter pub get

For iOS, install the native pod dependencies from your app’s ios/ directory:

$
cd ios && pod install && cd ..

No extra setup is required for Android. Gradle resolves the plugin automatically.

After you install the dependencies, import the packages into your code:

1
import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
2
import 'package:launchdarkly_flutter_observability/launchdarkly_flutter_observability.dart';

Initialize observability

To initialize, you need your LaunchDarkly environment’s mobile key. This authorizes your application to connect to a particular environment within LaunchDarkly. To learn more, read Initialize the client in the Flutter SDK reference guide.

There are two initialization variants. Use LDObserve.init if you are using the LaunchDarkly client, or LDObserve.initStandalone to initialize without a client.

Initialize with a LaunchDarkly client

Pass your LDClient to LDObserve.init. This registers the observability plugin on the client so feature flag evaluations are correlated with your telemetry:

1
import 'dart:async';
2
import 'package:flutter/material.dart';
3
import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
4
import 'package:launchdarkly_flutter_observability/launchdarkly_flutter_observability.dart';
5
6
void main() {
7
  runZonedGuarded(
8
    () {
9
      WidgetsFlutterBinding.ensureInitialized();
10
11
      final client = LDClient(
12
        LDConfig(
13
          'example-mobile-key',
14
          AutoEnvAttributes.enabled,
15
        ),
16
        LDContextBuilder().kind('user', 'example-context-key').build(),
17
      );
18
      client.start();
19
20
      LDObserve.init(
21
        client,
22
        observability: const ObservabilityOptions(
23
          serviceName: 'my-flutter-app',
24
        ),
25
      );
26
27
      // Report errors caught by the Flutter framework
28
      FlutterError.onError = (FlutterErrorDetails details) {
29
        LDObserve.recordException(details.exception, stackTrace: details.stack);
30
      };
31
32
      runApp(const MyApp());
33
    },
34
    (err, stack) {
35
      // Report uncaught errors from the zone
36
      LDObserve.recordException(err, stackTrace: stack);
37
    },
38
  );
39
}

Initialize standalone

To initialize without creating a LaunchDarkly client, pass your mobile key directly to LDObserve.initStandalone:

1
await LDObserve.initStandalone(
2
  'example-mobile-key',
3
  observability: const ObservabilityOptions(
4
    serviceName: 'my-flutter-app',
5
  ),
6
);

Configure plugin options

Pass an ObservabilityOptions object to LDObserve.init or LDObserve.initStandalone to configure observability behavior:

1
LDObserve.init(
2
  client,
3
  observability: ObservabilityOptions(
4
    serviceName: 'my-flutter-app',
5
    // Recommended: set to the latest deployed git SHA or semantic version
6
    serviceVersion: 'example-sha',
7
    instrumentation: InstrumentationOptions(
8
      networkRequests: true,
9
      launchTimes: true,
10
      debugPrint: DebugPrintSetting.releaseOnly(),
11
    ),
12
  ),
13
);

These ObservabilityOptions configuration options are available on all platforms:

• isEnabled: Enables or disables observability. Defaults to true.
• serviceName: The service name for telemetry. Defaults to "observability-flutter".
• serviceVersion: The service version, commonly a Git SHA or semantic version string. Defaults to "0.1.0".
• instrumentation: An InstrumentationOptions object that controls automatic instrumentation. To learn more, read Instrumentation options.
• otlpEndpoint: The OTLP endpoint for reporting OpenTelemetry data. Defaults to https://otel.observability.app.launchdarkly.com:4318. You do not need to change this for most configurations.
• backendUrl: The LaunchDarkly back-end URL. Defaults to https://pub.observability.app.launchdarkly.com. You do not need to change this for most configurations.
• contextFriendlyName: A display name to identify the user’s session in the observability UI.
• attributes: A map of additional resource attributes to include in telemetry.

The following ObservabilityOptions configuration options are available only on Android and iOS:

• customHeaders: Extra HTTP headers added to OTLP exports, for example for proxies or authentication. Defaults to {}.
• sessionBackgroundTimeout: How long the app can stay in the background before the session ends. Defaults to 15 minutes.
• logsApiLevel: The minimum severity of logs forwarded to the logs pipeline. Use ObservabilityLogLevel.none to disable logs. Defaults to ObservabilityLogLevel.info.
• traces: A TracesOptions object that controls automatic trace generation. Toggles includeErrors and includeSpans. Both default to true.
• metricsEnabled: Whether metrics are exported. Defaults to true.
• productAnalytics: A ProductAnalyticsOptions object that controls telemetry for product analytics events:
  • taps: Emits a span for each user click or tap. Defaults to false.
  • pageViews (Android only): Emits spans for screen and page view lifecycle events. Defaults to true.
  • trackEvents (Android only): Emits a span when a custom metric event is created with track(). Defaults to true. To learn more, read Product analytics events.

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

Instrumentation options

The InstrumentationOptions class controls which automatic instrumentation features are active. Pass it to the instrumentation parameter of ObservabilityOptions.

1
ObservabilityOptions(
2
  instrumentation: InstrumentationOptions(
3
    networkRequests: true,
4
    launchTimes: true,
5
    debugPrint: DebugPrintSetting.always(),
6
  ),
7
)

These instrumentation options are available on all platforms:

• networkRequests: When true, automatically instruments HTTP network requests. Defaults to true.
• launchTimes: When true, measures and reports application launch time. Defaults to true.
• debugPrint: Controls whether debugPrint calls are automatically captured as log events:
  • DebugPrintSetting.releaseOnly() (the default) captures debugPrint calls only in release builds.
  • DebugPrintSetting.always() captures debugPrint calls in all build configurations. When enabled, debugPrint output does not appear in the Flutter console.
  • DebugPrintSetting.disabled() does not instrument debugPrint.

The following InstrumentationOptions configuration option is available only on Android and iOS:

• crashReporting: When true, reports uncaught exceptions as errors. Defaults to true.

Intercept print statements

To capture the output from print statements, pass LDObserve.zoneSpecification() to runZonedGuarded:

1
void main() {
2
  runZonedGuarded(
3
    () {
4
      // Initialize and run your app
5
    },
6
    (err, stack) {
7
      LDObserve.recordException(err, stackTrace: stack);
8
    },
9
    zoneSpecification: LDObserve.zoneSpecification(),
10
  );
11
}

Map contexts to friendly names

Use contextFriendlyName to set a human-readable display name for the user’s session when displayed in the observability User Interface (UI):

1
ObservabilityOptions(
2
  contextFriendlyName: 'Bob Smith',
3
)

Configure session replay

Session replay captures screen recordings of user actions to help you understand how users interact with your application. It is included in the launchdarkly_flutter_observability package and uses native iOS and Android libraries to capture and upload recordings.

Session replay for Flutter is supported only on iOS and Android. Web session replay is not yet available.

Initialize session replay

To enable session replay, pass a SessionReplayOptions object to the replay parameter of LDObserve.init or LDObserve.initStandalone, and wrap your app in SessionReplayCapture:

1
import 'dart:async';
2
import 'package:flutter/material.dart';
3
import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
4
import 'package:launchdarkly_flutter_observability/launchdarkly_flutter_observability.dart';
5
6
void main() {
7
  runZonedGuarded(
8
    () {
9
      WidgetsFlutterBinding.ensureInitialized();
10
11
      final client = LDClient(
12
        LDConfig(
13
          'example-mobile-key',
14
          AutoEnvAttributes.enabled,
15
        ),
16
        LDContextBuilder().kind('user', 'example-context-key').build(),
17
      );
18
      client.start();
19
20
      LDObserve.init(
21
        client,
22
        observability: const ObservabilityOptions(
23
          serviceName: 'my-flutter-app',
24
        ),
25
        replay: const SessionReplayOptions(
26
          isEnabled: true,
27
          privacy: PrivacyOptions(maskTextInputs: true),
28
        ),
29
      );
30
31
      FlutterError.onError = (FlutterErrorDetails details) {
32
        LDObserve.recordException(details.exception, stackTrace: details.stack);
33
      };
34
35
      // Wrap your app in SessionReplayCapture to enable screen recording
36
      runApp(const SessionReplayCapture(child: MyApp()));
37
    },
38
    (err, stack) {
39
      LDObserve.recordException(err, stackTrace: stack);
40
    },
41
  );
42
}

SessionReplayCapture widget

Wrap your top-level widget in SessionReplayCapture to allow the native session replay library to capture screen content. On web, SessionReplayCapture is a no-op pass-through, so it is safe to use on every platform:

1
runApp(const SessionReplayCapture(child: MyApp()));

Session replay configuration options

Pass a SessionReplayOptions object to LDObserve.init or LDObserve.initStandalone to control session replay behavior:

1
const SessionReplayOptions(
2
  isEnabled: true,
3
  privacy: PrivacyOptions(
4
    maskTextInputs: true,
5
    maskWebViews: false,
6
    maskLabels: false,
7
    maskImages: false,
8
  ),
9
)

These SessionReplayOptions configuration options are available on all platforms:

• isEnabled: Controls whether session recording starts. Defaults to true.
• privacy: A PrivacyOptions object that controls which UI elements are masked. To learn more, read Privacy options.

The following SessionReplayOptions configuration option is available only on Android and iOS:

• frameRate: Target capture rate in frames per second. Defaults to 1.0.

Privacy options

Use PrivacyOptions to control which elements are masked in session replay recordings. By default, text inputs are masked to protect user data.

1
const PrivacyOptions(
2
  maskTextInputs: true,  // default — masks all text inputs
3
  maskWebViews: false,   // when true, masks WebView content
4
  maskLabels: false,     // when true, masks all text labels
5
  maskImages: false,     // when true, masks all images
6
  minimumAlpha: 0.02,    // views below this alpha are not captured (iOS only)
7
)

The available privacy options are:

• maskTextInputs: Masks all text input fields. Defaults to true.
• maskWebViews: Masks the contents of web views. When enabled, web views appear as blank rectangles in recordings. Defaults to false.
• maskLabels: Masks all text labels. Defaults to false.
• maskImages: Masks all images. Defaults to false.
• minimumAlpha: (iOS only) Minimum alpha value for a view to be captured. Views with a lower alpha are not recorded. Defaults to 0.02.

Per-widget masking

In addition to screen-wide PrivacyOptions, you can redact individual widgets using LDMask and LDUnmask.

Use LDMask to redact a widget’s subtree in all captured frames:

1
LDMask(
2
  child: Text(creditCardNumber),
3
)

Use LDUnmask to exempt a subtree from global masking rules such as maskTextInputs. For example, to reveal one non-sensitive field on a page where every input is masked:

1
// maskTextInputs masks every field; reveal just this one
2
LDUnmask(
3
  child: TextField(controller: searchController),
4
)

LDUnmask only overrides global masking. It does not override an explicit LDMask. An LDUnmask nested inside an LDMask stays masked.

LDMask and LDUnmask are active on iOS and Android. On web they render their child unchanged.

To learn more about session replay configuration, read Configuration for session replay.

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
• Tracing

Review observability data in LaunchDarkly

After you initialize the SDK and observability plugin, your application automatically starts sending observability data back to LaunchDarkly, including errors and logs. You can review this information in the LaunchDarkly user interface. To learn how, read Observability.