Flutter SDK observability reference

​

Prerequisites and dependencies

• The LaunchDarkly Flutter SDK version 4.18.0 or later
• Flutter 3.27 or later
• An iOS deployment target of 15.0 or later
• Android SDK version 24 or later (Android 7.0, Nougat)

​

Get started

• Install the package
• Initialize observability
• Configure plugin options
• Configure session replay
• Record screen views
• Record taps
• Manually instrument your app
• Explore supported features
• Review observability data in LaunchDarkly

​

Install the package

dependencies:
  launchdarkly_flutter_client_sdk: ^4.18.0
  launchdarkly_flutter_observability: ^1.0.0

flutter pub get

platform :ios, '15.0'

cd ios && pod install && cd ..

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

​

Initialize observability

​

Initialize with a LaunchDarkly client

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
import 'package:launchdarkly_flutter_observability/launchdarkly_flutter_observability.dart';

void main() {
  runZonedGuarded(
    () {
      WidgetsFlutterBinding.ensureInitialized();

      final client = LDClient(
        LDConfig(
          'example-mobile-key',
          AutoEnvAttributes.enabled,
        ),
        LDContextBuilder().kind('user', 'example-context-key').build(),
      );
      client.start();

      LDObserve.init(
        client,
        observability: const ObservabilityOptions(
          serviceName: 'my-flutter-app',
        ),
      );

      // Report errors caught by the Flutter framework
      FlutterError.onError = (FlutterErrorDetails details) {
        LDObserve.recordException(details.exception, stackTrace: details.stack);
      };

      runApp(const MyApp());
    },
    (err, stack) {
      // Report uncaught errors from the zone
      LDObserve.recordException(err, stackTrace: stack);
    },
  );
}

​

Initialize standalone

await LDObserve.initStandalone(
  'example-mobile-key',
  observability: const ObservabilityOptions(
    serviceName: 'my-flutter-app',
  ),
);

​

Configure plugin options

LDObserve.init(
  client,
  observability: ObservabilityOptions(
    serviceName: 'my-flutter-app',
    // Recommended: set to the latest deployed git SHA or semantic version
    serviceVersion: 'example-sha',
    instrumentation: InstrumentationOptions(
      launchTimes: true,
      debugPrint: DebugPrintSetting.releaseOnly(),
    ),
  ),
);

• isEnabled: Enables or disables observability telemetry. Defaults to true. When false, the plugin records no spans, logs, errors, flag evaluation spans, lifecycle spans, or debugPrint output, and exports nothing on web. Session replay is controlled separately with SessionReplayOptions.isEnabled. While session replay is on, screen views, taps, and track events still reach the replay timeline.
• serviceName: The service name for telemetry. Defaults to "observability-flutter", which names the plugin rather than your app. Set it to identify your app.
• serviceVersion: The service version, commonly a Git SHA or semantic version string. This option is optional. If you omit it, Android and iOS report your app’s own version, which Flutter sets from the version in your pubspec.yaml, and web omits service.version.
• instrumentation: An InstrumentationOptions object that controls automatic instrumentation. To learn more, read Instrumentation options.
• otlpEndpoint: The OpenTelemetry Protocol (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 OpenTelemetry resource attributes to attach to every signal the plugin exports. For example, {'deployment.environment': 'staging'}. If one of your attributes uses the same key as an attribute the plugin sets, such as a service.* key or the project identifier, the plugin’s value wins.
• analytics: An AnalyticsOptions object that controls telemetry for product analytics events. Use AnalyticsOptions.enabled to enable all types or AnalyticsOptions.disabled to disable all:
  • taps: Emits a click span for each user tap. Defaults to true. Setting this to false also stops tap detection, rather than detecting taps without publishing them. To learn more, read Record taps.
  • views: Emits a screen_view span for each screen view. Defaults to true. To learn more, read Record screen views.
  • trackEvents: Emits a track span when a custom event is tracked with track(). Defaults to true.
  • appLifecycle: Emits app lifecycle spans. Defaults to true. On every platform, including web, this option gates the Dart device.app.lifecycle span that the plugin emits on each Flutter AppLifecycleState change. On Android and iOS, it also gates the native app_foreground and app_background spans.
  • appLaunch (Android and iOS): Emits an app_launch span once per process launch. The span carries the launch type, which is install, update, or relaunch, along with version information and an app.start span event that records the cold or warm startup dimension. Defaults to true. InstrumentationOptions.launchTimes separately controls launch time measurement.
  • customClickTargetResolver: A function that names your own widget types as tap targets. To learn more, read Name your own widget types. To learn more, read Product analytics events.

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

​

Instrumentation options

ObservabilityOptions(
  instrumentation: InstrumentationOptions(
    launchTimes: true,
    debugPrint: DebugPrintSetting.always(),
  ),
)

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

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

​

Intercept print statements

void main() {
  runZonedGuarded(
    () {
      // Initialize and run your app
    },
    (err, stack) {
      LDObserve.recordException(err, stackTrace: stack);
    },
    zoneSpecification: LDObserve.zoneSpecification(),
  );
}

​

Map contexts to friendly names

ObservabilityOptions(
  contextFriendlyName: 'Bob Smith',
)

​

Configure product analytics event collection

• Track events (manual, all platforms): A track span recorded when your code calls LDObserve.track(). The trackEvents flag in AnalyticsOptions controls whether the span is emitted. To learn more, read Recording product analytics events.
• Taps (automatic, all platforms): A click span for each user tap, with the widget type, identifier, visible label, widget ancestry path, and coordinates. Enabled by default. Tap capture requires the SessionReplayCapture widget. To learn more, read Record taps.
• Screen views (automatic or manual, all platforms): A screen_view span when your app shows a screen, with the screen name and optional details such as the screen class, screen identifier, and category. Enabled by default. Screen views are reported from your Dart code, either by the LDNavigatorObserver or by a call to LDObserve.trackScreenView. To learn more, read Record screen views.
• App lifecycle (automatic, all platforms): A device.app.lifecycle span on each Flutter AppLifecycleState change. On Android and iOS, the plugin also emits a native app_foreground or app_background span as the app moves between the foreground and background states. Enabled by default.
• App launches (automatic, Android and iOS): An app_launch span once per process launch. The span carries the launch type, which is install, update, or relaunch, along with version information and an app.start span event that records the cold or warm startup dimension. Enabled by default. To learn more, read App launch events.

ObservabilityOptions(
  analytics: AnalyticsOptions.enabled,
)

ObservabilityOptions(
  analytics: AnalyticsOptions(
    trackEvents: true,   // all platforms
    taps: true,          // all platforms
    views: true,         // all platforms
    appLifecycle: true,  // all platforms
    appLaunch: true,     // Android and iOS
  ),
)

• taps: Gates the Dart-side tap detection as well as the click span. Setting it to false stops the plugin from resolving tapped widgets at all. On Android and iOS, the session replay Click timeline event is recorded regardless of this setting.
• views: Gates the screen_view span only. On Android and iOS, the session replay Navigate timeline event is recorded regardless of this setting.
• appLifecycle: Gates the Dart device.app.lifecycle span on every platform. On Android and iOS, it also gates the native app_foreground and app_background spans.

​

Configure session replay

​

Initialize session replay

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
import 'package:launchdarkly_flutter_observability/launchdarkly_flutter_observability.dart';

void main() {
  runZonedGuarded(
    () {
      WidgetsFlutterBinding.ensureInitialized();

      final client = LDClient(
        LDConfig(
          'example-mobile-key',
          AutoEnvAttributes.enabled,
        ),
        LDContextBuilder().kind('user', 'example-context-key').build(),
      );
      client.start();

      LDObserve.init(
        client,
        observability: const ObservabilityOptions(
          serviceName: 'my-flutter-app',
        ),
        replay: const SessionReplayOptions(
          isEnabled: true,
          privacy: PrivacyOptions(maskTextInputs: true),
        ),
      );

      FlutterError.onError = (FlutterErrorDetails details) {
        LDObserve.recordException(details.exception, stackTrace: details.stack);
      };

      // Wrap your app in SessionReplayCapture to enable screen recording
      runApp(const SessionReplayCapture(child: MyApp()));
    },
    (err, stack) {
      LDObserve.recordException(err, stackTrace: stack);
    },
  );
}

​

SessionReplayCapture widget

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

​

Session replay configuration options

const SessionReplayOptions(
  isEnabled: true,
  privacy: PrivacyOptions(
    maskTextInputs: true,
    maskWebViews: false,
    maskLabels: false,
    maskImages: false,
  ),
)

• isEnabled: Controls whether session recording starts on Android and iOS. Defaults to true. This option has no effect on web, where session replay is not supported.
• privacy: A PrivacyOptions object that controls which UI elements are masked. To learn more, read Privacy options.
• serviceName: The service name reported for session replay telemetry. Defaults to "sessionreplay-flutter".

• sampleRate: Probability from 0.0 to 1.0 that session replay starts when enabled. Defaults to 1.0.
• frameRate: Target capture rate in frames per second. Defaults to 1.0.
• scale: The resolution multiplier for captured frames, where 1.0 is 1x (160 DPI) and 2.0 is 2x. Higher values capture more detail but produce larger frames. A null value is treated as 1.0. Defaults to 1.0.
• imageQuality: The JPEG encoding quality of exported frames, from 0.0 (lowest quality, smallest payload) to 1.0 (highest quality, largest payload). Values outside that range are clamped. Defaults to 0.3.

​

Privacy options

const PrivacyOptions(
  maskTextInputs: true,  // default — masks all text inputs
  maskWebViews: false,   // when true, masks WebView content
  maskLabels: false,     // when true, masks all text labels
  maskImages: false,     // when true, masks all images
  minimumAlpha: 0.02,    // widgets below this opacity are not captured
  maskClickText: false,  // when true, drops the label from click events
)

• 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: The opacity threshold, from 0.0 to 1.0, below which the plugin treats a widget as invisible and skips it during capture and masking. Raise it to ignore nearly transparent UI. Defaults to 0.02.
• maskClickText: Drops the visible label from click events. Taps report the widget type and identifier but no text. Defaults to false. This option is independent of maskLabels, which controls whether the plugin paints over text in captured frames. To learn more, read Record taps.

​

Per-widget masking

LDMask(
  child: Text(creditCardNumber),
)

LDIgnore(
  child: VideoPlayer(controller),
)

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

​

Mask by widget type or key

PrivacyOptions(
  maskWidgetTypes: {CreditCardField},
  maskWidgetKeys: {const ValueKey('ssn-field')},
  unmaskWidgetTypes: {SearchBox},
  ignoreWidgetTypes: {LiveCameraPreview},
)

• maskWidgetTypes: A set of widget Types to mask wherever they appear. Defaults to an empty set.
• maskWidgetKeys: A set of widget Keys to mask wherever they appear. Defaults to an empty set.
• unmaskWidgetTypes: A set of widget Types to reveal from global masking. Defaults to an empty set.
• unmaskWidgetKeys: A set of widget Keys to reveal from global masking. Defaults to an empty set.
• ignoreWidgetTypes: A set of widget Types to ignore. Defaults to an empty set.
• ignoreWidgetKeys: A set of widget Keys to ignore. Defaults to an empty set.

​

Record screen views

​

Record screen views automatically

MaterialApp(
  navigatorObservers: [LDNavigatorObserver()],
  // ...
);

Navigator.of(context).push(
  MaterialPageRoute<void>(
    settings: const RouteSettings(name: '/checkout'),
    builder: (_) => const CheckoutPage(),
  ),
);

MaterialApp(
  navigatorObservers: [
    LDNavigatorObserver(
      screenNameExtractor: (route) =>
          route.settings.name ?? route.settings.arguments?.toString(),
      category: 'navigation',
    ),
  ],
);

​

Report route patterns instead of URLs

LDNavigatorObserver(
  screenNameExtractor: LDRoutePatterns.extractor(const [
    '/orders',
    '/orders/new', // A literal listed first wins over '/orders/:id'.
    '/orders/:id',
    '/orders/:id/receipt',
  ]),
);

• A :name segment matches exactly one path segment.
• A trailing * matches the rest of the path.

​

Navigation an observer cannot see

• Nested navigators: A tab shell, or a Navigator inside a page, reports only its own routes. Create a separate observer instance for each navigator.
• MaterialApp.router: Routers such as go_router, auto_route, and Beamer do not accept navigatorObservers. Pass the observer to the router’s own observer list instead, such as GoRouter(observers: [LDNavigatorObserver()]).
• GetMaterialApp: GetX merges the observers you pass with its own, so navigatorObservers: [LDNavigatorObserver()] works the same way it does on MaterialApp. GetMaterialApp.router is the exception. It accepts navigatorObservers and then builds its delegate without them, so pass them as routerDelegate: GetDelegate(navigatorObservers: [LDNavigatorObserver()]) instead.
• Navigation that leaves the route stack unchanged: Switching tabs in an IndexedStack, or paging a PageView, is invisible to any observer. Record these screen views manually.

​

Record screen views manually

LDObserve.trackScreenView(
  'Checkout',
  screenClass: 'CheckoutPage',
  category: 'commerce',
  properties: <String, Object?>{'cart_size': 3},
);

​

Record taps

​

Tap event attributes

• Material and Cupertino buttons, including IconButton and FloatingActionButton
• Selection controls, including Switch, Checkbox, Radio, and Slider
• Chips, tabs, and menus, including PopupMenuButton and DropdownButton
• Navigation bars
• ListTile, InkWell, and GestureDetector

​

Name a widget with LDClick

LDClick(
  id: 'checkout.pay',
  properties: <String, Object?>{'cart_size': 3},
  child: ElevatedButton(onPressed: _pay, child: const Text('Pay')),
);

​

Name your own widget types

ObservabilityOptions(
  analytics: AnalyticsOptions(
    customClickTargetResolver: (widget) => switch (widget) {
      PrimaryButton(:final label) =>
        LDClickTargetInfo(tag: 'PrimaryButton', text: label),
      _ => null,
    },
  ),
);

• tag: The widget type name reported as event.tag. Required.
• id: A stable identifier for the instance, reported as event.id.
• text: The visible label, reported as event.text. If you omit it, the plugin falls back to its usual text extraction.
• preferInnerTarget: When true, a more specific target nested inside this widget is reported instead. Set this for containers that only make a region tappable, such as a card or a row, to ensure that the plugin reports a button inside the containers. Defaults to false.

​

Record taps manually

LDObserve.trackClick(
  id: 'onboarding.shake_to_skip',
  tag: 'ShakeGesture',
  x: 24,
  y: 80,
  properties: <String, Object?>{'step': 2},
);

​

Tap capture limitations

• Only taps count as clicks. The plugin does not report a press that moves further than kTouchSlop, such as a scroll or a drag, a press that outlasts the long press timeout, or any multi-touch gesture. The native SDKs apply the same rule, which keeps Flutter and native clicks comparable.
• Embedded platform views resolve to their host widget. A tap in a WebView or a native map reports the Flutter widget hosting it, such as WebViewWidget. The plugin does not describe what the user pressed inside the embedded view.
• Pointer-blocking overlays are honored. An IgnorePointer is transparent to the plugin, because the tap passed through it. Because an AbsorbPointer, such as a loading overlay laid over a Stack, consumes the tap, the plugin reports neither its children nor the controls painted behind it. This matches what Flutter delivered to your app.
• Tap labels follow your masking rules. The plugin never reports text inside an LDMask or LDIgnore subtree, and never reads the contents of an editable field. Setting maskClickText in PrivacyOptions turns off tap labels entirely while still recording the taps. To learn more, read Privacy options.

​

Manual instrumentation

​

Recording custom logs

// Record a basic log message
LDObserve.recordLog(
  'User login successful',
  severity: LogSeverity.info,
);

// Record a log with custom properties
LDObserve.recordLog(
  'Authentication completed',
  severity: LogSeverity.info,
  properties: <String, Object?>{
    'user_id': '12345',
    'action': 'login',
  },
);

// Record a log with a stack trace
LDObserve.recordLog(
  'Checkout failed',
  severity: LogSeverity.error,
  stackTrace: StackTrace.current,
);

final span = LDObserve.startSpan('checkout-flow');
LDObserve.recordLog(
  'Processing on the same trace',
  severity: LogSeverity.warn,
  properties: <String, Object?>{'source': 'checkout'},
);
span.end();

​

Record errors

try {
  await processPayment();
} catch (e, stack) {
  LDObserve.recordException(e, stackTrace: stack);
}

​

Recording custom traces

// Start a span with custom properties
final span = LDObserve.startSpan(
  'database_query',
  properties: <String, Object?>{
    'table': 'users',
    'operation': 'select',
  },
);

// Perform your operation
await performDatabaseQuery();

// Always end the span
span.end();

• setAttribute(name, value): Sets a single attribute on the span.
• setAttributes(map): Sets multiple attributes on the span.
• addEvent(name, ): Records a named event on the span.
• setStatus(SpanStatusCode): Sets the span status to ok, error, or unset.
• recordException(exception, ): Records an exception on the span.
• end(): Ends the span.

final span1 = LDObserve.startSpan('SequentialOperation1');
span1.setAttribute('sequence', '1');
span1.end();

final span2 = LDObserve.startSpan('SequentialOperation2');
span2.setAttribute('sequence', '2');
span2.end();

​

Record scoped spans

final orders = await LDObserve.withSpan('load-orders', (span) async {
  span.setAttribute('page', 1);
  return api.fetchOrders(page: 1);
});

final response = await LDObserve.withSpan('api_request', (span) async {
  span.setAttribute('endpoint', '/api/users');
  span.setAttribute('method', 'GET');
  return httpClient.get(Uri.parse('https://api.example.com/api/users'));
});

​

Attribute and property values

​

Recording product analytics events

// Track an event with properties and an optional metric value
LDObserve.track(
  'purchase_completed',
  properties: <String, Object?>{
    'product_id': 'SKU-123',
    'price': 29.99,
  },
  metricValue: 29.99,
);

// Track an event with no properties
LDObserve.track('button_tapped');

​

Shut down observability

await LDObserve.shutdown();

​

Identify contexts

final userContext = LDContextBuilder()
    .kind('user', 'user-key')
    .name('Bob Smith')
    .build();
await client.identify(userContext);

​

Explore supported features

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

​

Review observability data in LaunchDarkly