@coralogix/react-native-plugin 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 0.5.0 (2026-05-17)
+
+### 🚀 Features
+
+- bridge startTimeMeasure / endTimeMeasure to native (CX-40525)
+- expose excludeFromSampling on JS config + native bridges
+
+## Unreleased
+
+### 🚀 Features
+
+- Bridge `CoralogixRum.startTimeMeasure(name, labels?)` / `CoralogixRum.endTimeMeasure(name)` to the native iOS and Android SDKs as a fire-and-forget pass-through ([CX-40525](https://coralogix.atlassian.net/browse/CX-40525)). The JS side keeps no state — native owns the in-flight registry.
+
+## 0.4.0 (2026-05-03)
+
+### 🚀 Features
+
+- Custom Spans & Traces Exporter (CX-36055)
+
+### 🩹 Fixes
+
+- import CoralogixIgnoredInstrument in index.ts for rollup build
+
 ## 0.3.3 (2026-04-05)
 
 ### 🩹 Fixes

package/CxSdk.podspec

@@ -16,9 +16,9 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
-  s.dependency 'Coralogix','2.4.1'
-  s.dependency 'CoralogixInternal','2.4.1'
-  s.dependency 'SessionReplay','2.4.1'
+  s.dependency 'Coralogix','2.6.4'
+  s.dependency 'CoralogixInternal','2.6.4'
+  s.dependency 'SessionReplay','2.6.4'
 
   # Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.
   # See https://github.com/facebook/react-native/blob/febf6b7f33fdb4904669f99d795eba4c0f95d7bf/scripts/cocoapods/new_architecture.rb#L79.

package/README.md

@@ -156,6 +156,25 @@ await CoralogixRum.init({
 });
 ```
 
+### Exclude From Sampling
+
+By default, when a session is sampled out (via `sessionSampleRate`), nothing is
+emitted for that session. Use `excludeFromSampling` to keep emitting specific
+event categories even when the session is sampled out.
+
+```javascript
+import { CoralogixRum } from '@coralogix/react-native-plugin';
+
+await CoralogixRum.init({
+  // ...
+  sessionSampleRate: 10,
+  excludeFromSampling: ['errors', 'logs'], // always emitted, even for sampled-out sessions
+});
+```
+
+Allowed values: `'errors'`, `'logs'`, `'network'`, `'userInteractions'`,
+`'mobileVitals'`, `'customSpan'`, `'customMeasurement'`.
+
 ### Ignore Errors
 
 The ignoreErrors option allows you to exclude errors that meet specific criteria.
@@ -184,6 +203,126 @@ await CoralogixRum.init({
 });
 ```
 
+### Custom Spans
+
+Create manual RUM spans to instrument custom flows in your application. Requires `traceParentInHeader.enabled: true`.
+
+**Prerequisite:**
+```javascript
+await CoralogixRum.init({
+  // ...
+  traceParentInHeader: { enabled: true },
+});
+```
+
+**Basic usage — global span with a child:**
+```javascript
+import { CoralogixRum } from '@coralogix/react-native-plugin';
+
+const tracer = CoralogixRum.getCustomTracer();
+
+const globalSpan = await tracer.startGlobalSpan('checkout', { step: 'start' });
+if (!globalSpan) return; // another global span is already active
+
+const childSpan = await globalSpan.startCustomSpan('validate-cart');
+await childSpan?.endSpan();
+
+await globalSpan.endSpan();
+```
+
+**Linking network requests with `withContext`:**
+
+When you call `fetch` inside `withContext`, the network request is automatically linked to the active global span's trace.
+
+```javascript
+const globalSpan = await tracer.startGlobalSpan('checkout');
+
+await globalSpan.withContext(async () => {
+  await fetch('https://api.example.com/cart'); // linked to globalSpan's traceId
+});
+
+await globalSpan.endSpan();
+```
+
+**`ignoredInstruments` — exclude auto-instrumentation from the trace:**
+
+Pass instrument names to prevent network requests, errors, or interactions fired during this tracer's spans from being linked to your custom trace.
+
+```javascript
+const tracer = CoralogixRum.getCustomTracer(['networkRequests', 'userInteractions', 'errors']);
+```
+
+> **Note:** Only one global span may be active at a time. `startGlobalSpan` returns `null` if a global span is already open.
+
+### Time Measurement
+
+Measure the duration of arbitrary flows with a pair of `startTimeMeasure(name, labels?)` / `endTimeMeasure(name)` calls. The native SDK records start/end timestamps and reports the delta as a custom-measurement span (milliseconds).
+
+```javascript
+import { CoralogixRum } from '@coralogix/react-native-plugin';
+
+CoralogixRum.startTimeMeasure('checkout', { flow: 'checkout' });
+
+await validateCart();
+await charge();
+await confirm();
+
+CoralogixRum.endTimeMeasure('checkout');
+```
+
+**Behaviour:**
+
+- Both calls are fire-and-forget — they cross the bridge directly into native and return immediately.
+- The JS side keeps no state; the native SDK owns the in-flight registry.
+- **You are responsible for pairing every `startTimeMeasure(name, labels?)` with exactly one `endTimeMeasure(name)`.** Leaked starts persist in memory until `CoralogixRum.shutdown()`.
+- Unmatched `endTimeMeasure` calls are dropped silently by the native SDK.
+- Calling `startTimeMeasure` again with an open `name` overwrites the previous start.
+
+### Traces Exporter
+
+Receive OTLP-formatted trace batches from the native SDK in your JavaScript code. Use this to forward spans to an OTLP-compatible backend (e.g. Jaeger, custom collector) alongside Coralogix.
+
+```javascript
+await CoralogixRum.init({
+  // ...
+  tracesExporter: (data) => {
+    // data.resource_spans contains OTLP JSON-format span data
+    sendToMyOtlpBackend(JSON.stringify(data));
+  },
+});
+```
+
+The callback receives a `TraceExporterData` object following the OTLP JSON format:
+
+```typescript
+{
+  resource_spans: [
+    {
+      resource: { attributes: [{ key: string, value: { string_value: string } }] },
+      scope_spans: [
+        {
+          scope: { name: string, version?: string },
+          spans: [
+            {
+              trace_id: string,
+              span_id: string,
+              parent_span_id?: string,
+              name: string,
+              start_time_unix_nano: string,
+              end_time_unix_nano: string,
+              attributes: [{ key: string, value: {...} }],
+              status: { code: string },
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+> **Note:** The callback fires once per native export batch, which typically contains several spans rather than one per span.
+
 ### beforeSend
 
 Enable event access and modification before sending to Coralogix, supporting content modification, and event discarding.

package/android/build.gradle

@@ -61,6 +61,15 @@ android {
         "generated/jni"
       ]
     }
+    test {
+      java.srcDirs += ["src/test/kotlin"]
+    }
+  }
+
+  testOptions {
+    unitTests.all {
+      useJUnitPlatform()
+    }
   }
 }
 
@@ -75,7 +84,10 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 
-  implementation "com.coralogix:android-sdk:2.9.5"
+  implementation "com.coralogix:android-sdk:2.12.0"
+
+  testImplementation "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
+  testImplementation "org.mockito:mockito-core:5.12.0"
 }
 
 react {

package/android/src/main/java/com/cxsdk/CxSdkModule.kt

@@ -5,6 +5,11 @@ import android.os.Handler
 import android.os.Looper
 import android.util.Log
 import com.coralogix.android.sdk.CoralogixRum
+import com.coralogix.android.sdk.customspans.CoralogixCustomSpan
+import com.coralogix.android.sdk.customspans.CoralogixGlobalSpan
+import com.coralogix.android.sdk.customspans.CoralogixIgnoredInstrument
+import com.coralogix.android.sdk.model.ExcludableInstrumentation
+import com.coralogix.android.sdk.traceexporter.CoralogixTraceExporterData
 import com.coralogix.android.sdk.internal.features.instrumentations.error.CoralogixErrorDecorator
 import com.coralogix.android.sdk.internal.features.instrumentations.network.NetworkRequestDetails
 import com.coralogix.android.sdk.internal.infrastructure.threaddump.CoralogixJsStackFrame
@@ -39,10 +44,14 @@ import com.facebook.react.modules.core.DeviceEventManagerModule
 import org.json.JSONArray
 import org.json.JSONObject
 import com.facebook.react.uimanager.UIManagerModule
+import java.util.concurrent.ConcurrentHashMap
 
 class CxSdkModule(reactContext: ReactApplicationContext) :
   ReactContextBaseJavaModule(reactContext), RUMClient, SessionReplayClient {
 
+  private val globalSpans = ConcurrentHashMap<String, CoralogixGlobalSpan>()
+  private val customSpans = ConcurrentHashMap<String, CoralogixCustomSpan>()
+
   override fun getName(): String {
     return NAME
   }
@@ -134,6 +143,16 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
     CoralogixRum.sendCustomMeasurement(name, value)
   }
 
+  @ReactMethod
+  override fun startTimeMeasure(name: String, labels: ReadableMap?) {
+    CoralogixRum.startTimeMeasure(name, labels?.toStringAnyMap() ?: emptyMap())
+  }
+
+  @ReactMethod
+  override fun endTimeMeasure(name: String) {
+    CoralogixRum.endTimeMeasure(name)
+  }
+
   @ReactMethod
   override fun reportError(details: ReadableMap) {
     val errorType = details.getString("error_type").orEmpty()
@@ -290,10 +309,73 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
   }
   // endregion
 
+  // region - Custom Spans
+
+  @ReactMethod
+  override fun startGlobalSpan(name: String, labels: ReadableMap?, ignoredInstruments: ReadableArray?, promise: Promise) {
+    val ignoredSet = ignoredInstruments?.toIgnoredInstrumentSet() ?: emptySet()
+    val tracer = CoralogixRum.getCustomTracer(ignoredSet)
+    if (tracer == null) {
+      promise.resolve(null)
+      return
+    }
+    val globalSpan = tracer.startGlobalSpan(name, labels?.toStringAnyMap())
+    if (globalSpan == null) {
+      promise.resolve(null)
+      return
+    }
+    globalSpans[globalSpan.spanId] = globalSpan
+    val result = Arguments.createMap()
+    result.putString("spanId", globalSpan.spanId)
+    result.putString("traceId", globalSpan.traceId)
+    promise.resolve(result)
+  }
+
+  @ReactMethod
+  override fun startCustomSpan(parentSpanId: String, name: String, labels: ReadableMap?, promise: Promise) {
+    val globalSpan = globalSpans[parentSpanId]
+    if (globalSpan == null) {
+      promise.resolve(null)
+      return
+    }
+    val customSpan = globalSpan.startCustomSpan(name, labels?.toStringAnyMap())
+    val otelIds = extractOtelIds(customSpan)
+    if (otelIds == null) {
+      Log.e(NAME, "startCustomSpan: failed to extract OTel IDs via reflection — resolving null")
+      promise.resolve(null)
+      return
+    }
+    customSpans[otelIds.first] = customSpan
+    val result = Arguments.createMap()
+    result.putString("spanId", otelIds.first)
+    result.putString("traceId", otelIds.second)
+    promise.resolve(result)
+  }
+
+
+  @ReactMethod
+  override fun endSpan(spanId: String, promise: Promise) {
+    globalSpans.remove(spanId)?.let {
+      it.endSpan()
+      promise.resolve(null)
+      return
+    }
+    customSpans.remove(spanId)?.let {
+      it.endSpan()
+      promise.resolve(null)
+      return
+    }
+    Log.w(NAME, "endSpan: unknown spanId $spanId")
+    promise.resolve(null)
+  }
+
+  // endregion
+
   // region - utils
   override fun invalidate() {
     super.invalidate()
-
+    globalSpans.clear()
+    customSpans.clear()
     Handler(Looper.getMainLooper()).post {
       Log.d("CxSdkModule", "Bridge destroyed — shutting down CoralogixRum")
       CoralogixRum.shutdown()
@@ -354,6 +436,13 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
       getArray("networkExtraConfig")?.toNetworkCaptureRuleList() ?: emptyList()
     else emptyList()
 
+    val excludeFromSampling = if (hasKey("excludeFromSampling") && !isNull("excludeFromSampling"))
+      getArray("excludeFromSampling")?.toExcludeFromSamplingList() ?: emptyList()
+    else emptyList()
+
+    val sessionSampleRate =
+      if (hasKey("sessionSampleRate") && !isNull("sessionSampleRate")) getInt("sessionSampleRate") else 100
+
     return CoralogixOptions(
       applicationName = applicationName,
       coralogixDomain = coralogixDomain,
@@ -367,13 +456,23 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
       mobileVitalsOptions = getMap("mobileVitals")?.toMobileVitalsOptions() ?: mapOf(),
       ignoreUrls = getArray("ignoreUrls")?.handleStringOrRegexList() ?: listOf(),
       ignoreErrors = getArray("ignoreErrors")?.handleStringOrRegexList() ?: listOf(),
-      sessionSampleRate = 100,
+      sessionSampleRate = sessionSampleRate,
+      excludeFromSampling = excludeFromSampling,
       traceParentInHeader = traceParentInHeaderConfig,
       debug = if (hasKey("debug")) getBoolean("debug") else false,
       proxyUrl = getString("proxyUrl"),
       beforeSendCallback = if (hasKey("hasBeforeSend") && getBoolean("hasBeforeSend")) ::beforeSendCallback else null,
       collectIPData = collectIpData,
-      networkCaptureConfig = networkExtraConfig
+      networkCaptureConfig = networkExtraConfig,
+      tracesExporter = if (hasKey("hasTracesExporter") && getBoolean("hasTracesExporter")) {
+        { data: CoralogixTraceExporterData ->
+          if (reactApplicationContext.hasActiveReactInstance()) {
+            reactApplicationContext
+              .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+              .emit("onTracesExport", data.toJson())
+          }
+        }
+      } else null
     )
   }
 
@@ -523,8 +622,9 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
       "AP1" -> CoralogixDomain.AP1
       "AP2" -> CoralogixDomain.AP2
       "AP3" -> CoralogixDomain.AP3
+      "US3" -> CoralogixDomain.US3
       "STAGING" -> CoralogixDomain.STAGING
-      else -> throw IllegalArgumentException("Invalid coralogixDomain: $this. Must be one of [EU1, EU2, US1, US2, AP1, AP2, AP3, STAGING]")
+      else -> throw IllegalArgumentException("Invalid coralogixDomain: $this. Must be one of [EU1, EU2, US1, US2, US3, AP1, AP2, AP3, STAGING]")
     }
   }
 
@@ -758,6 +858,36 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
     return result
   }
 
+  private fun ReadableArray.toIgnoredInstrumentSet(): Set<CoralogixIgnoredInstrument> {
+    val set = mutableSetOf<CoralogixIgnoredInstrument>()
+    for (i in 0 until size()) {
+      when (getString(i)) {
+        "networkRequests" -> set.add(CoralogixIgnoredInstrument.NETWORK_REQUESTS)
+        "userInteractions" -> set.add(CoralogixIgnoredInstrument.USER_INTERACTIONS)
+        "errors" -> set.add(CoralogixIgnoredInstrument.ERRORS)
+      }
+    }
+    return set
+  }
+
+  private fun ReadableArray.toExcludeFromSamplingList(): List<ExcludableInstrumentation> {
+    val set = LinkedHashSet<ExcludableInstrumentation>()
+    for (i in 0 until size()) {
+      val value = getString(i)
+      when (value) {
+        "errors" -> set.add(ExcludableInstrumentation.Errors)
+        "logs" -> set.add(ExcludableInstrumentation.Logs)
+        "network" -> set.add(ExcludableInstrumentation.Network)
+        "userInteractions" -> set.add(ExcludableInstrumentation.UserInteractions)
+        "mobileVitals" -> set.add(ExcludableInstrumentation.MobileVitals)
+        "customSpan" -> set.add(ExcludableInstrumentation.CustomSpan)
+        "customMeasurement" -> set.add(ExcludableInstrumentation.CustomMeasurement)
+        else -> Log.w("CxSdkModule", "excludeFromSampling: unrecognized value '$value' — native enum may have drifted")
+      }
+    }
+    return set.toList()
+  }
+
   private fun ReadableArray.toHybridMetricList(): List<HybridMetric> {
     val out = ArrayList<HybridMetric>(size())
     for (i in 0 until size()) {
@@ -778,5 +908,22 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
 
   companion object {
     const val NAME = "CxSdk"
+
+    // TODO: replace reflection with a public accessor once the Coralogix Android SDK exposes one —
+    // 'getSpan$library_release' is a Kotlin-internal name that may be renamed in a future SDK version.
+    internal fun extractOtelIds(child: CoralogixCustomSpan): Pair<String, String>? =
+      extractOtelIds(child, "getSpan\$library_release")
+
+    internal fun extractOtelIds(child: CoralogixCustomSpan, accessorName: String): Pair<String, String>? = try {
+      val span = child.javaClass.getMethod(accessorName).invoke(child) ?: return null
+      val ctx = span.javaClass.getMethod("getSpanContext").invoke(span) ?: return null
+      val spanId = ctx.javaClass.getMethod("getSpanId").invoke(ctx) as? String
+      val traceId = ctx.javaClass.getMethod("getTraceId").invoke(ctx) as? String
+      if (spanId.isNullOrEmpty() || traceId.isNullOrEmpty()) null
+      else Pair(spanId, traceId)
+    } catch (e: Throwable) {
+      Log.w(NAME, "extractOtelIds: reflection failed — $e")
+      null
+    }
   }
 }

package/android/src/main/java/com/cxsdk/RUMClient.kt

@@ -16,10 +16,17 @@ interface RUMClient {
   fun log(severity: Int, message: String, data: ReadableMap, labels: ReadableMap)
   fun reportNetworkRequest(requestDetails: ReadableMap)
   fun sendCustomMeasurement(measurement: ReadableMap)
+  fun startTimeMeasure(name: String, labels: ReadableMap?)
+  fun endTimeMeasure(name: String)
   fun reportError(details: ReadableMap)
   fun sendCxSpanData(results: ReadableArray)
   fun reportMobileVitalsMeasurement(type: String, value: Double, units: String)
   fun reportMobileVitalsMeasurementSet(type: String, metrics: ReadableArray)
   fun isCoralogixGradlePluginApplied(promise: Promise)
   fun shutdown(promise: Promise)
+
+  // custom spans
+  fun startGlobalSpan(name: String, labels: ReadableMap?, ignoredInstruments: ReadableArray?, promise: Promise)
+  fun startCustomSpan(parentSpanId: String, name: String, labels: ReadableMap?, promise: Promise)
+  fun endSpan(spanId: String, promise: Promise)
 }

package/android/src/test/kotlin/com/cxsdk/ExtractOtelIdsTest.kt

@@ -0,0 +1,49 @@
+package com.cxsdk
+
+import com.coralogix.android.sdk.customspans.CoralogixCustomSpan
+import io.opentelemetry.api.trace.Span
+import io.opentelemetry.api.trace.SpanContext
+import io.opentelemetry.api.trace.TraceFlags
+import io.opentelemetry.api.trace.TraceState
+import org.mockito.Mockito.mock
+import org.mockito.Mockito.`when`
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNull
+
+class ExtractOtelIdsTest {
+
+    @Test
+    fun `extractOtelIds returns correct spanId and traceId via reflection`() {
+        val spanId  = "1234567890abcdef"
+        val traceId = "abcdef1234567890abcdef1234567890"
+
+        val mockSpan = mock(Span::class.java)
+        `when`(mockSpan.spanContext).thenReturn(
+            SpanContext.create(traceId, spanId, TraceFlags.getDefault(), TraceState.getDefault())
+        )
+
+        val result = CxSdkModule.extractOtelIds(CoralogixCustomSpan(mockSpan))
+
+        assertEquals(Pair(spanId, traceId), result)
+    }
+
+    @Test
+    fun `extractOtelIds returns null when spanContext returns null`() {
+        val mockSpan = mock(Span::class.java)
+        `when`(mockSpan.spanContext).thenReturn(null)
+
+        val result = CxSdkModule.extractOtelIds(CoralogixCustomSpan(mockSpan))
+
+        assertNull(result)
+    }
+
+    @Test
+    fun `extractOtelIds returns null when accessor method does not exist`() {
+        val mockSpan = mock(Span::class.java)
+
+        val result = CxSdkModule.extractOtelIds(CoralogixCustomSpan(mockSpan), "nonExistentMethod")
+
+        assertNull(result)
+    }
+}