@coralogix/react-native-plugin 0.3.3 → 0.5.0

package/ios/CxSdk.swift

@@ -1,5 +1,6 @@
 import Foundation
 import Coralogix
+import CoralogixInternal
 import SessionReplay
 import React
 
@@ -11,6 +12,9 @@ enum CxSdkError: Error {
 @objc(CxSdk)
 class CxSdk: RCTEventEmitter {
   var coralogixRum: CoralogixRum?
+  // Accessed only from the RN methodQueue (serial); no explicit locking required.
+  private var globalSpans: [String: CoralogixGlobalSpan] = [:]
+  private var customSpans: [String: CoralogixCustomSpan] = [:]
 
   override init() {
     super.init()
@@ -21,7 +25,7 @@ class CxSdk: RCTEventEmitter {
   }
 
   override func supportedEvents() -> [String]! {
-    return ["onBeforeSend"]
+    return ["onBeforeSend", "onTracesExport"]
   }
 
   @objc(initialize:withResolver:withRejecter:)
@@ -39,6 +43,15 @@ class CxSdk: RCTEventEmitter {
 
       var options = try self.toCoralogixOptions(parameter: parameter)
       options.beforeSendCallBack = beforeSendCallBack
+
+      let hasTracesExporter = parameter["hasTracesExporter"] as? Bool ?? false
+      if hasTracesExporter {
+        options.tracesExporter = { [weak self] data in
+          guard let jsonString = data.jsonString else { return }
+          self?.sendEvent(withName: "onTracesExport", body: jsonString)
+        }
+      }
+
       let rnPluginVersion =  parameter["frameworkVersion"] as? String ?? ""
 
       self.coralogixRum = CoralogixRum(options: options, sdkFramework: .reactNative(version: rnPluginVersion))
@@ -195,6 +208,8 @@ class CxSdk: RCTEventEmitter {
   @objc(shutdown:withRejecter:)
   func shutdown(resolve:RCTPromiseResolveBlock,
                 reject:RCTPromiseRejectBlock) -> Void {
+    globalSpans.removeAll()
+    customSpans.removeAll()
     coralogixRum?.shutdown()
     resolve("shutdown success")
   }
@@ -353,6 +368,17 @@ class CxSdk: RCTEventEmitter {
     resolve("sendCustomMeasurement success")
   }
 
+  @objc(startTimeMeasure:labels:)
+  func startTimeMeasure(name: String, labels: NSDictionary) {
+    let labelsDict = labels as? [String: Any]
+    coralogixRum?.startTimeMeasure(name: name, labels: labelsDict)
+  }
+
+  @objc(endTimeMeasure:)
+  func endTimeMeasure(name: String) {
+    coralogixRum?.endTimeMeasure(name: name)
+  }
+
   private func toHybridMetricList(metrics: NSArray) -> [HybridMetric] {
     let array = metrics as? [[String: Any]] ?? []
 
@@ -457,6 +483,9 @@ class CxSdk: RCTEventEmitter {
     let ignoreError = (parameter["ignoreErrors"] as? [Any])?.compactMap { $0 as? String } ?? []
     let rawNetworkExtraConfig = parameter["networkExtraConfig"] as? [[String: Any]]
     let networkExtraConfig = toNetworkCaptureRuleList(rawNetworkExtraConfig)
+    let excludeFromSampling = toExcludeFromSampling(parameter["excludeFromSampling"] as? [Any])
+
+    let sessionSampleRate = (parameter["sessionSampleRate"] as? NSNumber)?.intValue ?? 100
 
     let options = CoralogixExporterOptions(
       coralogixDomain: coralogixDomain,
@@ -468,6 +497,8 @@ class CxSdk: RCTEventEmitter {
                                            ignoreUrls: ignoreUrls,
                                            ignoreErrors: ignoreError,
                                            labels: labels,
+                                           sessionSampleRate: sessionSampleRate,
+                                           excludeFromSampling: excludeFromSampling,
                                            instrumentations: instrumentationDict,
                                            collectIPData: parameter["collectIPData"] as? Bool ?? true,
                                           proxyUrl: parameter["proxyUrl"] as? String ?? nil,
@@ -579,6 +610,23 @@ class CxSdk: RCTEventEmitter {
     }
   }
 
+  private func toExcludeFromSampling(_ raw: [Any]?) -> Set<ExcludableInstrumentation> {
+    guard let raw = raw else { return [] }
+    var result: Set<ExcludableInstrumentation> = []
+    for value in raw {
+      guard let key = value as? String else {
+        debugPrint("[CxSdk] excludeFromSampling: ignoring non-string value \(value)")
+        continue
+      }
+      guard let instrumentation = ExcludableInstrumentation(rawValue: key) else {
+        debugPrint("[CxSdk] excludeFromSampling: unrecognized value '\(key)' — native enum may have drifted")
+        continue
+      }
+      result.insert(instrumentation)
+    }
+    return result
+  }
+
   private func instrumentationType(from string: String) -> CoralogixExporterOptions.InstrumentationType? {
     switch string {
     case "mobile_vitals":
@@ -600,6 +648,78 @@ class CxSdk: RCTEventEmitter {
     }
   }
 
+  // MARK: - Custom Spans
+
+  @objc(startGlobalSpan:labels:ignoredInstruments:withResolver:withRejecter:)
+  func startGlobalSpan(name: String,
+                       labels: NSDictionary?,
+                       ignoredInstruments: NSArray?,
+                       resolve: RCTPromiseResolveBlock,
+                       reject: RCTPromiseRejectBlock) {
+    guard let rum = coralogixRum else { resolve(nil); return }
+    let ignored = toIgnoredInstrumentSet(ignoredInstruments)
+    guard let tracer = rum.getCustomTracer(ignoredInstruments: ignored) else { resolve(nil); return }
+    let labelsDict = toAnyDict(labels)
+    guard let globalSpan = tracer.startGlobalSpan(name: name, labels: labelsDict) else { resolve(nil); return }
+    let spanId = globalSpan.spanId
+    let traceId = globalSpan.traceId
+    globalSpans[spanId] = globalSpan
+    resolve(["spanId": spanId, "traceId": traceId])
+  }
+
+  @objc(startCustomSpan:name:labels:withResolver:withRejecter:)
+  func startCustomSpan(parentSpanId: String,
+                       name: String,
+                       labels: NSDictionary?,
+                       resolve: RCTPromiseResolveBlock,
+                       reject: RCTPromiseRejectBlock) {
+    guard let globalSpan = globalSpans[parentSpanId] else { resolve(nil); return }
+    let labelsDict = toAnyDict(labels)
+    let customSpan = globalSpan.startCustomSpan(name: name, labels: labelsDict)
+    let spanId = customSpan.span.context.spanId.hexString
+    let traceId = globalSpan.traceId
+    guard !spanId.isEmpty else { resolve(nil); return }
+    customSpans[spanId] = customSpan
+    resolve(["spanId": spanId, "traceId": traceId])
+  }
+
+  @objc(endSpan:withResolver:withRejecter:)
+  func endSpan(spanId: String,
+               resolve: RCTPromiseResolveBlock,
+               reject: RCTPromiseRejectBlock) {
+    if let globalSpan = globalSpans.removeValue(forKey: spanId) {
+      globalSpan.endSpan()
+    } else if let customSpan = customSpans.removeValue(forKey: spanId) {
+      customSpan.endSpan()
+    }
+    resolve(nil)
+  }
+
+  private func toIgnoredInstrumentSet(_ array: NSArray?) -> Set<CoralogixIgnoredInstrument> {
+    guard let array = array else { return [] }
+    var set = Set<CoralogixIgnoredInstrument>()
+    for item in array {
+      switch item as? String {
+      case "networkRequests": set.insert(.networkRequests)
+      case "userInteractions": set.insert(.userInteractions)
+      case "errors": set.insert(.errors)
+      default: break
+      }
+    }
+    return set
+  }
+
+  private func toAnyDict(_ dict: NSDictionary?) -> [String: Any]? {
+    guard let dict = dict, dict.count > 0 else { return nil }
+    var result = [String: Any]()
+    for (key, value) in dict {
+      if let k = key as? String {
+        result[k] = value
+      }
+    }
+    return result.isEmpty ? nil : result
+  }
+
   private func getCoralogixDomain(domain: String) -> CoralogixDomain {
     switch domain.uppercased() {
     case "EU1":
@@ -616,6 +736,8 @@ class CxSdk: RCTEventEmitter {
       return .AP2
     case "AP3":
       return .AP3
+    case "US3":
+      return .US3
     case "STAGING":
       return .STG
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralogix/react-native-plugin",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Official Coralogix React Native plugin",
   "license": "Apache-2.0",
   "author": "Coralogix",

package/src/custom-spans/CoralogixCustomSpan.d.ts

@@ -0,0 +1,9 @@
+import type { CustomSpanBridge } from './CustomSpanBridge';
+/** A child span nested under a {@link CoralogixGlobalSpan}. */
+export declare class CoralogixCustomSpan {
+    readonly spanId: string;
+    readonly traceId: string;
+    private readonly bridge;
+    constructor(spanId: string, traceId: string, bridge: CustomSpanBridge);
+    endSpan(): Promise<void>;
+}

package/src/custom-spans/CoralogixCustomTracer.d.ts

@@ -0,0 +1,18 @@
+import type { CoralogixIgnoredInstrument } from '../model/Types';
+import { CoralogixGlobalSpan } from './CoralogixGlobalSpan';
+import type { CustomSpanBridge } from './CustomSpanBridge';
+/**
+ * Entry point for manual RUM tracing. Obtain an instance via `CoralogixRum.getCustomTracer()`.
+ * The `ignoredInstruments` list controls which auto-instrumented events are NOT linked to spans
+ * created by this tracer (e.g. passing `['networkRequests']` keeps network spans independent).
+ */
+export declare class CoralogixCustomTracer {
+    private readonly ignoredInstruments;
+    private readonly bridge;
+    constructor(ignoredInstruments: CoralogixIgnoredInstrument[], bridge: CustomSpanBridge);
+    /**
+     * Starts a new global (root) span. Returns `null` if a global span is already active —
+     * only one global span may exist at a time across the entire app.
+     */
+    startGlobalSpan(name: string, labels?: Record<string, any>): Promise<CoralogixGlobalSpan | null>;
+}

package/src/custom-spans/CoralogixGlobalSpan.d.ts

@@ -0,0 +1,20 @@
+import { CoralogixCustomSpan } from './CoralogixCustomSpan';
+import type { CustomSpanBridge } from './CustomSpanBridge';
+/** A root-level custom span. All child spans and `withContext` network calls share its traceId. */
+export declare class CoralogixGlobalSpan {
+    readonly spanId: string;
+    readonly traceId: string;
+    private readonly bridge;
+    constructor(spanId: string, traceId: string, bridge: CustomSpanBridge);
+    /** Creates a child span nested under this global span. */
+    startCustomSpan(name: string, labels?: Record<string, any>): Promise<CoralogixCustomSpan | null>;
+    /**
+     * Runs fn() with this span set as the active global span for the duration of
+     * the returned promise. The active span ID remains set throughout the full
+     * async chain — including code after intermediate awaits — because we await
+     * fn() before clearing. Only detached callbacks (e.g. setTimeout) that fire
+     * after withContext resolves won't be linked.
+     */
+    withContext<T>(fn: () => Promise<T>): Promise<T>;
+    endSpan(): Promise<void>;
+}

package/src/custom-spans/CustomSpanBridge.d.ts

@@ -0,0 +1,11 @@
+export interface CustomSpanBridge {
+    startGlobalSpan(name: string, labels: Record<string, any> | null, ignoredInstruments: string[]): Promise<{
+        spanId: string;
+        traceId: string;
+    } | null>;
+    startCustomSpan(parentSpanId: string, name: string, labels: Record<string, any> | null): Promise<{
+        spanId: string;
+        traceId: string;
+    } | null>;
+    endSpan(spanId: string): Promise<void>;
+}

package/src/custom-spans/CustomSpanRegistry.d.ts

@@ -0,0 +1,12 @@
+import type { CoralogixIgnoredInstrument } from '../model/Types';
+export declare const CustomSpanRegistry: {
+    getActive: () => string | null;
+    setActive: (id: string) => void;
+    clearActive: () => void;
+    registerSpan: (spanId: string, traceId: string) => void;
+    unregisterSpan: (spanId: string) => void;
+    getTraceId: (spanId: string) => string | undefined;
+    setIgnoredInstruments: (set: Set<CoralogixIgnoredInstrument>) => void;
+    getIgnoredInstruments: () => Set<CoralogixIgnoredInstrument>;
+    clear: () => void;
+};

package/src/index.d.ts

@@ -10,6 +10,7 @@ interface CxSdkClient {
     initialize(options: CoralogixBrowserSdkConfig & {
         frameworkVersion?: string;
         hasBeforeSend?: boolean;
+        hasTracesExporter?: boolean;
     }): Promise<boolean>;
     setUserContext(userContext: UserContextConfig): void;
     getUserContext(): Promise<UserContextConfig>;
@@ -20,6 +21,8 @@ interface CxSdkClient {
     setViewContext(viewContext: string): void;
     log(severity: CoralogixLogSeverity, message: string, data: Record<string, any> | undefined | null, labels: Record<string, any> | undefined | null): void;
     sendCustomMeasurement(measurement: CustomMeasurement): void;
+    startTimeMeasure(name: string, labels: Record<string, unknown>): void;
+    endTimeMeasure(name: string): void;
     reportError(details: Record<string, string>): void;
     reportNetworkRequest(details: NetworkRequestDetails): void;
     shutdown(): Promise<boolean>;
@@ -38,6 +41,15 @@ interface CxSdkClient {
     captureScreenshot(): void;
     maskViewByTag(viewTag: number): void;
     reportUserInteraction(interaction: InteractionContext): void;
+    startGlobalSpan(name: string, labels: Record<string, any> | null, ignoredInstruments: string[]): Promise<{
+        spanId: string;
+        traceId: string;
+    } | null>;
+    startCustomSpan(parentSpanId: string, name: string, labels: Record<string, any> | null): Promise<{
+        spanId: string;
+        traceId: string;
+    } | null>;
+    endSpan(spanId: string): Promise<void>;
 }
 export declare const CxSdk: CxSdkClient;
 export declare const CoralogixRum: CoralogixOtelWebType;
@@ -47,9 +59,12 @@ export { type ApplicationContextConfig } from './model/ApplicationContextConfig'
 export { type ViewContextConfig } from './model/ViewContextConfig';
 export { CoralogixDomain } from './model/CoralogixDomain';
 export { type UserContextConfig } from './model/UserContextConfig';
-export { type CoralogixBrowserSdkConfig, type NetworkCaptureRule, CoralogixLogSeverity, } from './model/Types';
+export { type CoralogixBrowserSdkConfig, type CoralogixIgnoredInstrument, type ExcludableInstrumentation, type NetworkCaptureRule, type TraceExporterData, CoralogixLogSeverity, } from './model/Types';
 export { type CoralogixOtelWebOptionsInstrumentations } from './model/CoralogixOtelWebOptionsInstrumentations';
 export { type CustomMeasurement } from './model/CustomMeasurement';
 export { type NetworkRequestDetails } from './model/NetworkRequestDetails';
 export { type CoralogixMobileVitals } from './model/CoralogixMobileVitals';
 export { attachReactNavigationObserver } from './instrumentations/navigation/NavigationInstrumentation';
+export { CoralogixCustomTracer } from './custom-spans/CoralogixCustomTracer';
+export { CoralogixGlobalSpan } from './custom-spans/CoralogixGlobalSpan';
+export { CoralogixCustomSpan } from './custom-spans/CoralogixCustomSpan';

package/src/model/CoralogixDomain.d.ts

@@ -6,5 +6,6 @@ export declare enum CoralogixDomain {
     AP1 = "AP1",
     AP2 = "AP2",
     AP3 = "AP3",
+    US3 = "US3",
     STAGING = "staging"
 }

package/src/model/CoralogixOtelWebType.d.ts

@@ -1,11 +1,12 @@
 import type { SendLog } from './SendLog';
 import type { CoralogixRumLabels } from './CoralogixRumLabels';
-import { CoralogixBrowserSdkConfig } from './Types';
+import { CoralogixBrowserSdkConfig, CoralogixIgnoredInstrument } from './Types';
 import { UserContextConfig } from './UserContextConfig';
 import { ViewContextConfig } from './ViewContextConfig';
 import { ApplicationContextConfig } from './ApplicationContextConfig';
 import { CustomMeasurement } from './CustomMeasurement';
 import { NetworkRequestDetails } from './NetworkRequestDetails';
+import { CoralogixCustomTracer } from '../custom-spans/CoralogixCustomTracer';
 export interface CoralogixOtelWebType extends SendLog {
     /**
      * Init CoralogixRum.
@@ -40,11 +41,29 @@ export interface CoralogixOtelWebType extends SendLog {
      * Send custom key value pair
      */
     sendCustomMeasurement: (measurement: CustomMeasurement) => void;
+    /**
+     * Start a time measurement for `name`. The native SDK records the start
+     * timestamp; the call is fire-and-forget. Pair every `startTimeMeasure`
+     * with exactly one `endTimeMeasure(name)` — leaked starts persist in
+     * memory until shutdown.
+     */
+    startTimeMeasure: (name: string, labels?: Record<string, unknown>) => void;
+    /**
+     * End a previously started time measurement. The native SDK computes the
+     * duration and reports it as a custom-measurement span (milliseconds).
+     * Unknown names are dropped silently by the native SDK.
+     */
+    endTimeMeasure: (name: string) => void;
     reportError: (error: Error, isCrash: boolean) => void;
     /**
      * Report a network request to the underlying Coralogix SDK
      * @param details
      */
     reportNetworkRequest: (details: NetworkRequestDetails) => void;
+    /**
+     * Returns a tracer for creating custom spans. Instruments listed in
+     * ignoredInstruments will not be auto-parented to the active global span.
+     */
+    getCustomTracer: (ignoredInstruments?: CoralogixIgnoredInstrument[]) => CoralogixCustomTracer;
     readonly isInited: boolean;
 }

package/src/model/Types.d.ts

@@ -200,6 +200,11 @@ export interface CoralogixBrowserSdkConfig {
     environment?: string;
     /** Percentage of overall sessions being tracked, defaults to 100%  */
     sessionSampleRate?: number;
+    /**
+     * Event categories that bypass session sampling. Events of these categories are
+     * emitted even when the session is sampled out. Defaults to `[]`.
+     */
+    excludeFromSampling?: ExcludableInstrumentation[];
     /** Collect IP data */
     collectIPData?: boolean;
     /** Enable event access and modification before sending to Coralogix, supporting content modification, and event discarding. */
@@ -218,12 +223,30 @@ export interface CoralogixBrowserSdkConfig {
         sampleIntervalMs?: number;
     };
     mobileVitals?: CoralogixMobileVitals;
+    /** Callback invoked with each OTLP trace batch exported by the native SDK. */
+    tracesExporter?: (data: TraceExporterData) => void;
 }
 export type HybridMetric = {
     name: string;
     value: number;
     units: string;
 };
+/**
+ * Instrumentation names that can be excluded from a custom tracer's span context.
+ * Pass one or more values to `getCustomTracer()` to prevent those event types from
+ * being linked to spans created by that tracer.
+ */
+export type CoralogixIgnoredInstrument = 'networkRequests' | 'userInteractions' | 'errors';
+/**
+ * Event categories that can opt out of session sampling. When the session is
+ * sampled out, events whose category is listed in `excludeFromSampling` are still
+ * emitted; everything else is dropped. Mirrors the iOS/Android native enums.
+ */
+export type ExcludableInstrumentation = 'errors' | 'logs' | 'network' | 'userInteractions' | 'mobileVitals' | 'customSpan' | 'customMeasurement';
+/** OTLP JSON-format trace data delivered to the `tracesExporter` callback. */
+export interface TraceExporterData {
+    resource_spans: Record<string, unknown>[];
+}
 export interface InteractionContext {
     type: 'click' | 'scroll' | 'swipe';
     /** Required. Element identifier: accessibilityLabel ?? componentName for clicks; 'ScrollView' for scroll/swipe. */