LaunchDarkly.SessionReplay 0.13.0

LaunchDarkly Observability SDK for .NET MAUI

The LaunchDarkly Observability SDK for .NET MAUI provides automatic and manual instrumentation for your mobile application, including metrics, logs, error reporting, and session replay.

Early Access Preview

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

Features

Automatic Instrumentation

The .NET MAUI observability plugin automatically instruments:

• HTTP Requests: Outgoing HTTP requests made through HttpClient (instrumentation.networkRequests; requires HttpActivityPropagationSupport, see Enabling HTTP request tracing)
• Launch Times: App launch performance (instrumentation.launchTimes)
• Feature Flag Evaluations: Evaluation events added to your spans
• Session Management: User session tracking and background timeout handling

Automatic crash reporting is not enabled yet; use LDObserve.RecordError to report exceptions.

Prerequisites

• .NET 9 or .NET 10 with the MAUI workload.
• Android API 23 or later and iOS 15 or later.

Enabling HTTP request tracing

HTTP tracing needs one setting in your app's project file:

<PropertyGroup>
  <HttpActivityPropagationSupport>true</HttpActivityPropagationSupport>
</PropertyGroup>

The Android SDK sets this to false by default in every configuration, and the iOS SDK sets it to false in Release builds. While it is false, the trimmer removes the System.Net.Http diagnostics that the SDK listens to, so no HTTP spans are recorded even with networkRequests: true. The SDK cannot turn it back on at runtime.

Example Application

A complete example application is available in the sample directory. MauiSample9.csproj builds it for .NET 9 and MauiSample10.csproj for .NET 10; both share the same sources.

Usage

Basic Setup

Initialize observability with LDObserve.Init. There are two variants depending on whether you use a LaunchDarkly client.

With a LaunchDarkly client

Pass your initialized LdClient to LDObserve.Init. This registers the ObservabilityPlugin on the client so feature flag evaluations are correlated with your telemetry:

using LaunchDarkly.Observability;
using LaunchDarkly.Sdk;
using LaunchDarkly.Sdk.Client;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        // ... other configuration ...

        var mobileKey = "your-mobile-key";

        var ldConfig = Configuration.Builder(mobileKey, ConfigurationBuilder.AutoEnvAttributes.Enabled).Build();
        var context = Context.New("maui-user-key");
        var client = LdClient.Init(ldConfig, context, TimeSpan.FromSeconds(10));

        LDObserve.Init(client, new ObservabilityOptions(
            isEnabled: true,
            serviceName: "maui-sample-app"
        ));

        return builder.Build();
    }
}

Alternatively, register the plugin yourself when building the client configuration. ObservabilityPlugin takes the same options, including optional SessionReplayOptions as its second argument:

using LaunchDarkly.Sdk.Client.Integrations;
using LaunchDarkly.SessionReplay;

var ldConfig = Configuration.Builder(mobileKey, ConfigurationBuilder.AutoEnvAttributes.Enabled)
    .Plugins(new PluginConfigurationBuilder()
        .Add(new ObservabilityPlugin(
            new ObservabilityOptions(isEnabled: true, serviceName: "maui-sample-app"),
            new SessionReplayOptions(isEnabled: true))))
    .Build();
var client = LdClient.Init(ldConfig, context, TimeSpan.FromSeconds(10));

Standalone (without a LaunchDarkly client)

If you are not using the LaunchDarkly client, pass your mobile key directly. This boots the native observability stack without registering a plugin:

using LaunchDarkly.Observability;
using LaunchDarkly.SessionReplay;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        // ... other configuration ...

        var mobileKey = "your-mobile-key";

        LDObserve.Init(
            mobileKey,
            new ObservabilityOptions(
                isEnabled: true,
                serviceName: "maui-sample-app"
            ),
            new SessionReplayOptions(
                isEnabled: true,
                privacy: new(
                    maskTextInputs: true,
                    maskWebViews: false,
                    maskLabels: false
                )
            )
        );

        return builder.Build();
    }
}

Observability Options

ObservabilityOptions accepts the following settings, all optional:

var observabilityOptions = new ObservabilityOptions(
    serviceName: "my-maui-app",
    serviceVersion: "2.4.0",
    customHeaders: new Dictionary<string, string> { { "X-Proxy-Token", "..." } },
    logsApiLevel: ObservabilityLogLevel.Warn
);

After initialization, LDObserve.NativeVersion returns the version of the underlying native observability SDK, which is useful in diagnostics and support requests.

Recording Observability Data

After initialization of the LaunchDarkly client, use LDObserve to record metrics, logs, and errors:

using LaunchDarkly.Observability;

// Record metrics
LDObserve.RecordMetric("user_actions", 1.0);
LDObserve.RecordCount("api_calls", 1.0);
LDObserve.RecordIncr("page_views", 1.0);
LDObserve.RecordHistogram("response_time", 150.0);
LDObserve.RecordUpDownCounter("active_connections", 1.0);

// Record logs with severity and optional attributes
LDObserve.RecordLog(
    "User performed action",
    Severity.Info,
    new Dictionary<string, object?>
    {
        { "user_id", "12345" },
        { "action", "button_click" }
    }
);

// Record errors from an exception
var exception = new Exception("Something went wrong", new InvalidOperationException("root cause"));
LDObserve.RecordError(exception);

// Or record errors from a message string
LDObserve.RecordError("Something went wrong", "The underlying cause of the error.");

Metrics

Logs

Use RecordLog to emit structured log records with a severity level and optional attributes:

LDObserve.RecordLog(
    "Checkout completed",
    Severity.Info,
    new Dictionary<string, object?>
    {
        { "order_id", "ORD-9876" },
        { "total", 42.99 }
    }
);

Supported severity levels: Trace, Debug, Info, Warn, Error, Fatal, each with numbered variants (for example Info2 to Info4) matching the OpenTelemetry severity numbers.

Logs with Span Context

You can correlate logs with a specific span for distributed tracing by capturing and passing a SpanContext:

var span = LDObserve.StartActiveSpan("checkout-flow");
var capturedContext = span.Context;
span.End();

await Task.Run(() =>
{
    LDObserve.RecordLog(
        "Checkout processed on background thread",
        Severity.Warn,
        new Dictionary<string, object?> { { "source", "background-task" } },
        spanContext: capturedContext);
});

This is useful when a log is emitted on a different thread or after the span has ended, but you still want it associated with the original trace.

Errors

Use RecordError to capture error events. You can pass an Exception object directly, or a message string with an optional cause:

// From an exception (inner exceptions are captured automatically)
var exception = new Exception("Payment failed", new TimeoutException("Connection timed out"));
LDObserve.RecordError(exception);

// From a message string with optional cause
LDObserve.RecordError("Payment failed", "Timeout connecting to payment gateway.");

Traces

For in-depth examples covering nested spans, error handling, manual context propagation, and more, see the Distributed Tracing Guide.

Use LDObserve to create spans for tracing operations in your application. Spans are backed by OpenTelemetry and should be disposed when the operation completes.

Create spans to trace operations. The returned TelemetrySpan is disposable — wrap it in a using statement so it ends automatically:

using var span = LDObserve.StartActiveSpan("api_request");
span.SetAttribute("endpoint", "/api/users");
span.SetAttribute("method", "GET");
span.AddEvent("cache.miss");

Nested Spans

StartActiveSpan automatically creates parent-child relationships. Each new active span becomes a child of the currently active span:

using var parent = LDObserve.StartActiveSpan("ProcessOrder");
using var child = LDObserve.StartActiveSpan("ValidatePayment");
using var grandchild = LDObserve.StartActiveSpan("ChargeCard");

await httpClient.PostAsync("https://api.example.com/charge", content);

Independent Root Spans

Use StartRootSpan to create spans that are independent of the current trace context. This is useful for sequential operations that should not be nested:

using (var span1 = LDObserve.StartRootSpan("SequentialOperation1"))
{
    span1.SetAttribute("sequence", "1");
}

using (var span2 = LDObserve.StartRootSpan("SequentialOperation2"))
{
    span2.SetAttribute("sequence", "2");
}

Manual Span Lifecycle

You can also manage a span's lifecycle manually using End() and capture its Context for distributed tracing:

var span = LDObserve.StartActiveSpan("my-operation");
span.SetAttribute("key", "value");
var capturedContext = span.Context;
span.End();

Using System.Diagnostics.Activity

If you prefer the native .NET Activity API over OpenTelemetry's TelemetrySpan, equivalent methods are available. Activities are nullable — StartActivity returns null before SDK initialization or when no listener is registered:

using System.Diagnostics;

using var activity = LDObserve.StartActivity("api_request");
activity?.SetTag("endpoint", "/api/users");
activity?.SetTag("method", "GET");
activity?.AddEvent(new ActivityEvent("cache.miss"));

// Root activity (no parent), equivalent to StartRootSpan
using var root = LDObserve.StartRootActivity("independent-operation");
root?.SetTag("sequence", "1");

// Or get the ActivitySource directly for full control
var source = LDObserve.GetActivitySource();
using var custom = source.StartActivity("custom", ActivityKind.Client);

Identifying Users

Use the LaunchDarkly client to identify or switch user contexts. This ties observability data to the correct user:

using LaunchDarkly.Sdk;
using LaunchDarkly.Sdk.Client;

// Single context
var userContext = Context.Builder("user-key")
    .Name("Bob Bobberson")
    .Build();
await LdClient.Instance.IdentifyAsync(userContext);

// Multi-context
var userContext = Context.Builder("user-key")
    .Name("Bob Bobberson")
    .Build();
var deviceContext = Context.Builder(ContextKind.Of("device"), "iphone")
    .Name("iphone")
    .Build();
var multiContext = Context.MultiBuilder()
    .Add(userContext)
    .Add(deviceContext)
    .Build();
LdClient.Instance.Identify(multiContext, TimeSpan.FromSeconds(5));

// Anonymous context
var anonContext = Context.Builder("anonymous-key")
    .Anonymous(true)
    .Build();
LdClient.Instance.Identify(anonContext, TimeSpan.FromSeconds(5));

Session Replay

Session Replay captures user interactions and screen recordings to help you understand how users interact with your application. To enable Session Replay, pass SessionReplayOptions as the third argument to LDObserve.Init:

using LaunchDarkly.SessionReplay;
using LaunchDarkly.Observability;
using LaunchDarkly.Sdk;
using LaunchDarkly.Sdk.Client;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        // ... other configuration ...

        var mobileKey = "your-mobile-key";

        var ldConfig = Configuration.Builder(mobileKey, ConfigurationBuilder.AutoEnvAttributes.Enabled).Build();
        var context = Context.New("maui-user-key");
        var client = LdClient.Init(ldConfig, context, TimeSpan.FromSeconds(10));

        LDObserve.Init(
            client,
            new ObservabilityOptions(
                isEnabled: true,
                serviceName: "maui-sample-app",
                instrumentation: new(
                    networkRequests: true,
                    launchTimes: true
                )
            ),
            new SessionReplayOptions(
                isEnabled: true,
                privacy: new(
                    maskTextInputs: true,
                    maskWebViews: false,
                    maskLabels: false
                )
            )
        );

        return builder.Build();
    }
}

The same third argument works with the standalone variant: LDObserve.Init(mobileKey, observabilityOptions, sessionReplayOptions).

Capture Options

SessionReplayOptions controls how often and at what quality frames are captured:

• SampleRate: (Default: 1.0) Probability from 0.0 to 1.0 that a session is recorded when replay is enabled. 0.25 records about a quarter of sessions.
• FrameRate: (Default: 1.0) Target capture rate in frames per second.
• Scale: (Default: 1.0) Capture resolution: 1.0 is 1x (160 DPI), 2.0 is 2x, and so on. Higher values capture more detail but produce larger frames.
• ImageQuality: (Default: 0.3) JPEG quality of exported frames, from 0.0 (smallest) to 1.0 (best).

var replayOptions = new SessionReplayOptions(
    isEnabled: true,
    sampleRate: 0.25,
    frameRate: 2.0,
    scale: 1.5,
    imageQuality: 0.5
);

Privacy Options

You can control what information is captured during a session using PrivacyOptions:

• MaskTextInputs: (Default: true) Masks all text input fields.
• MaskWebViews: (Default: false) Masks all web view content.
• MaskLabels: (Default: false) Masks all text labels.
• MaskImages: (Default: false) Masks all images.
• MinimumAlpha: (Default: 0.02) Opacity below which a view is treated as invisible and not masked.
• MaskViewTypes: MAUI view types to mask wherever they appear.
• UnmaskViewTypes: MAUI view types to reveal from the global masking settings above.
• IgnoreViewTypes: MAUI view types to leave out of recordings. On Android they are masked instead, because the native Android SDK has no per-view ignore.

View types match exactly, so a subclass must be listed separately from its base type:

var replayOptions = new SessionReplayOptions(
    isEnabled: true,
    privacy: new SessionReplayOptions.PrivacyOptions(
        maskLabels: true,
        maskViewTypes: new List<Type> { typeof(CreditCardView) },
        unmaskViewTypes: new List<Type> { typeof(PriceLabel) },
        ignoreViewTypes: new List<Type> { typeof(VideoPlayerView) }
    )
);

Manual Masking

You can manually mask, unmask, or ignore specific UI components using the provided extension methods on any MAUI View. Call them once the view has been attached to the screen (its Handler is set), for example from OnHandlerChanged or a page's OnAppearing; before that they have no effect.

using LaunchDarkly.SessionReplay;

// Mask a specific view
mySensitiveView.LDMask();

// Unmask a specific view
myPublicView.LDUnmask();

// Leave a view out of recordings (masked instead on Android)
myVideoView.LDIgnore();

Contributing

We encourage pull requests and other contributions from the community. Check out our contributing guidelines for instructions on how to contribute to this SDK.

About LaunchDarkly

• 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
  • launchdarkly.com for more information
  • docs.launchdarkly.com for our documentation and SDK reference guides
  • apidocs.launchdarkly.com for our API documentation
  • launchdarkly.com/blog for the latest product updates