@coralogix/browser 3.23.2 → 3.23.3

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.23.3 (2026-08-30)
+
+### 🩹 Fixes
+
+- Stop the INP (Interaction to Next Paint) reporter throwing an uncaught `TypeError` after a back/forward navigation followed by a tab switch
+
 ## 3.23.2 (2026-08-20)
 
 ### 🩹 Fixes

package/README.md

@@ -255,6 +255,23 @@ CoralogixRum.log(CoralogixLogSeverity.Info, 'this is a custom log message with i
 });
 ```
 
+#### Stringifying custom log data
+
+By default the `data` you pass to a custom log is sent as a nested structure. Set
+`stringifyCustomLogData` at initialization to send it as a string instead, which is
+useful when `data` holds nested objects or arrays. Circular references are handled
+rather than throwing.
+
+```javascript
+CoralogixRum.init({
+  // ...
+  stringifyCustomLogData: true,
+});
+```
+
+The SDK reads this option once, when it initializes, so it applies to every custom
+log from that point on and cannot be changed per call.
+
 ### Instrumentation's
 
 Turn on/off specific instrumentation, default to all trues.
@@ -276,6 +293,11 @@ CoralogixRum.init({
 });
 ```
 
+> [!NOTE]
+> The `fetch` and `xhr` instrumentations also add the trace context headers to outgoing requests.
+> Turning both off stops trace context propagation as well, even when `traceParentInHeader` is
+> enabled.
+
 ##### Web Vitals: TBT metric
 
 By default, the **TBT** (Total Blocking Time) metric is disabled.
@@ -693,6 +715,11 @@ CoralogixRum.init({
 });
 ```
 
+> [!NOTE]
+> Trace headers are added by the `fetch` and `xhr` instrumentations, so this feature depends on them.
+> If you set both `instrumentations.fetch` and `instrumentations.xhr` to `false`, no trace headers are
+> sent even with `enabled: true`.
+
 #### propagateTraceHeaderCorsUrls
 
 When the backend domain is different from the app domain, specifying backend domains is necessary. <br>
@@ -983,6 +1010,13 @@ CoralogixRum.startTimeMeasure('login', {
 CoralogixRum.endTimeMeasure('login');
 ```
 
+A few behaviours worth knowing:
+
+- Starting a key while a measurement for it is still in progress does nothing, and neither does a blank key: `startTimeMeasure` returns and the running timer is left alone.
+- `endTimeMeasure` takes only the key, so there is no way to pass labels at the end. The object handed to `startTimeMeasure` is held by reference, and at the end it is merged over the SDK's global labels as they stand then - so a later `CoralogixRum.setLabels()` does affect the result.
+- Ending a measurement releases its key, so the same key can be measured again afterwards.
+- Open measurements are dropped the next time you start or end one while the session is idle. The check runs on those calls rather than on a timer, and activity clears the idle flag, so a measurement spanning a short idle gap may still report.
+
 ### Microfrontend support
 
 This feature allows you to track multiple applications on the same page.<br>
@@ -1039,15 +1073,57 @@ const customTracer = CoralogixRum.getCustomTracer({
 // ... your code
 ```
 
+#### When getCustomTracer returns nothing
+
+`getCustomTracer` returns `undefined` rather than throwing, so a missing prerequisite
+shows up as a `TypeError` on the next line instead. It returns nothing when:
+
+- the SDK has not been initialized yet
+- `traceParentInHeader` is not enabled - custom spans need it, and only a debug-level
+  message says so
+- a custom tracer already exists, which logs `Custom tracer already exists`
+
+`startGlobalSpan` behaves the same way: with a global span already open it warns
+`Global span already exists` and returns `undefined`, rather than replacing it.
+
+A few more things worth knowing:
+
+- Every span must be ended explicitly. `endSpan` ends the span and releases it, so a
+  new global span can be started afterwards.
+- Labels are applied to the span they are passed with. A child span created by
+  `startCustomSpan` does not inherit the global span's labels.
+- Open global spans are ended for you when the session resets, which happens after an
+  hour of session time or 15 minutes of inactivity.
+
 ### Traces Exporter
 
 The `tracesExporter` callback gives you full control over how collected trace events are handled.  
 It receives a `TraceExporterData` object containing all trace data that the SDK has collected.
 
+Setting it redirects your traces rather than copying them. The span data is removed from
+what the SDK sends to Coralogix and delivered to your callback instead, so Coralogix stops
+receiving traces until you forward them yourself from inside the callback.
+
+This happens per batch, and only for batches that carry OpenTelemetry span data. When
+one does, the strip applies to every log in it, not only to custom spans: views, errors
+and network events still reach Coralogix as RUM events, but without their
+`instrumentation_data`, the field holding request and response span detail. A batch with
+no span data at all is sent unchanged and your callback is not called for it.
+
+Treat the payload as a subset rather than a mirror. A span missing its trace id, span id,
+name or timestamps is dropped from the conversion, as is one whose timestamps fall
+outside the accepted window - more than an hour ahead or a day behind. Those spans can
+still reach Coralogix inside the RUM payload without a matching entry in what your
+callback receives, so `resource_spans` can be shorter than you expect, or empty.
+
+> [!WARNING]
+> The callback runs inline on the path that sends the RUM payload, and it is not wrapped.
+> An exception escaping your callback also stops that batch reaching Coralogix, so keep
+> your own work inside a `try`/`catch`.
+
 ```ts
 CoralogixRum.init({
   tracesExporter: (data: TraceExporterData) => {
-    // Example: forward traces to your own backend endpoint
     fetch('https://api.mycompany.com/rum-traces', {
       method: 'POST',
       headers: {
@@ -1138,8 +1214,14 @@ CoralogixRum.init({
 const worker = new Worker('my-worker.js');
 ```
 
+The SDK also attaches a `CoralogixRum` handle to the worker object it returns, as a
+convenience for logging next to the code that created the worker. It is an alias to the
+same SDK instance, not a per-worker one, so it adds no worker attribution of its own -
+`worker.CoralogixRum.log(...)` and `CoralogixRum.log(...)` do the same thing. Pass a
+label yourself if you need to tell workers apart.
+
 ```javascript
-// Worker code
+// App code, on the main thread
 
 // Log a basic info log
 worker.CoralogixRum.log(CoralogixLogSeverity.Info, 'Test log from worker');
@@ -1151,12 +1233,17 @@ try {
   worker.CoralogixRum.captureError(error, { worker: 'analytics-worker' }, { label1: 'value1' });
 }
 
-// Log messages received in the worker
-self.onmessage = (message) => {
-  worker.CoralogixRum.log(CoralogixLogSeverity.Info, message);
+// Log messages the worker sends back
+worker.onmessage = (message) => {
+  worker.CoralogixRum.log(CoralogixLogSeverity.Info, 'worker message', { data: message.data });
 };
 ```
 
+> [!NOTE]
+> `worker.CoralogixRum` lives on the worker object in the page, not inside the worker
+> script. Worker scope has no Coralogix global, so these calls only work on the main
+> thread.
+
 ## Angular Zone.js Configuration
 
 By default, the SDK runs its internal timers outside Angular's Zone.js to prevent unnecessary change detection cycles. This improves performance by avoiding redundant UI updates triggered by the SDK's background operations.
@@ -1194,7 +1281,8 @@ If you are targeting legacy environments, make sure to use the ES5-compatible ve
 
 https://cdn.rum-ingress-coralogix.com/coralogix/browser/[version]/coralogix-browser-sdk.es5.js
 
-> _**Note: CDN latest has no longer maintained, please use an explicit version instead.**_
+> [!NOTE]
+> The CDN `latest` tag is no longer maintained. Use an explicit version instead.
 
 ### Add the CDN script to your application
 

package/index.esm.js

@@ -7,6 +7,7 @@ import 'error-stack-parser';
 import '@opentelemetry/instrumentation-fetch';
 import '@opentelemetry/instrumentation-xml-http-request';
 import 'web-vitals/attribution';
+import 'web-vitals';
 import '@opentelemetry/api';
 import '@opentelemetry/propagator-b3';
 import '@opentelemetry/propagator-aws-xray';

package/index.esm2.js

@@ -5,7 +5,8 @@ import { InstrumentationBase, registerInstrumentations } from '@opentelemetry/in
 import ErrorStackParser from 'error-stack-parser';
 import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
 import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
-import { onFID, onCLS, onLCP, onFCP, onINP, onTTFB } from 'web-vitals/attribution';
+import { onFID, onCLS, onLCP, onFCP, onTTFB } from 'web-vitals/attribution';
+import { onINP } from 'web-vitals';
 import { createContextKey, baggageEntryMetadataFromString, propagation, diag, trace, isSpanContextValid, TraceFlags, context } from '@opentelemetry/api';
 import { B3Propagator, B3InjectEncoding } from '@opentelemetry/propagator-b3';
 import { AWSXRayPropagator } from '@opentelemetry/propagator-aws-xray';
@@ -1442,7 +1443,7 @@ var attributionSanitizers = {
         return __assign(__assign({}, rest), { attribution: sanitizedAttribution });
     },
     INP: function (metric) {
-        metric.entries; metric.attribution; var rest = __rest(metric, ["entries", "attribution"]);
+        metric.entries; var rest = __rest(metric, ["entries"]);
         return rest;
     },
 };
@@ -1831,6 +1832,9 @@ function isPerformanceObserverSupported() {
 }
 
 function sanitizeAttribution(metric) {
+    if (metric.name === 'INP') {
+        return attributionSanitizers.INP(metric);
+    }
     if (!('attribution' in metric)) {
         metric.entries; var rest = __rest(metric, ["entries"]);
         return rest;
@@ -1846,8 +1850,6 @@ function sanitizeAttribution(metric) {
             return attributionSanitizers.FID(metric);
         case 'TTFB':
             return attributionSanitizers.TTFB(metric);
-        case 'INP':
-            return attributionSanitizers.INP(metric);
     }
 }
 var CoralogixWebVitalsInstrumentation = (function (_super) {
@@ -1856,6 +1858,13 @@ var CoralogixWebVitalsInstrumentation = (function (_super) {
         var _this = _super.call(this, WEB_VITALS_INSTRUMENTATION_NAME, WEB_VITALS_INSTRUMENTATION_VERSION, config) || this;
         _this.observers = [];
         _this.isSoftNavsEnabled = getSdkConfig().trackSoftNavigations;
+        _this.onReportInp = function (metric) {
+            var _a;
+            if (!((_a = metric === null || metric === void 0 ? void 0 : metric.entries) === null || _a === void 0 ? void 0 : _a.length)) {
+                return;
+            }
+            _this.onReport(metric);
+        };
         _this.onReport = function (metric) {
             if (!metric) {
                 return;
@@ -1900,7 +1909,7 @@ var CoralogixWebVitalsInstrumentation = (function (_super) {
             onFCP(this.onReport, { reportSoftNavs: shouldReportSoftNavs });
         }
         if (this.metrics.inp) {
-            onINP(this.onReport, { reportSoftNavs: shouldReportSoftNavs });
+            onINP(this.onReportInp, { reportSoftNavs: shouldReportSoftNavs });
         }
         if (this.metrics.ttfb) {
             onTTFB(this.onReport, { reportSoftNavs: shouldReportSoftNavs });
@@ -5206,7 +5215,7 @@ function resolveUrlBlueprinters(urlBlueprinters) {
     return resolvedUrlBlueprinters;
 }
 
-var SDK_VERSION = '3.23.2';
+var SDK_VERSION = '3.23.3';
 
 function shouldDropEvent(cxRumEvent, options) {
     if (isDocumentErrorWithoutMessage(cxRumEvent)) {

package/package.json

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

package/sessionRecorder.esm.js

@@ -7,6 +7,7 @@ import 'error-stack-parser';
 import '@opentelemetry/instrumentation-fetch';
 import '@opentelemetry/instrumentation-xml-http-request';
 import 'web-vitals/attribution';
+import 'web-vitals';
 import '@opentelemetry/api';
 import '@opentelemetry/propagator-b3';
 import '@opentelemetry/propagator-aws-xray';

package/src/instrumentations/web-vitals/CoralogixWebVitalsInstrumentation.d.ts

@@ -8,6 +8,7 @@ export declare class CoralogixWebVitalsInstrumentation extends InstrumentationBa
     private registerToCoreWebVitalMetrics;
     private registerToSoftNavigations;
     private registerToCalculatedWebVitalMetrics;
+    private onReportInp;
     private onReport;
     private registerToTBTMetric;
     private calculateLoadingPageTime;

package/src/instrumentations/web-vitals/web-vitals.types.d.ts

@@ -1,4 +1,5 @@
-import { CLSMetricWithAttribution, FCPMetricWithAttribution, FIDMetricWithAttribution, INPMetricWithAttribution, LCPMetricWithAttribution, Metric, TTFBMetricWithAttribution } from 'web-vitals/attribution';
+import { CLSMetricWithAttribution, FCPMetricWithAttribution, FIDMetricWithAttribution, INPMetricWithAttribution, LCPMetricWithAttribution, Metric, MetricWithAttribution, TTFBMetricWithAttribution } from 'web-vitals/attribution';
+import { INPMetric } from 'web-vitals';
 import { WebVitalsRating } from '../../types';
 export type CustomMetric = {
     name: 'SN' | 'LT' | 'TBT' | 'TTI';
@@ -36,7 +37,7 @@ type SanitizedFIDMetric = Omit<FIDMetricWithAttribution, 'entries' | 'attributio
 export type SanitizedTTFBMetric = Omit<TTFBMetricWithAttribution, 'entries' | 'attribution'> & {
     attribution: Omit<TTFBAttribution, 'navigationEntry'>;
 };
-type SanitizedINPMetric = Omit<INPMetricWithAttribution, 'entries' | 'attribution'>;
+type SanitizedINPMetric = Omit<INPMetric, 'entries'>;
 export type SanitizedMetric = SanitizedLCPMetric | SanitizedFCPMetric | SanitizedCLSMetric | SanitizedFIDMetric | SanitizedTTFBMetric | SanitizedINPMetric | CustomMetric;
 export type SanitizerMap = {
     LCP: (m: LCPMetricWithAttribution) => SanitizedLCPMetric;
@@ -44,8 +45,9 @@ export type SanitizerMap = {
     CLS: (m: CLSMetricWithAttribution) => SanitizedCLSMetric;
     FID: (m: FIDMetricWithAttribution) => SanitizedFIDMetric;
     TTFB: (m: TTFBMetricWithAttribution) => SanitizedTTFBMetric;
-    INP: (m: INPMetricWithAttribution) => SanitizedINPMetric;
+    INP: (m: INPMetric) => SanitizedINPMetric;
 };
+export type ReportedMetric = Exclude<MetricWithAttribution, INPMetricWithAttribution> | INPMetric | CustomMetric;
 export interface CoralogixWebVitalsMetrics {
     lcp: boolean;
     fid: boolean;

package/src/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "3.23.2";
+export declare const SDK_VERSION = "3.23.3";