@barrysolomon/mobile-react-native 0.1.0-alpha → 0.2.0-alpha

package/android/src/test/java/com/dash0/mobile/reactnative/OTelNetworkInterceptorTest.kt

@@ -0,0 +1,381 @@
+/*
+ * Unit tests for OTelNetworkInterceptor — the OkHttp interceptor that wraps the
+ * host app's ENTIRE OkHttp pipeline (classic fetch, XMLHttpRequest, axios, AND
+ * expo/fetch all bottom out on RN's shared OkHttp client).
+ *
+ * Because a throw from this interceptor would break ALL host networking, the
+ * highest-value assertions here are the fault-isolation ones: a telemetry
+ * failure must NEVER stop `chain.proceed` nor alter the response/exception the
+ * host sees.
+ *
+ * Everything is exercised on a pure JVM: real OkHttp request/response objects, a
+ * real OpenTelemetry SDK tracer wired to an InMemorySpanExporter so we can read
+ * back the exact span the interceptor produced and the traceparent it injected,
+ * and hand-rolled Interceptor.Chain test doubles. No React types, no Android
+ * runtime, no emulator — the interceptor depends only on okhttp3 + otel-api.
+ */
+package com.dash0.mobile.reactnative
+
+import io.opentelemetry.api.trace.Tracer
+import io.opentelemetry.sdk.OpenTelemetrySdk
+import io.opentelemetry.sdk.trace.SdkTracerProvider
+import io.opentelemetry.sdk.trace.`data`.SpanData
+import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor
+import io.opentelemetry.sdk.trace.samplers.Sampler
+import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter
+import okhttp3.Interceptor
+import okhttp3.Protocol
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+import okhttp3.ResponseBody.Companion.toResponseBody
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Before
+import org.junit.Test
+
+class OTelNetworkInterceptorTest {
+
+    private lateinit var spanExporter: InMemorySpanExporter
+    private lateinit var sdk: OpenTelemetrySdk
+    private lateinit var tracer: Tracer
+    private lateinit var interceptor: OTelNetworkInterceptor
+
+    @Before
+    fun setUp() {
+        spanExporter = InMemorySpanExporter.create()
+        sdk = OpenTelemetrySdk.builder()
+            .setTracerProvider(
+                SdkTracerProvider.builder()
+                    .addSpanProcessor(SimpleSpanProcessor.create(spanExporter))
+                    .setSampler(Sampler.alwaysOn())
+                    .build(),
+            )
+            .build()
+        tracer = sdk.getTracer("test")
+        interceptor = OTelNetworkInterceptor()
+    }
+
+    @After
+    fun tearDown() {
+        sdk.close()
+    }
+
+    // ── unarmed → pure pass-through ──────────────────────────────────────────
+
+    @Test
+    fun unarmed_passesThrough_unmodifiedRequest_noSpan() {
+        // No arm() call → interceptor must be a transparent no-op.
+        val chain = FakeChain(get("https://api.example.com/widgets"))
+
+        val response = interceptor.intercept(chain)
+
+        // chain.proceed was called exactly once with the ORIGINAL request.
+        assertEquals(1, chain.proceedCount)
+        assertSame(chain.request, chain.proceededRequest)
+        // No traceparent was injected.
+        assertNull(chain.proceededRequest!!.header("traceparent"))
+        // The exact response object flows back untouched.
+        assertSame(chain.cannedResponse, response)
+        // No telemetry produced.
+        assertTrue(spanExporter.finishedSpanItems.isEmpty())
+    }
+
+    // ── armed → CLIENT span + W3C traceparent ────────────────────────────────
+
+    @Test
+    fun armed_recordsClientSpan_andInjectsWellFormedTraceparent() {
+        interceptor.arm(tracer, collectorEndpoint = "https://ingress.dash0.com/v1/traces")
+        val chain = FakeChain(get("https://api.example.com/orders?id=7"), responseCode = 200)
+
+        val response = interceptor.intercept(chain)
+
+        // Host request proceeded exactly once and the response is unchanged.
+        assertEquals(1, chain.proceedCount)
+        assertSame(chain.cannedResponse, response)
+
+        // Exactly one CLIENT span, named by method, with the expected attributes.
+        val spans = spanExporter.finishedSpanItems
+        assertEquals(1, spans.size)
+        val span: SpanData = spans[0]
+        assertEquals("GET", span.name)
+        assertEquals(io.opentelemetry.api.trace.SpanKind.CLIENT, span.kind)
+        assertEquals("GET", span.attributes.get(io.opentelemetry.api.common.AttributeKey.stringKey("http.request.method")))
+        assertEquals("https://api.example.com/orders?id=7", span.attributes.get(io.opentelemetry.api.common.AttributeKey.stringKey("url.full")))
+        assertEquals("api.example.com", span.attributes.get(io.opentelemetry.api.common.AttributeKey.stringKey("server.address")))
+        assertEquals("https", span.attributes.get(io.opentelemetry.api.common.AttributeKey.stringKey("url.scheme")))
+        assertEquals(200L, span.attributes.get(io.opentelemetry.api.common.AttributeKey.longKey("http.response.status_code")))
+        assertNotNull(span.attributes.get(io.opentelemetry.api.common.AttributeKey.longKey("http.client.request.duration_ms")))
+        assertEquals(io.opentelemetry.api.trace.StatusCode.OK, span.status.statusCode)
+
+        // The traceparent the host request carried must be a well-formed W3C
+        // header derived from THIS span's context.
+        val traceparent = chain.proceededRequest!!.header("traceparent")
+        assertNotNull(traceparent)
+        assertTrue(
+            "traceparent not W3C-shaped: $traceparent",
+            Regex("^00-[0-9a-f]{32}-[0-9a-f]{16}-0[01]$").matches(traceparent!!),
+        )
+        // ...and it carries the span's REAL trace + span ids (distributed-trace stitch).
+        assertEquals("00-${span.traceId}-${span.spanId}-01", traceparent)
+    }
+
+    // ── invalid/not-sampled context → traceparent OMITTED (not malformed) ─────
+
+    @Test
+    fun invalidSpanContext_omitsTraceparent_doesNotInjectMalformedHeader() {
+        // A tracer whose spans always carry an INVALID span context (mirrors the
+        // SDK handing back a no-op span when sampling is off). The interceptor
+        // must inject NO traceparent rather than a malformed "00-000…-000…".
+        interceptor.arm(InvalidContextTracer(), collectorEndpoint = null)
+        val chain = FakeChain(get("https://api.example.com/x"))
+
+        val response = interceptor.intercept(chain)
+
+        assertEquals(1, chain.proceedCount)
+        assertSame(chain.cannedResponse, response)
+        assertNull("must omit traceparent for invalid context", chain.proceededRequest!!.header("traceparent"))
+    }
+
+    // ── collector host in ignore list → NOT instrumented ─────────────────────
+
+    @Test
+    fun collectorHost_isNotInstrumented_noSpanNoHeader() {
+        // Arm with a collector endpoint; a request to that same host is our own
+        // telemetry export and must NOT be instrumented (no recursion).
+        interceptor.arm(tracer, collectorEndpoint = "https://ingress.dash0.com/v1/traces")
+        val chain = FakeChain(get("https://ingress.dash0.com/v1/traces"))
+
+        val response = interceptor.intercept(chain)
+
+        assertEquals(1, chain.proceedCount)
+        assertSame(chain.request, chain.proceededRequest) // untouched request
+        assertNull(chain.proceededRequest!!.header("traceparent"))
+        assertSame(chain.cannedResponse, response)
+        assertTrue(spanExporter.finishedSpanItems.isEmpty())
+    }
+
+    @Test
+    fun collectorHost_matchIsCaseInsensitive() {
+        interceptor.arm(tracer, collectorEndpoint = "https://Ingress.Dash0.com/v1/traces")
+        val chain = FakeChain(get("https://INGRESS.DASH0.COM/v1/traces"))
+
+        interceptor.intercept(chain)
+
+        assertTrue(spanExporter.finishedSpanItems.isEmpty())
+        assertNull(chain.proceededRequest!!.header("traceparent"))
+    }
+
+    @Test
+    fun nonCollectorHost_isInstrumented_evenWhenIgnoreListPresent() {
+        interceptor.arm(tracer, collectorEndpoint = "https://ingress.dash0.com/v1/traces")
+        val chain = FakeChain(get("https://api.example.com/y"))
+
+        interceptor.intercept(chain)
+
+        assertEquals(1, spanExporter.finishedSpanItems.size)
+        assertNotNull(chain.proceededRequest!!.header("traceparent"))
+    }
+
+    // ── FAULT ISOLATION (the critical contract) ──────────────────────────────
+
+    @Test
+    fun throwingTracer_duringSetup_stillProceedsWithOriginalRequest_andReturnsResponse() {
+        // The tracer throws as soon as the interceptor tries to start a span.
+        // The host request must still proceed (with the UNMODIFIED request) and
+        // the original response must come back verbatim. Telemetry failure must
+        // never become a host-networking failure.
+        interceptor.arm(ThrowingTracer(), collectorEndpoint = null)
+        val chain = FakeChain(get("https://api.example.com/z"))
+
+        val response = interceptor.intercept(chain)
+
+        assertEquals(1, chain.proceedCount)
+        assertSame("must proceed with the original, unmodified request", chain.request, chain.proceededRequest)
+        assertNull(chain.proceededRequest!!.header("traceparent"))
+        assertSame(chain.cannedResponse, response)
+        assertTrue(spanExporter.finishedSpanItems.isEmpty())
+    }
+
+    @Test
+    fun throwingTracer_doesNotPropagateTelemetryExceptionToHost() {
+        // Belt-and-suspenders: the telemetry exception must be swallowed, not
+        // surfaced to the host caller.
+        interceptor.arm(ThrowingTracer(), collectorEndpoint = null)
+        val chain = FakeChain(get("https://api.example.com/z"))
+        try {
+            interceptor.intercept(chain)
+        } catch (t: Throwable) {
+            fail("telemetry exception leaked to host: $t")
+        }
+    }
+
+    // ── network failure → span ERROR, original throwable rethrown verbatim ────
+
+    @Test
+    fun networkException_endsSpanWithError_andRethrowsOriginalThrowableUnchanged() {
+        interceptor.arm(tracer, collectorEndpoint = null)
+        val boom = java.net.UnknownHostException("api.example.com: nodename nor servname provided")
+        val chain = FakeChain(get("https://api.example.com/down"), throwOnProceed = boom)
+
+        val thrown = try {
+            interceptor.intercept(chain)
+            null
+        } catch (t: Throwable) {
+            t
+        }
+
+        // The EXACT original throwable instance is rethrown (not wrapped).
+        assertSame(boom, thrown)
+
+        // The span was still recorded, ended, and marked ERROR.
+        val spans = spanExporter.finishedSpanItems
+        assertEquals(1, spans.size)
+        assertEquals(io.opentelemetry.api.trace.StatusCode.ERROR, spans[0].status.statusCode)
+        // No status_code attribute since the request never produced a response.
+        assertNull(spans[0].attributes.get(io.opentelemetry.api.common.AttributeKey.longKey("http.response.status_code")))
+    }
+
+    // ── status-code mapping ──────────────────────────────────────────────────
+
+    @Test
+    fun http2xx_mapsToOkStatus() {
+        interceptor.arm(tracer, collectorEndpoint = null)
+        interceptor.intercept(FakeChain(get("https://api.example.com/ok"), responseCode = 204))
+        assertEquals(io.opentelemetry.api.trace.StatusCode.OK, spanExporter.finishedSpanItems[0].status.statusCode)
+    }
+
+    @Test
+    fun http4xx_mapsToErrorStatus() {
+        interceptor.arm(tracer, collectorEndpoint = null)
+        interceptor.intercept(FakeChain(get("https://api.example.com/missing"), responseCode = 404))
+        val span = spanExporter.finishedSpanItems[0]
+        assertEquals(io.opentelemetry.api.trace.StatusCode.ERROR, span.status.statusCode)
+        assertEquals(404L, span.attributes.get(io.opentelemetry.api.common.AttributeKey.longKey("http.response.status_code")))
+    }
+
+    @Test
+    fun http5xx_mapsToErrorStatus() {
+        interceptor.arm(tracer, collectorEndpoint = null)
+        interceptor.intercept(FakeChain(get("https://api.example.com/boom"), responseCode = 503))
+        assertEquals(io.opentelemetry.api.trace.StatusCode.ERROR, spanExporter.finishedSpanItems[0].status.statusCode)
+    }
+
+    // ── method handling ──────────────────────────────────────────────────────
+
+    @Test
+    fun postRequest_spanNamedByUppercasedMethod_andRecordsMethodAttribute() {
+        interceptor.arm(tracer, collectorEndpoint = null)
+        val req = Request.Builder()
+            .url("https://api.example.com/orders")
+            .post("{}".toRequestBody())
+            .build()
+        interceptor.intercept(FakeChain(req, responseCode = 201))
+        val span = spanExporter.finishedSpanItems[0]
+        assertEquals("POST", span.name)
+        assertEquals("POST", span.attributes.get(io.opentelemetry.api.common.AttributeKey.stringKey("http.request.method")))
+    }
+
+    // ── disarm → back to pass-through ────────────────────────────────────────
+
+    @Test
+    fun disarm_returnsToPassThrough() {
+        interceptor.arm(tracer, collectorEndpoint = null)
+        interceptor.intercept(FakeChain(get("https://api.example.com/1")))
+        assertEquals(1, spanExporter.finishedSpanItems.size)
+
+        interceptor.disarm()
+        val chain = FakeChain(get("https://api.example.com/2"))
+        interceptor.intercept(chain)
+
+        // Still just the one span from before the disarm.
+        assertEquals(1, spanExporter.finishedSpanItems.size)
+        assertNull(chain.proceededRequest!!.header("traceparent"))
+    }
+
+    // ── helpers ──────────────────────────────────────────────────────────────
+
+    private fun get(url: String): Request = Request.Builder().url(url).build()
+}
+
+/**
+ * Minimal okhttp3 Interceptor.Chain test double. Captures whatever request the
+ * interceptor proceeds with, counts proceed calls, and either returns a canned
+ * response or throws a supplied exception (network-failure simulation).
+ */
+private class FakeChain(
+    val request: Request,
+    responseCode: Int = 200,
+    private val throwOnProceed: Throwable? = null,
+) : Interceptor.Chain {
+
+    var proceedCount = 0
+    var proceededRequest: Request? = null
+
+    val cannedResponse: Response = Response.Builder()
+        .request(request)
+        .protocol(Protocol.HTTP_1_1)
+        .code(responseCode)
+        .message("status $responseCode")
+        .body("".toResponseBody())
+        .build()
+
+    override fun request(): Request = request
+
+    override fun proceed(request: Request): Response {
+        proceedCount++
+        proceededRequest = request
+        throwOnProceed?.let { throw it }
+        // Return the SAME response instance so identity-based assertions can
+        // prove the interceptor hands the host's response back verbatim.
+        return cannedResponse
+    }
+
+    override fun connection() = null
+    override fun call(): okhttp3.Call = throw UnsupportedOperationException()
+    override fun connectTimeoutMillis(): Int = 0
+    override fun withConnectTimeout(timeout: Int, unit: java.util.concurrent.TimeUnit): Interceptor.Chain = this
+    override fun readTimeoutMillis(): Int = 0
+    override fun withReadTimeout(timeout: Int, unit: java.util.concurrent.TimeUnit): Interceptor.Chain = this
+    override fun writeTimeoutMillis(): Int = 0
+    override fun withWriteTimeout(timeout: Int, unit: java.util.concurrent.TimeUnit): Interceptor.Chain = this
+}
+
+/** A Tracer whose span builder throws the moment startSpan() is called. */
+private class ThrowingTracer : Tracer {
+    override fun spanBuilder(spanName: String): io.opentelemetry.api.trace.SpanBuilder =
+        throw RuntimeException("boom: tracer is broken")
+}
+
+/**
+ * A Tracer that produces spans whose context is always INVALID — the SDK's
+ * behavior when a span is dropped (e.g. sampling off) and it hands back a
+ * no-op/invalid context. Used to prove the interceptor omits the traceparent
+ * rather than emitting a malformed all-zeros header.
+ */
+private class InvalidContextTracer : Tracer {
+    override fun spanBuilder(spanName: String): io.opentelemetry.api.trace.SpanBuilder =
+        InvalidContextSpanBuilder()
+}
+
+private class InvalidContextSpanBuilder : io.opentelemetry.api.trace.SpanBuilder {
+    override fun setParent(context: io.opentelemetry.context.Context) = this
+    override fun setNoParent() = this
+    override fun addLink(spanContext: io.opentelemetry.api.trace.SpanContext) = this
+    override fun addLink(spanContext: io.opentelemetry.api.trace.SpanContext, attributes: io.opentelemetry.api.common.Attributes) = this
+    override fun setAttribute(key: String, value: String) = this
+    override fun setAttribute(key: String, value: Long) = this
+    override fun setAttribute(key: String, value: Double) = this
+    override fun setAttribute(key: String, value: Boolean) = this
+    override fun <T : Any?> setAttribute(key: io.opentelemetry.api.common.AttributeKey<T>, value: T) = this
+    override fun setSpanKind(spanKind: io.opentelemetry.api.trace.SpanKind) = this
+    override fun setStartTimestamp(startTimestamp: Long, unit: java.util.concurrent.TimeUnit) = this
+    // Span.getInvalid() carries an invalid SpanContext and is a no-op.
+    override fun startSpan(): io.opentelemetry.api.trace.Span = io.opentelemetry.api.trace.Span.getInvalid()
+}

package/ios/BoundedLiveSpanStore.swift

@@ -0,0 +1,138 @@
+// Bounded, insertion-ordered store of live spans keyed by spanId.
+//
+// The RN bridge holds a span object between `startSpan` and `endSpan` so it can
+// apply end-time attributes and status. A misbehaving JS layer that starts spans
+// but never ends them (navigation churn, leaked timers) would otherwise grow
+// this map without bound. We cap it and evict the oldest entry when full.
+//
+// Design goals (all O(1)):
+//   - lookup / remove by spanId           → dictionary
+//   - evict the OLDEST inserted entry      → intrusive doubly-linked list
+//
+// A naive bounded list does an O(n) `firstIndex(where:)` scan to evict; this
+// structure keeps a `head`/`tail` of a doubly-linked list of nodes plus a
+// `[Key: Node]` index, so both lookup-by-id AND oldest-eviction are O(1).
+//
+// This type is deliberately generic and has **no** dependency on OTelMobileSDK
+// or React, so it lives in the base RN package target and is unit-testable with
+// plain `swift test`. `OTelMobileCallSink` specializes it to `Span`.
+//
+// NOT thread-safe on its own — the caller (`OTelMobileCallSink`) serializes all
+// access under its existing `spanLock`, matching the prior `liveSpans` usage.
+final class BoundedLiveSpanStore<Key: Hashable, Value> {
+
+    private final class Node {
+        let key: Key
+        var value: Value
+        var prev: Node?
+        var next: Node?
+        init(key: Key, value: Value) {
+            self.key = key
+            self.value = value
+        }
+    }
+
+    /// Max live entries before the oldest is evicted on insert. Exposed
+    /// (read-only) so the owning sink can name the limit in its eviction
+    /// diagnostics without hard-coding a second copy of the number.
+    let capacity: Int
+    private var index: [Key: Node] = [:]
+    // head = oldest (evict from here), tail = newest (insert here). FIFO order.
+    private var head: Node?
+    private var tail: Node?
+
+    /// Count of entries evicted because the store hit `capacity`. Exposed for
+    /// tests and a future health gauge.
+    private(set) var evictedCount: Int = 0
+
+    init(capacity: Int) {
+        precondition(capacity > 0, "capacity must be positive")
+        self.capacity = capacity
+        index.reserveCapacity(capacity)
+    }
+
+    var count: Int { index.count }
+
+    /// Insert or replace the value for `key`. Returns the value that was
+    /// evicted to make room (the oldest entry), or `nil` if nothing was evicted.
+    /// O(1). Re-inserting an existing key updates its value in place and does
+    /// NOT change its insertion position (it is not "refreshed" to newest) —
+    /// startSpan for a duplicate id is a degenerate case we simply overwrite.
+    @discardableResult
+    func put(_ key: Key, _ value: Value) -> Value? {
+        if let existing = index[key] {
+            existing.value = value
+            return nil
+        }
+
+        var evicted: Value?
+        // Evict oldest if at capacity. `>=` because we are about to add one.
+        if index.count >= capacity, let oldest = head {
+            evicted = oldest.value
+            removeNode(oldest)
+            index[oldest.key] = nil
+            evictedCount += 1
+        }
+
+        let node = Node(key: key, value: value)
+        appendNode(node)
+        index[key] = node
+        return evicted
+    }
+
+    /// Look up the value for `key` without changing its insertion position
+    /// or removing it. Returns `nil` if absent. O(1). Used for parent-span
+    /// resolution in startSpan — a read-only peek, so the LRU order is left
+    /// untouched (the entry is still removed normally by its own endSpan).
+    func value(forKey key: Key) -> Value? {
+        return index[key]?.value
+    }
+
+    /// Remove and return the value for `key`, or `nil` if absent. O(1).
+    @discardableResult
+    func removeValue(forKey key: Key) -> Value? {
+        guard let node = index[key] else { return nil }
+        removeNode(node)
+        index[key] = nil
+        return node.value
+    }
+
+    /// Remove all entries. Returns the values in insertion (oldest→newest) order
+    /// so the caller can end/clean them up if needed. O(n).
+    @discardableResult
+    func removeAll() -> [Value] {
+        var values: [Value] = []
+        values.reserveCapacity(index.count)
+        var cur = head
+        while let node = cur {
+            values.append(node.value)
+            cur = node.next
+        }
+        index.removeAll(keepingCapacity: true)
+        head = nil
+        tail = nil
+        return values
+    }
+
+    // MARK: - Intrusive list ops (all O(1))
+
+    private func appendNode(_ node: Node) {
+        node.prev = tail
+        node.next = nil
+        if let t = tail {
+            t.next = node
+        } else {
+            head = node
+        }
+        tail = node
+    }
+
+    private func removeNode(_ node: Node) {
+        let p = node.prev
+        let n = node.next
+        if let p = p { p.next = n } else { head = n }
+        if let n = n { n.prev = p } else { tail = p }
+        node.prev = nil
+        node.next = nil
+    }
+}

package/ios/BridgeCallSink.swift

@@ -44,6 +44,40 @@ extension BridgeCallSink {
     }
 }
 
+/// Bridge-side mirror of the JS `SamplingConfig`. Decoded from the RN
+/// `start()` payload and translated to the native SDK's `SamplingConfig`
+/// in `OTelMobileCallSink.start`. Kept SDK-independent so the dispatcher
+/// and its tests compile without linking `OTelMobileSDK`.
+public struct BridgeSamplingConfig: Equatable {
+    public enum Strategy: String, Equatable {
+        case alwaysOn = "always_on"
+        case alwaysOff = "always_off"
+        case dynamic
+
+        /// Maps the JS `strategy` string; unknown values fall back to
+        /// `.alwaysOn` (the RN default — see `BridgeStartConfig.sampling`).
+        public static func fromToken(_ raw: String?) -> Strategy {
+            switch raw {
+            case "always_off": return .alwaysOff
+            case "dynamic": return .dynamic
+            default: return .alwaysOn
+            }
+        }
+    }
+
+    public let strategy: Strategy
+    /// Baseline rate for `.dynamic`. Nil = native default.
+    public let normalRate: Double?
+    /// High-priority rate for `.dynamic`. Nil = native default.
+    public let highPriorityRate: Double?
+
+    public init(strategy: Strategy, normalRate: Double? = nil, highPriorityRate: Double? = nil) {
+        self.strategy = strategy
+        self.normalRate = normalRate
+        self.highPriorityRate = highPriorityRate
+    }
+}
+
 public struct BridgeStartConfig: Equatable {
     public let serviceName: String
     public let serviceVersion: String?
@@ -63,6 +97,18 @@ public struct BridgeStartConfig: Equatable {
     /// "screen", "deviceStats". Unknown tokens are ignored (forward compat).
     public let nativeAutoCapture: [String]
 
+    /// Trace sampling strategy from the JS caller, mapped onto the native
+    /// `SamplingConfig` in `OTelMobileCallSink.start`.
+    ///
+    /// The RN bridge defaults this to `.alwaysOn` when the JS caller omits
+    /// `sampling`, rather than inheriting the native SDK's `dynamic(0.1)`
+    /// default. RN manual spans are root spans with arbitrary names, so a
+    /// 10% baseline silently drops ~90% of a user's first span (Loper
+    /// finding #4). Nil means the caller sent nothing — the sink falls back
+    /// to `.alwaysOn` to preserve the RN default; in practice the JS bridge
+    /// always sends a value.
+    public let sampling: BridgeSamplingConfig?
+
     public init(
         serviceName: String,
         serviceVersion: String?,
@@ -70,7 +116,8 @@ public struct BridgeStartConfig: Equatable {
         authToken: String?,
         dataset: String?,
         extraResourceAttributes: [String: String] = [:],
-        nativeAutoCapture: [String] = []
+        nativeAutoCapture: [String] = [],
+        sampling: BridgeSamplingConfig? = nil
     ) {
         self.serviceName = serviceName
         self.serviceVersion = serviceVersion
@@ -79,5 +126,6 @@ public struct BridgeStartConfig: Equatable {
         self.dataset = dataset
         self.extraResourceAttributes = extraResourceAttributes
         self.nativeAutoCapture = nativeAutoCapture
+        self.sampling = sampling
     }
 }

package/ios/Dash0MobileBridgeDispatcher.swift

@@ -29,6 +29,7 @@ public final class Dash0MobileBridgeDispatcher {
         let extras: [String: String] = (config["extraResourceAttributes"] as? [String: Any])?
             .compactMapValues { $0 as? String } ?? [:]
         let nativeAutoCapture = (config["nativeAutoCapture"] as? [Any])?.compactMap { $0 as? String } ?? []
+        let sampling = Self.parseSampling(config["sampling"])
         sink.start(BridgeStartConfig(
             serviceName: serviceName,
             serviceVersion: config["serviceVersion"] as? String,
@@ -36,10 +37,31 @@ public final class Dash0MobileBridgeDispatcher {
             authToken: config["authToken"] as? String,
             dataset: config["dataset"] as? String,
             extraResourceAttributes: extras,
-            nativeAutoCapture: nativeAutoCapture
+            nativeAutoCapture: nativeAutoCapture,
+            sampling: sampling
         ))
     }
 
+    /// Decode the JS `sampling` object into a `BridgeSamplingConfig`.
+    /// Returns nil when absent so the sink applies the RN default
+    /// (`.alwaysOn`). `normalRate` / `highPriorityRate` may arrive as
+    /// Int, Double, or NSNumber across the RN bridge.
+    private static func parseSampling(_ raw: Any?) -> BridgeSamplingConfig? {
+        guard let map = raw as? [String: Any] else { return nil }
+        return BridgeSamplingConfig(
+            strategy: .fromToken(map["strategy"] as? String),
+            normalRate: doubleOrNil(map["normalRate"]),
+            highPriorityRate: doubleOrNil(map["highPriorityRate"])
+        )
+    }
+
+    private static func doubleOrNil(_ v: Any?) -> Double? {
+        if let n = v as? Double { return n }
+        if let n = v as? Int { return Double(n) }
+        if let n = v as? NSNumber { return n.doubleValue }
+        return nil
+    }
+
     public func emitBatch(_ payloads: [[String: Any]]) {
         for p in payloads {
             dispatch(p)