Add Session Replay plugin

Introduces the Session Replay plugin for the LaunchDarkly Android SDK, allowing session recording as an extension to Observability.
Refactors plugin and instrumentation management by adding PluginManager and InstrumentationContributor, removes direct instrumentation from Options, and updates ObservabilityClient and InstrumentationManager to support plugin-contributed instrumentations.
Updates documentation and sample usage to reflect the new plugin architecture. Also bumps launchdarkly-android-client-sdk dependency to 5.9.2.

Author: agrognetti

e2e/android/app/build.gradle.kts

@@ -54,7 +54,7 @@ dependencies {
     // Uncomment to use the publicly released version (note this may be behind branch/main)
     // implementation("com.launchdarkly:launchdarkly-observability-android:0.2.0")
 
-    implementation("com.launchdarkly:launchdarkly-android-client-sdk:5.9.0")
+    implementation("com.launchdarkly:launchdarkly-android-client-sdk:5.9.2")
 
     implementation("io.opentelemetry:opentelemetry-api:1.51.0")
     implementation("io.opentelemetry:opentelemetry-sdk:1.51.0")

e2e/android/app/src/main/java/com/example/androidobservability/BaseApplication.kt

@@ -12,6 +12,7 @@ import com.launchdarkly.observability.plugin.Observability
 import com.launchdarkly.observability.replay.PrivacyProfile
 import com.launchdarkly.observability.replay.ReplayInstrumentation
 import com.launchdarkly.observability.replay.ReplayOptions
+import com.launchdarkly.observability.replay.SessionReplay
 import com.launchdarkly.sdk.android.LDAndroidLogging
 import com.launchdarkly.sdk.android.integrations.Plugin
 import io.opentelemetry.api.common.AttributeKey
@@ -32,14 +33,6 @@ open class BaseApplication : Application() {
         ),
         debug = true,
         logAdapter = LDAndroidLogging.adapter(),
-        // TODO: consider these being factories so that the obs plugin can pass instantiation data, log adapter
-        instrumentations = listOf(
-            ReplayInstrumentation(
-                options = ReplayOptions(
-                    privacyProfile = PrivacyProfile(maskText = false)
-                )
-            )
-        ),
     )
 
     var telemetryInspector: TelemetryInspector? = null
@@ -52,6 +45,12 @@ open class BaseApplication : Application() {
             options = testUrl?.let { pluginOptions.copy(backendUrl = it, otlpEndpoint = it) } ?: pluginOptions
         )
 
+        val replayPlugin = SessionReplay(
+            options = ReplayOptions(
+                privacyProfile = PrivacyProfile(maskText = false)
+            )
+        )
+
         // Set LAUNCHDARKLY_MOBILE_KEY to your LaunchDarkly mobile key found on the LaunchDarkly
         // dashboard in the start guide.
         // If you want to disable the Auto EnvironmentAttributes functionality.
@@ -60,7 +59,10 @@ open class BaseApplication : Application() {
             .mobileKey(LAUNCHDARKLY_MOBILE_KEY)
             .plugins(
                 Components.plugins().setPlugins(
-                    Collections.singletonList<Plugin>(observabilityPlugin)
+                    listOf(
+                        observabilityPlugin,
+                        replayPlugin
+                    )
                 )
             )
             .build()

sdk/@launchdarkly/observability-android/README.md

@@ -169,6 +169,31 @@ span.end()
 
 ### Session Replay
 
+#### Enable Session Replay
+
+Add the Session Replay plugin **after** Observability when configuring the LaunchDarkly SDK:
+
+```kotlin
+import com.launchdarkly.observability.plugin.Observability
+import com.launchdarkly.observability.replay.SessionReplay
+
+val ldConfig = LDConfig.Builder(LDConfig.Builder.AutoEnvAttributes.Enabled)
+    .mobileKey("your-mobile-key")
+    .plugins(
+        Components.plugins().setPlugins(
+            listOf(
+                Observability(this@MyApplication, "your-mobile-key"),
+                SessionReplay() // depends on Observability being present first
+            )
+        )
+    )
+    .build()
+```
+
+Notes:
+- SessionReplay depends on Observability. If Observability is missing or listed after SessionReplay, the plugin logs an error and stays inactive.
+- Observability runs fine without SessionReplay; adding SessionReplay extends the Observability pipeline to include session recording.
+
 #### Masking sensitive UI
 
 Use `ldMask()` to mark views that should be masked in session replay. There are helpers for both XML-based Views and Jetpack Compose.

sdk/@launchdarkly/observability-android/lib/build.gradle.kts

@@ -20,7 +20,7 @@ allprojects {
 }
 
 dependencies {
-    implementation("com.launchdarkly:launchdarkly-android-client-sdk:5.9.0")
+    implementation("com.launchdarkly:launchdarkly-android-client-sdk:5.9.2")
     implementation("com.jakewharton.timber:timber:5.0.1")
 
     // Android

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/api/Options.kt

@@ -2,7 +2,6 @@ package com.launchdarkly.observability.api
 
 import com.launchdarkly.logging.LDLogAdapter
 import com.launchdarkly.observability.BuildConfig
-import com.launchdarkly.observability.interfaces.LDExtendedInstrumentation
 import com.launchdarkly.sdk.android.LDTimberLogging
 import io.opentelemetry.api.common.Attributes
 import kotlin.time.Duration
@@ -29,7 +28,6 @@ const val DEFAULT_BACKEND_URL = "https://pub.observability.app.launchdarkly.com"
  * @property disableMetrics Disables metrics if true. Defaults to false.
  * @property logAdapter The log adapter to use. Defaults to using the LaunchDarkly SDK's LDTimberLogging.adapter(). Use LDAndroidLogging.adapter() to use the Android logging adapter.
  * @property loggerName The name of the logger to use. Defaults to "LaunchDarklyObservabilityPlugin".
- * @property instrumentations List of additional instrumentations to use
  */
 data class Options(
     val serviceName: String = DEFAULT_SERVICE_NAME,
@@ -46,6 +44,4 @@ data class Options(
     val disableMetrics: Boolean = false,
     val logAdapter: LDLogAdapter = LDTimberLogging.adapter(), // this follows the LaunchDarkly SDK's default log adapter
     val loggerName: String = "LaunchDarklyObservabilityPlugin",
-    // TODO: update this to provide a list of factories instead of instances
-    val instrumentations: List<LDExtendedInstrumentation> = emptyList()
 )

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/InstrumentationManager.kt

@@ -13,6 +13,7 @@ import com.launchdarkly.observability.sampling.SamplingLogProcessor
 import com.launchdarkly.observability.sampling.SamplingTraceExporter
 import com.launchdarkly.observability.sampling.SpansSampler
 import com.launchdarkly.observability.coroutines.DispatcherProviderHolder
+import com.launchdarkly.observability.interfaces.LDExtendedInstrumentation
 import io.opentelemetry.android.OpenTelemetryRum
 import io.opentelemetry.android.config.OtelRumConfig
 import io.opentelemetry.android.features.diskbuffering.DiskBufferingConfig
@@ -54,18 +55,25 @@ import java.util.concurrent.TimeUnit
 /**
  * Manages instrumentation for LaunchDarkly Observability.
  *
+ * This class is responsible for setting up and managing the OpenTelemetry RUM (Real User Monitoring)
+ * instrumentation. It configures the providers for logs, traces, and metrics based on the
+ * provided options. It also handles dynamic sampling configuration and provides methods to
+ * record various telemetry signals like metrics, logs, and traces.
+ *
  * @param application The application instance.
- * @param sdkKey The SDK key.
+ * @param sdkKey The SDK key for authentication.
  * @param resources The OpenTelemetry resource describing this service.
- * @param logger The logger.
- * @param options Additional options.
+ * @param logger The logger for internal logging.
+ * @param options Additional configuration options for the SDK.
+ * @param instrumentations A list of custom instrumentations to be added.
  */
 class InstrumentationManager(
     private val application: Application,
     private val sdkKey: String,
     private val resources: Resource,
     private val logger: LDLogger,
     private val options: Options,
+    private val instrumentations: List<LDExtendedInstrumentation>,
 ) {
     private val otelRUM: OpenTelemetryRum
     private var otelMeter: Meter
@@ -104,7 +112,8 @@ class InstrumentationManager(
                         resources,
                         logger,
                         telemetryInspector,
-                        options
+                        options,
+                        instrumentations
                     )
                     logProcessor = processor
                     sdkLoggerProviderBuilder.addLogRecordProcessor(processor)
@@ -125,7 +134,7 @@ class InstrumentationManager(
                 }
             }
 
-        for (instrumentation in options.instrumentations) {
+        for (instrumentation in instrumentations) {
             rumBuilder.addInstrumentation(instrumentation)
         }
 
@@ -412,6 +421,7 @@ class InstrumentationManager(
             logger: LDLogger,
             telemetryInspector: TelemetryInspector?,
             options: Options,
+            instrumentations: List<LDExtendedInstrumentation>,
         ): LogRecordProcessor {
             val primaryLogExporter = createOtlpLogExporter(options)
             sdkLoggerProviderBuilder.setResource(resource)
@@ -442,7 +452,7 @@ class InstrumentationManager(
                 pipeline to provide instrumentation specific caching and export.
             */
             val routingLogRecordProcessor = RoutingLogRecordProcessor(fallthroughProcessor = baseProcessor)
-            options.instrumentations.forEach { instrumentation ->
+            instrumentations.forEach { instrumentation ->
                 instrumentation.getLogRecordProcessor(credential = sdkKey)?.let { processor ->
                     instrumentation.getLoggerScopeName().let { scopeName ->
                         routingLogRecordProcessor.addProcessor(scopeName, processor)

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/ObservabilityClient.kt

@@ -3,6 +3,7 @@ package com.launchdarkly.observability.client
 import android.app.Application
 import com.launchdarkly.logging.LDLogger
 import com.launchdarkly.observability.api.Options
+import com.launchdarkly.observability.interfaces.LDExtendedInstrumentation
 import com.launchdarkly.observability.interfaces.Metric
 import com.launchdarkly.observability.interfaces.Observe
 import io.opentelemetry.api.common.Attributes
@@ -14,26 +15,34 @@ import io.opentelemetry.sdk.resources.Resource
  * The [ObservabilityClient] can be used for recording observability data such as
  * metrics, logs, errors, and traces.
  *
- * It is recommended to use the [Observability] plugin with the LaunchDarkly Android
- * Client SDK, as that will automatically initialize the [LDObserve] singleton instance.
+ * It is recommended to use the [com.launchdarkly.observability.plugin.Observability] plugin with the LaunchDarkly Android
+ * Client SDK, as that will automatically initialize the [com.launchdarkly.observability.sdk.LDObserve] singleton instance.
  *
- * @param application The application instance.
- * @param sdkKey The SDK key.
- * @param resource The resource.
- * @param logger The logger.
- * @param options Additional options for the client.
  */
 class ObservabilityClient : Observe {
     private val instrumentationManager: InstrumentationManager
 
+    /**
+     * Creates a new ObservabilityClient.
+     *
+     * @param application The application instance.
+     * @param sdkKey The SDK key for the environment.
+     * @param resource The resource.
+     * @param logger The logger.
+     * @param options Additional options for the client.
+     * @param instrumentations A list of extended instrumentation providers.
+     */
     constructor(
         application: Application,
         sdkKey: String,
         resource: Resource,
         logger: LDLogger,
-        options: Options
+        options: Options,
+        instrumentations: List<LDExtendedInstrumentation>
     ) {
-        this.instrumentationManager = InstrumentationManager(application, sdkKey, resource, logger, options)
+        this.instrumentationManager = InstrumentationManager(
+            application, sdkKey, resource, logger, options, instrumentations
+        )
     }
 
     internal constructor(

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/PluginManager.kt

@@ -0,0 +1,64 @@
+package com.launchdarkly.observability.client
+
+import com.launchdarkly.observability.plugin.InstrumentationContributor
+import com.launchdarkly.observability.plugin.Observability
+import com.launchdarkly.sdk.android.LDClient
+import com.launchdarkly.sdk.android.integrations.Plugin
+import java.util.WeakHashMap
+
+/**
+ * Manages a collection of plugins associated with an [LDClient] instance.
+ *
+ * This object provides a central place to register and retrieve plugins for a given LDClient.
+ * It uses a [WeakHashMap] to store plugins, which allows the [LDClient] instances and
+ * associated plugins to be garbage collected when they are no longer in use.
+ */
+internal object PluginManager {
+    private val plugins = WeakHashMap<LDClient, MutableList<Plugin>>()
+
+    /**
+     * Adds a [Plugin] to the list of plugins associated with the given [LDClient].
+     *
+     * If no plugins have been added for the client before, a new list is created.
+     *
+     * @param client The [LDClient] to associate the plugin with.
+     * @param plugin The [Plugin] to add.
+     */
+    fun add(client: LDClient, plugin: Plugin) {
+        synchronized(plugins) {
+            plugins.getOrPut(client) { mutableListOf() }.add(plugin)
+        }
+    }
+
+    /**
+     * Retrieves the list of [Plugin]s associated with the given [LDClient].
+     *
+     * The returned list is a snapshot and is safe to iterate over.
+     *
+     * @param client The [LDClient] to get the plugins for.
+     * @return A list of [Plugin]s, or null if no plugins are associated with the client.
+     */
+    fun get(client: LDClient): List<Plugin>? = synchronized(plugins) {
+        plugins[client]?.toList()
+    }
+
+    /**
+     * Retrieves the list of [InstrumentationContributor] plugins associated with the given [LDClient].
+     *
+     * @param client The [LDClient] to get the instrumentations for.
+     * @return A list of [InstrumentationContributor]s, or null if no plugins are associated with the client.
+     */
+    fun getInstrumentations(client: LDClient): List<InstrumentationContributor>? = synchronized(plugins) {
+        plugins[client]?.filterIsInstance<InstrumentationContributor>()
+    }
+
+    /**
+     * Checks if the observability plugin has been initialized for the given [LDClient].
+     *
+     * @param client The [LDClient] to check.
+     * @return True if the observability plugin is initialized, false otherwise.
+     */
+    fun isObservabilityInitialized(client: LDClient): Boolean {
+        return get(client)?.any { it.metadata.name == Observability.PLUGIN_NAME } == true
+    }
+}

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/plugin/InstrumentationContributor.kt

@@ -0,0 +1,10 @@
+package com.launchdarkly.observability.plugin
+import com.launchdarkly.observability.interfaces.LDExtendedInstrumentation
+
+/**
+ * Plugins can implement this to contribute OpenTelemetry instrumentations that should
+ * be installed by the Observability plugin.
+ */
+interface InstrumentationContributor {
+    fun provideInstrumentations(): List<LDExtendedInstrumentation>
+}