@coralogix/browser 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2.12.0 (2025-11-30)
+
+### 🚀 Features
+
+- Introduced the tracesExporter callback, enabling custom processing or exporting of collected trace events.
+
+
+## 2.11.1 (2025-11-24)
+
+### 🩹 Fixes
+
+- Trigger snapshot context when setUserContext is called
+
 ## 2.11.0 (2025-11-23)
 
 ### 🚀 Features

package/README.md

@@ -901,6 +901,28 @@ const customTracer = CoralogixRum.getCustomTracer({
 // ... your code
 ```
 
+### Traces Exporter
+
+The `tracesExporter` callback gives you full control over how collected trace events are handled.  
+It receives a `TracesExporterPayload` object containing all trace data that the SDK has collected.
+
+```ts
+CoralogixRum.init({
+  tracesExporter: (data: TraceExporterData) => {
+    // Example: forward traces to your own backend endpoint
+    fetch('https://api.mycompany.com/rum-traces', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+  },
+});
+```
+
+
 ### Soft Navigations — Experimental
 
 Soft navigations are navigations that do not trigger a full page reload, such as SPA navigations. Defaults to false.

package/index.esm2.js

@@ -3381,6 +3381,179 @@ function isProcessorShouldStop(isActive) {
     return !isActive || !!((_a = getSessionManager()) === null || _a === void 0 ? void 0 : _a.isIdleActive);
 }
 
+var NANOS_IN_SECOND = 1000000000;
+var NANOS_PER_MILLISECOND = 1000000;
+var MAX_FUTURE_NANOS = 60 * 60 * NANOS_IN_SECOND;
+var MAX_PAST_NANOS = 24 * 60 * 60 * NANOS_IN_SECOND;
+
+function toOtlpKeyValue(key, value) {
+    if (!value) {
+        return { key: key, value: { string_value: '' } };
+    }
+    switch (typeof value) {
+        case 'string':
+            return { key: key, value: { string_value: value } };
+        case 'number':
+            if (!Number.isFinite(value)) {
+                return {
+                    key: key,
+                    value: { string_value: String(value) },
+                };
+            }
+            return Number.isInteger(value)
+                ? { key: key, value: { int_value: value } }
+                : { key: key, value: { double_value: value } };
+        case 'boolean':
+            return { key: key, value: { bool_value: value } };
+        default:
+            return { key: key, value: { string_value: '' } };
+    }
+}
+function toOtlpAttributes(attributes) {
+    if (!attributes)
+        return [];
+    return Object.entries(attributes).map(function (_a) {
+        var _b = __read$1(_a, 2), k = _b[0], v = _b[1];
+        return toOtlpKeyValue(k, v);
+    });
+}
+function timestampToNanosNumber(timestamp) {
+    var _a = __read$1(timestamp, 2), seconds = _a[0], nanos = _a[1];
+    return seconds * NANOS_IN_SECOND + nanos;
+}
+function timestampToNanosString(timestamp) {
+    var _a = __read$1(timestamp, 2), seconds = _a[0], nanos = _a[1];
+    var secondsPart = String(seconds);
+    var nanosPart = String(nanos).padStart(9, '0');
+    return secondsPart + nanosPart;
+}
+function hexToBase64(hex) {
+    if (!hex)
+        return '';
+    var binary = '';
+    for (var i = 0; i < hex.length; i += 2) {
+        var byte = Number.parseInt(hex.slice(i, i + 2), 16);
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function mapStatusCodeToOtlp(code) {
+    var _a;
+    if (code == null)
+        return undefined;
+    var STATUS_CODE_MAP = {
+        0: 'STATUS_CODE_UNSET',
+        1: 'STATUS_CODE_OK',
+        2: 'STATUS_CODE_ERROR',
+    };
+    return (_a = STATUS_CODE_MAP[code]) !== null && _a !== void 0 ? _a : 'STATUS_CODE_UNSET';
+}
+function toOtlpStatus(spanStatus) {
+    if (!spanStatus)
+        return undefined;
+    var code = mapStatusCodeToOtlp(spanStatus.code);
+    var message = spanStatus.message;
+    if (!code && !message)
+        return undefined;
+    return __assign({ code: code !== null && code !== void 0 ? code : 'STATUS_CODE_UNSET' }, (message ? { message: message } : {}));
+}
+function isWithinAllowedWindow(start, now) {
+    return start <= now + MAX_FUTURE_NANOS && start >= now - MAX_PAST_NANOS;
+}
+
+function buildExporterPayload(logs) {
+    var e_1, _a;
+    var _b;
+    var resourceSpans = [];
+    var nowUnixNano = Date.now() * NANOS_PER_MILLISECOND;
+    try {
+        for (var logs_1 = __values$1(logs), logs_1_1 = logs_1.next(); !logs_1_1.done; logs_1_1 = logs_1.next()) {
+            var entry = logs_1_1.value;
+            var instrumentationData = entry.instrumentation_data;
+            if (!instrumentationData)
+                continue;
+            var spanJson = mapCxSpanToOtlpSpan(instrumentationData.otelSpan);
+            if (!spanJson)
+                continue;
+            var startNanos = timestampToNanosNumber(instrumentationData.otelSpan.startTime);
+            if (!isWithinAllowedWindow(startNanos, nowUnixNano))
+                continue;
+            var resource = mapEntryToOtlpResource(entry, (_b = instrumentationData.otelResource) === null || _b === void 0 ? void 0 : _b.attributes);
+            var scopeSpans = {
+                spans: [spanJson],
+            };
+            resourceSpans.push({ resource: resource, scope_spans: [scopeSpans] });
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (logs_1_1 && !logs_1_1.done && (_a = logs_1.return)) _a.call(logs_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return { resource_spans: resourceSpans };
+}
+function stripOtelFieldsFromLogs(logs) {
+    return logs.map(function (_a) {
+        _a.instrumentation_data; var rest = __rest(_a, ["instrumentation_data"]);
+        return rest;
+    });
+}
+function mapCxSpanToOtlpSpan(span) {
+    var _a;
+    if (!span.traceId || !span.spanId || !span.name) {
+        if (getSdkConfig().debug) {
+            console.debug('Missing required span fields: traceId, spanId, name', span);
+            return null;
+        }
+    }
+    if (!span.startTime || !span.endTime) {
+        if (getSdkConfig().debug) {
+            console.debug('Missing span timestamps', span);
+        }
+        return null;
+    }
+    var ids = encodeSpanIds(span);
+    if (!ids)
+        return null;
+    var startUnixNano = timestampToNanosString(span.startTime);
+    var endUnixNano = timestampToNanosString(span.endTime);
+    return __assign(__assign(__assign({ trace_id: ids.traceIdB64, span_id: ids.spanIdB64 }, (ids.parentSpanIdB64 ? { parentSpanId: ids.parentSpanIdB64 } : {})), { name: (_a = span.name) !== null && _a !== void 0 ? _a : '', kind: 'SPAN_KIND_CLIENT', start_time_unix_nano: startUnixNano, end_time_unix_nano: endUnixNano, attributes: toOtlpAttributes(span.attributes) }), (span.status ? { status: toOtlpStatus(span.status) } : {}));
+}
+function mapEntryToOtlpResource(entry, extra) {
+    var _a;
+    var base = {
+        'cx.application.name': entry.applicationName,
+        'cx.subsystem.name': entry.subsystemName,
+    };
+    var merged = __assign(__assign({}, base), (extra !== null && extra !== void 0 ? extra : {}));
+    if (!('service.name' in merged)) {
+        merged['service.name'] = entry.applicationName;
+    }
+    var version = (_a = entry.version_metadata) === null || _a === void 0 ? void 0 : _a.app_version;
+    if (version && !('service.version' in merged)) {
+        merged['service.version'] = version;
+    }
+    var attributes = toOtlpAttributes(merged);
+    return attributes.length ? { attributes: attributes } : {};
+}
+function encodeSpanIds(span) {
+    return {
+        traceIdB64: hexToBase64(span.traceId),
+        spanIdB64: hexToBase64(span.spanId),
+        parentSpanIdB64: span.parentSpanId
+            ? hexToBase64(span.parentSpanId)
+            : undefined,
+    };
+}
+
+function buildCustomTraces(logs) {
+    var tracesPayload = buildExporterPayload(logs);
+    var strippedLogs = stripOtelFieldsFromLogs(logs);
+    return { tracesPayload: tracesPayload, strippedLogs: strippedLogs };
+}
+
 var CoralogixExporter = (function () {
     function CoralogixExporter() {
         var _this = this;
@@ -3393,6 +3566,9 @@ var CoralogixExporter = (function () {
         this.batchTimeDelay = BATCH_TIME_DELAY;
         this.invokeLogRequest = function (logs, markCachedLogsSent) {
             if (logs === null || logs === void 0 ? void 0 : logs.length) {
+                if (_this.sdkConfig.tracesExporter) {
+                    logs = _this.buildAndExportOtelTraces(logs);
+                }
                 _this.request
                     .send(JSON.stringify({
                     logs: logs,
@@ -3463,6 +3639,14 @@ var CoralogixExporter = (function () {
             }
         }
     };
+    CoralogixExporter.prototype.buildAndExportOtelTraces = function (logs) {
+        var hasOtelSpanData = logs.some(function (log) { return !!log.instrumentation_data; });
+        if (!hasOtelSpanData)
+            return logs;
+        var _a = buildCustomTraces(logs), tracesPayload = _a.tracesPayload, strippedLogs = _a.strippedLogs;
+        this.sdkConfig.tracesExporter(tracesPayload);
+        return strippedLogs;
+    };
     CoralogixExporter.prototype.clearCachedDataForSessionWithError = function () {
         CxGlobal.cachedLogs = [];
         this.batchTimeDelay = BATCH_TIME_DELAY;
@@ -3968,7 +4152,7 @@ function resolveUrlBlueprinters(urlBlueprinters) {
     return resolvedUrlBlueprinters;
 }
 
-var SDK_VERSION = '2.11.0';
+var SDK_VERSION = '2.12.0';
 
 function shouldDropEvent(cxRumEvent, options) {
     if (isDocumentErrorWithoutMessage(cxRumEvent)) {
@@ -4378,6 +4562,10 @@ var CoralogixSnapshotSpanProcessor = (function () {
         if (spanType === CoralogixEventType.USER_INTERACTION) {
             updateSnapshot({ actionCount: actionCount + 1 });
         }
+        if (getSnapshotManager().shouldTriggerSnapshotContext) {
+            shouldCreateSnapshot = true;
+            getSnapshotManager().shouldTriggerSnapshotContext = false;
+        }
         return shouldCreateSnapshot;
     };
     return CoralogixSnapshotSpanProcessor;
@@ -4386,6 +4574,7 @@ var CoralogixSnapshotSpanProcessor = (function () {
 var SnapshotManager = (function () {
     function SnapshotManager() {
         var _this = this;
+        this._shouldTriggerSnapshotContext = false;
         this.updateSnapshot = function (overrides) {
             _this._currentSnapshot = __assign(__assign({}, _this._currentSnapshot), overrides);
         };
@@ -4421,6 +4610,16 @@ var SnapshotManager = (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(SnapshotManager.prototype, "shouldTriggerSnapshotContext", {
+        get: function () {
+            return this._shouldTriggerSnapshotContext;
+        },
+        set: function (value) {
+            this._shouldTriggerSnapshotContext = value;
+        },
+        enumerable: false,
+        configurable: true
+    });
     return SnapshotManager;
 }());
 
@@ -4793,6 +4992,7 @@ var CoralogixRum = {
             console.debug('CoralogixRum must be initiated before setting user context');
             return;
         }
+        getSnapshotManager().shouldTriggerSnapshotContext = true;
         attributesProcessor === null || attributesProcessor === void 0 ? void 0 : attributesProcessor.setInternalLabels(__assign(__assign({}, attributesProcessor.getInternalLabels()), (_a = {}, _a[CoralogixAttributes.USER_CONTEXT] = userContext, _a)));
     },
     getUserContext: function () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralogix/browser",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Official Coralogix SDK for browsers",
   "license": "Apache-2.0",
   "author": "Coralogix",

package/src/processors/CoralogixExporter.d.ts

@@ -14,6 +14,7 @@ export declare class CoralogixExporter implements SpanExporter, ProcessorBaseMod
     export(spans: CxReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     private handleSessionWithError;
     private invokeLogRequest;
+    private buildAndExportOtelTraces;
     clearCachedDataForSessionWithError(): void;
     shutdown(): Promise<void>;
 }

package/src/snapshot/snapshotManager.d.ts

@@ -3,11 +3,14 @@ export declare class SnapshotManager {
     private _currentSnapshot;
     private _fragmentsState;
     private _isSnapshotSentDueToRecording;
+    private _shouldTriggerSnapshotContext;
     constructor();
     get fragmentsState(): Set<string>;
     get currentSnapshot(): SnapshotContext;
     get isSnapshotSentDueToRecording(): boolean;
+    get shouldTriggerSnapshotContext(): boolean;
     set isSnapshotSentDueToRecording(value: boolean);
+    set shouldTriggerSnapshotContext(value: boolean);
     updateSnapshot: (overrides: Partial<SnapshotContext>) => void;
     resetSnapshot: () => void;
 }

package/src/traces-exporter/trace-exporter.const.d.ts

@@ -0,0 +1,4 @@
+export declare const NANOS_IN_SECOND = 1000000000;
+export declare const NANOS_PER_MILLISECOND = 1000000;
+export declare const MAX_FUTURE_NANOS: number;
+export declare const MAX_PAST_NANOS: number;

package/src/traces-exporter/trace-exporter.d.ts

@@ -0,0 +1,3 @@
+import { CxSpan } from '../types';
+import { BuildCustomTracesResult } from './traces-exporter.types';
+export declare function buildCustomTraces(logs: CxSpan[]): BuildCustomTracesResult;

package/src/traces-exporter/traces-exporter.converter.d.ts

@@ -0,0 +1,4 @@
+import { TraceExporterData } from './traces-exporter.types';
+import { CxSpan } from '../types';
+export declare function buildExporterPayload(logs: CxSpan[]): TraceExporterData;
+export declare function stripOtelFieldsFromLogs(logs: CxSpan[]): Omit<CxSpan, 'instrumentation_data'>[];

package/src/traces-exporter/traces-exporter.types.d.ts

@@ -0,0 +1,71 @@
+import type { HrTime, SpanStatusCode } from '@opentelemetry/api';
+import { CxSpan } from '../types';
+export interface OtlpAnyValueJson {
+    string_value?: string;
+    bool_value?: boolean;
+    int_value?: number | string;
+    double_value?: number | string;
+}
+export interface OtlpKeyValueJson {
+    key: string;
+    value?: OtlpAnyValueJson;
+}
+export type OtlpStatusCodeJson = 'STATUS_CODE_UNSET' | 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR';
+export interface OtlpStatusJson {
+    code?: OtlpStatusCodeJson;
+    message?: string;
+}
+export type OtlpSpanKindJson = 'SPAN_KIND_INTERNAL' | 'SPAN_KIND_SERVER' | 'SPAN_KIND_CLIENT' | 'SPAN_KIND_PRODUCER' | 'SPAN_KIND_CONSUMER';
+export interface OtlpSpanJson {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    kind: OtlpSpanKindJson;
+    start_time_unix_nano: string;
+    end_time_unix_nano: string;
+    attributes?: OtlpKeyValueJson[];
+    status?: OtlpStatusJson;
+}
+export interface OtlpScopeJson {
+    name?: string;
+    version?: string;
+    attributes?: OtlpKeyValueJson[];
+}
+export interface OtlpScopeSpansJson {
+    scope?: OtlpScopeJson;
+    spans: OtlpSpanJson[];
+}
+export interface OtlpResourceJson {
+    attributes?: OtlpKeyValueJson[];
+}
+export interface OtlpResourceSpansJson {
+    resource?: OtlpResourceJson;
+    scope_spans: OtlpScopeSpansJson[];
+}
+export type CustomTimestamp = [seconds: number, nanos: number];
+export type ResourceAttributes = Record<string, unknown>;
+export interface TraceExporterData {
+    resource_spans: OtlpResourceSpansJson[];
+}
+export interface CxSpanOtelSpan {
+    spanId: string;
+    traceId: string;
+    sessionId?: string;
+    parentSpanId?: string;
+    name?: string;
+    attributes?: Record<string, unknown>;
+    startTime?: HrTime;
+    endTime?: HrTime;
+    status?: {
+        code: SpanStatusCode | number;
+        message?: string;
+    };
+}
+export interface CxSpanOtelResource {
+    attributes?: Record<string, unknown>;
+}
+export interface BuildCustomTracesResult {
+    tracesPayload: TraceExporterData;
+    strippedLogs: CxSpan[];
+}

package/src/traces-exporter/traces-exporter.utils.d.ts

@@ -0,0 +1,10 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import { CustomTimestamp, CxSpanOtelSpan, OtlpKeyValueJson, OtlpStatusCodeJson, OtlpStatusJson } from './traces-exporter.types';
+export declare function toOtlpKeyValue(key: string, value: unknown): OtlpKeyValueJson;
+export declare function toOtlpAttributes(attributes?: Record<string, unknown>): OtlpKeyValueJson[];
+export declare function timestampToNanosNumber(timestamp: CustomTimestamp): number;
+export declare function timestampToNanosString(timestamp: CustomTimestamp): string;
+export declare function hexToBase64(hex: string): string;
+export declare function mapStatusCodeToOtlp(code?: SpanStatusCode | number): OtlpStatusCodeJson | undefined;
+export declare function toOtlpStatus(spanStatus?: CxSpanOtelSpan['status']): OtlpStatusJson | undefined;
+export declare function isWithinAllowedWindow(start: number, now: number): boolean;

package/src/types.d.ts

@@ -17,6 +17,7 @@ import { MemoryUsageContext } from './instrumentations/memory-usage';
 import { MFEMetadata } from './mfe/mfe.types';
 import { UrlBasedLabelProvider } from './label-providers/url-based-label-provider';
 import { CustomTracer, CustomTracerIgnoredInstruments } from './custom-spans';
+import { TraceExporterData } from './traces-exporter/traces-exporter.types';
 export interface CxStackFrame extends Partial<MFEMetadata> {
     fileName?: string;
     columnNumber?: number;
@@ -157,6 +158,7 @@ export interface CoralogixBrowserSdkConfig {
     networkExtraConfig?: NetworkExtraConfig[];
     supportMfe?: boolean;
     workerSupport?: boolean;
+    tracesExporter?: (data: TraceExporterData) => void;
 }
 export interface CoralogixOtelWebType extends SendLog {
     init: (options: CoralogixBrowserSdkConfig) => void;

package/src/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.11.0";
+export declare const SDK_VERSION = "2.12.0";