feat: O11Y-359 - Add custom sampling for OTLP logs and traces (#189)

## Summary

This commit introduces a custom sampling mechanism for OpenTelemetry
(OTLP) logs and traces within the Android observability SDK. This allows
for more granular control over which telemetry data is exported, helping
to manage data volume and focus on relevant information.

The architecture and implementation are mostly based on the
[observability-node](https://github.com/launchdarkly/observability-sdk/tree/main/sdk/%40launchdarkly/observability-node)
project

The key additions include:
- `CustomSampler`: A class that implements sampling logic based on a
`SamplingConfig`.
- `SamplingConfig`: Data classes defining the structure for configuring
sampling rules for spans and logs.
- `ExportSampler`: An interface defining the contract for samplers that
operate during the export phase.
- `SamplingTraceExporter` and `SamplingLogExporter`: Decorator classes
that wrap the standard `OtlpHttpSpanExporter` and
`OtlpHttpLogRecordExporter` respectively. They use the `CustomSampler`
to filter spans/logs before delegating to the underlying exporter.
- `SamplingResult`: A data class to hold the outcome of a sampling
decision (whether to sample and any additional attributes).
- `sampleSpans` and `sampleLogs`: Utility functions that take a list of
spans or logs and an `ExportSampler` to filter them based on sampling
decisions.

What is not included:
- Fetching sampling configuration from the backend service
- Setting sampling configuration to the CustomSampler

## How did you test this change?
Unit testing

## Are there any deployment considerations?
Since the sample configuration isn't being retrieved from the backend
yet, null is currently passed as the config. This means no data will be
sampled.

---------

Co-authored-by: Todd Anderson <127344469+tanderson-ld@users.noreply.github.com>

Author: agrognetti

sdk/@launchdarkly/observability-android/gradle/libs.versions.toml

@@ -2,10 +2,12 @@
 # https://docs.gradle.org/current/userguide/platforms.html#sub::toml-dependencies-format
 
 [versions]
-junit-jupiter = "5.12.1"
+junit-jupiter = "5.13.4"
 
 [libraries]
-junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }
+junit-bom = { module = "org.junit:junit-bom", version.ref = "junit-jupiter" }
+junit-jupiter = { module = "org.junit.jupiter:junit-jupiter" }
+junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher" }
 
 [plugins]
 kotlin-android = { id = "org.jetbrains.kotlin.android", version = "2.1.20" }

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

@@ -39,12 +39,20 @@ dependencies {
     implementation("io.opentelemetry.android.instrumentation:crash:0.11.0-alpha")
 
     // Use JUnit Jupiter for testing.
-    testImplementation("org.junit.jupiter:junit-jupiter")
-    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+    testImplementation(platform(libs.junit.bom))
+    testImplementation(libs.junit.jupiter)
+    testRuntimeOnly(libs.junit.platform.launcher)
+
+    // MockK for mocking in Kotlin tests
+    testImplementation("io.mockk:mockk:1.14.5")
 }
 
 val releaseVersion = version.toString()
 
+tasks.withType<Test> {
+    useJUnitPlatform()
+}
+
 android {
     namespace = "com.launchdarkly.observability"
     compileSdk = 30

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

@@ -4,6 +4,10 @@ import android.app.Application
 import com.launchdarkly.logging.LDLogger
 import com.launchdarkly.observability.api.Options
 import com.launchdarkly.observability.interfaces.Metric
+import com.launchdarkly.observability.sampling.CompositeLogExporter
+import com.launchdarkly.observability.sampling.CustomSampler
+import com.launchdarkly.observability.sampling.SamplingLogExporter
+import com.launchdarkly.observability.sampling.SamplingTraceExporter
 import io.opentelemetry.android.OpenTelemetryRum
 import io.opentelemetry.android.config.OtelRumConfig
 import io.opentelemetry.android.session.SessionConfig
@@ -17,7 +21,10 @@ import io.opentelemetry.context.Context
 import io.opentelemetry.exporter.otlp.http.logs.OtlpHttpLogRecordExporter
 import io.opentelemetry.exporter.otlp.http.metrics.OtlpHttpMetricExporter
 import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter
+import io.opentelemetry.sdk.common.CompletableResultCode
+import io.opentelemetry.sdk.logs.data.LogRecordData
 import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor
+import io.opentelemetry.sdk.logs.export.LogRecordExporter
 import io.opentelemetry.sdk.metrics.export.MetricExporter
 import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader
 import io.opentelemetry.sdk.resources.Resource
@@ -45,63 +52,55 @@ class InstrumentationManager(
     private var otelMeter: Meter
     private var otelLogger: Logger
     private var otelTracer: Tracer
+    private var customSampler = CustomSampler()
 
     init {
         val otelRumConfig = OtelRumConfig().setSessionConfig(
             SessionConfig(backgroundInactivityTimeout = options.sessionBackgroundTimeout)
         )
+
         otelRUM = OpenTelemetryRum.builder(application, otelRumConfig)
             .addLoggerProviderCustomizer { sdkLoggerProviderBuilder, application ->
                 val logExporter = OtlpHttpLogRecordExporter.builder()
                     .setEndpoint(options.otlpEndpoint + LOGS_PATH)
                     .setHeaders { options.customHeaders }
                     .build()
 
-                val processor = BatchLogRecordProcessor.builder(logExporter)
-                    .setMaxQueueSize(100)
-                    .setScheduleDelay(1000, TimeUnit.MILLISECONDS)
-                    .setExporterTimeout(5000, TimeUnit.MILLISECONDS)
-                    .setMaxExportBatchSize(10)
-                    .build()
-
-                sdkLoggerProviderBuilder
-                    .setResource(resources)
-                    .addLogRecordProcessor(processor)
+                sdkLoggerProviderBuilder.setResource(resources)
 
                 if (options.debug) {
-                    val adapterLogExporter = object : io.opentelemetry.sdk.logs.export.LogRecordExporter {
-                        override fun export(logRecords: Collection<io.opentelemetry.sdk.logs.data.LogRecordData>): io.opentelemetry.sdk.common.CompletableResultCode {
+                    val debugLogExporter = object : LogRecordExporter {
+                        override fun export(logRecords: Collection<LogRecordData>): CompletableResultCode {
                             for (record in logRecords) {
                                 logger.info(record.toString()) // TODO: Figure out why logger.debug is being blocked by Log.isLoggable is adapter.
                             }
-                            return io.opentelemetry.sdk.common.CompletableResultCode.ofSuccess()
-                        }
-                        override fun flush(): io.opentelemetry.sdk.common.CompletableResultCode {
-                            return io.opentelemetry.sdk.common.CompletableResultCode.ofSuccess()
-                        }
-                        override fun shutdown(): io.opentelemetry.sdk.common.CompletableResultCode {
-                            return io.opentelemetry.sdk.common.CompletableResultCode.ofSuccess()
+                            return CompletableResultCode.ofSuccess()
                         }
+                        override fun flush(): CompletableResultCode = CompletableResultCode.ofSuccess()
+                        override fun shutdown(): CompletableResultCode = CompletableResultCode.ofSuccess()
                     }
 
-                    val adapterProcessor = BatchLogRecordProcessor.builder(adapterLogExporter)
-                        .setMaxQueueSize(100)
-                        .setScheduleDelay(1000, TimeUnit.MILLISECONDS)
-                        .setExporterTimeout(5000, TimeUnit.MILLISECONDS)
-                        .setMaxExportBatchSize(10)
-                        .build()
-                    sdkLoggerProviderBuilder.addLogRecordProcessor(adapterProcessor)
-                }
+                    val compositeExporter = CompositeLogExporter(logExporter, debugLogExporter)
+                    val samplingLogExporter = SamplingLogExporter(compositeExporter, customSampler)
+                    val logProcessor = getBatchLogRecordProcessor(samplingLogExporter)
+
+                    sdkLoggerProviderBuilder.addLogRecordProcessor(logProcessor)
+                } else {
+                    val samplingLogExporter = SamplingLogExporter(logExporter, customSampler)
+                    val logProcessor = getBatchLogRecordProcessor(samplingLogExporter)
 
-                sdkLoggerProviderBuilder
+                    sdkLoggerProviderBuilder.addLogRecordProcessor(logProcessor)
+                }
             }
             .addTracerProviderCustomizer { sdkTracerProviderBuilder, application ->
                 val spanExporter = OtlpHttpSpanExporter.builder()
                     .setEndpoint(options.otlpEndpoint + TRACES_PATH)
                     .setHeaders { options.customHeaders }
                     .build()
 
-                val spanProcessor = BatchSpanProcessor.builder(spanExporter)
+                val samplingTraceExporter = SamplingTraceExporter(spanExporter, customSampler)
+
+                val spanProcessor = BatchSpanProcessor.builder(samplingTraceExporter)
                     .setMaxQueueSize(100)
                     .setScheduleDelay(1000, TimeUnit.MILLISECONDS)
                     .setExporterTimeout(5000, TimeUnit.MILLISECONDS)
@@ -135,6 +134,14 @@ class InstrumentationManager(
         otelTracer = otelRUM.openTelemetry.tracerProvider.get(INSTRUMENTATION_SCOPE_NAME)
     }
 
+    private fun getBatchLogRecordProcessor(logRecordExporter: LogRecordExporter): BatchLogRecordProcessor {
+        return BatchLogRecordProcessor.builder(logRecordExporter)
+            .setMaxQueueSize(100)
+            .setScheduleDelay(1000, TimeUnit.MILLISECONDS)
+            .setExporterTimeout(5000, TimeUnit.MILLISECONDS)
+            .setMaxExportBatchSize(10)
+            .build()
+    }
 
     fun recordMetric(metric: Metric) {
         otelMeter.gaugeBuilder(metric.name).build()

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/sampling/CompositeLogExporter.kt

@@ -0,0 +1,65 @@
+package com.launchdarkly.observability.sampling
+
+import io.opentelemetry.sdk.common.CompletableResultCode
+import io.opentelemetry.sdk.logs.data.LogRecordData
+import io.opentelemetry.sdk.logs.export.LogRecordExporter
+
+/**
+ * A composite log exporter that forwards log records to multiple underlying exporters.
+ * 
+ * This allows sending the same log records to multiple destinations (e.g., OTLP endpoint 
+ * and local debug output) without duplicating the sampling logic. All operations 
+ * (export, flush, shutdown) are forwarded to all underlying exporters.
+ * 
+ * The composite operation succeeds only if ALL underlying exporters succeed.
+ * 
+ * @param exporters The list of underlying exporters to forward operations to
+ */
+class CompositeLogExporter(
+    private val exporters: List<LogRecordExporter>
+) : LogRecordExporter {
+    
+    /**
+     * Convenience constructor that accepts a variable number of exporters.
+     * 
+     * @param exporters The exporters to compose
+     */
+    constructor(vararg exporters: LogRecordExporter) : this(exporters.toList())
+    
+    /**
+     * Exports log records to all underlying exporters.
+     * 
+     * @param logRecords The log records to export
+     * @return A CompletableResultCode that succeeds only if all underlying exports succeed
+     */
+    override fun export(logRecords: Collection<LogRecordData>): CompletableResultCode {
+        val results = exporters.map { exporter ->
+            exporter.export(logRecords)
+        }
+        return CompletableResultCode.ofAll(results)
+    }
+    
+    /**
+     * Flushes all underlying exporters.
+     * 
+     * @return A CompletableResultCode that succeeds only if all underlying flushes succeed
+     */
+    override fun flush(): CompletableResultCode {
+        val results = exporters.map { exporter ->
+            exporter.flush()
+        }
+        return CompletableResultCode.ofAll(results)
+    }
+    
+    /**
+     * Shuts down all underlying exporters.
+     * 
+     * @return A CompletableResultCode that succeeds only if all underlying shutdowns succeed
+     */
+    override fun shutdown(): CompletableResultCode {
+        val results = exporters.map { exporter ->
+            exporter.shutdown()
+        }
+        return CompletableResultCode.ofAll(results)
+    }
+}