Table of Contents
JavaScript / TypeScript Frameworks: React, Angular, Vue, NextJS and more.
Flutter (Currently only web).
To use Coralogix SDK for Browsers, call CoralogixRum.init(options) at the soonest available moment after the page load.
This will initialize the SDK based on the options you provided.
import { CoralogixRum } from '@coralogix/browser';
CoralogixRum.init({
application: 'app-name',
environment: 'production',
public_key: 'abc-123-456',
coralogixDomain: 'EU2',
version: 'v1.0.3',
labels: {
payment: 'visa',
},
sessionConfig: {
sessionSampleRate: 100, // Percentage of overall sessions being tracked, defaults to 100%
},
});To provide contextual information or transmit manual logs, utilize the exported functions of CoralogixRum.
Keep in mind that these functions will remain inactive until you've invoked CoralogixRum.init().
import { CoralogixRum } from '@coralogix/browser';
// Update user context dynamically
CoralogixRum.setUserContext({
user_id: '123',
user_name: 'name',
user_email: 'user@email.com',
user_metadata: {
role: 'admin',
// ...
},
});
// Update custom labels dynamically
CoralogixRum.setLabels({
...CoralogixRum.getLabels(),
paymentMethod: 'visa',
userTheme: 'dark',
// ...
});
// Update application context dynamically
CoralogixRum.setApplicationContext({
application: 'app-name',
version: '1.0.0',
});CoralogixRum.init({
// ...
sessionConfig: {
sessionSampleRate: 50, // Percentage of overall sessions being tracked, defaults to 100%
},
});This configuration will ensure all sessions with errors are tracked, and a percentage of sessions without errors are also tracked.
CoralogixRum.init({
// ...
sessionConfig: {
sessionSampleRate: 50,
alwaysTrackSessionsWithErrors: true,
},
});Track only sessions with errors, and send specific instrumentation data immediately even if error is not occurred. From Session recording perspective, the SDK will record approximately 10–60s(according to maxRecordTime property) before the error occurred.
CoralogixRum.init({
// ...
sessionConfig: {
onlyWithErrorConfig: {
enable: true, // Whether to track only sessions with errors, defaults to false
maxRumEvents: 5000, // Maximum number of cached RUM events to store in cache up until error is coming, defaults to 5000, max 20000
maxRecordTime: 10_000, // Maximum time in milliseconds to store last record events in cache before error occurred, defaults to 10000(10s), max 60000(1m)
/**
* Specifies the instrumentation data to be sent for sessions with errors, defaulting to web-vitals only.
* The instrumentation data will only be sent if it is enabled in the main configuration.
* This data will be sent immediately, even if no error has occurred.
*/
instrumentationsToSend: {
[CoralogixEventType.WEB_VITALS]: true,
// more instrumentation's can be added
// [CoralogixEventType.LONG_TASK]: true,
//...
},
},
},
});import { CoralogixRum, CoralogixLogSeverity } from '@coralogix/browser';
// send custom logs with different severity levels
CoralogixRum.log(CoralogixLogSeverity.Info, 'this is a custom log');
// send custom logs with extra data
CoralogixRum.log(CoralogixLogSeverity.Error, 'this is an error custom log with extra data', { data: 'tbd' });
// send custom logs with extra data, call the error severity log directly
CoralogixRum.error('this is a custom log with error severity', { data: 'tbd' });
// send custom logs with extra data and labels
CoralogixRum.warning(
'this is a custom log message with warning severity',
{
data: 'tbd',
},
{
my_label_key: 'my label value',
}
);
// data is optional unless labels are provided, in which case data is required (can be null
CoralogixRum.log(CoralogixLogSeverity.Info, 'this is a custom log message with info severity', null, {
my_label_key: 'my label value',
});Turn on/off specific instrumentation, default to all trues. Each instrumentation is responsible for which data the SDK will track and collect for you.
CoralogixRum.init({
// ...
instrumentations: {
xhr: true,
fetch: true,
web_vitals: false,
interactions: false,
custom: true,
errors: true,
long_tasks: true,
resources: false,
},
});You can pass an Error object to capture it as an event.
Additionally, you can include custom data and labels with the event.
try {
// Some code that might throw an error
} catch (error) {
CoralogixRum.captureError(error);
CoralogixRum.captureError(error, { custom_data: { id: '123' } }); // add custom data
CoralogixRum.captureError(error, { custom_data: { id: '123' } }, { label1: 'value1' }); // add custom data and labels
}Session Recording enhances your user experience monitoring by enabling you to record and visually replay the web browsing activities of your users.
CoralogixRum.init({
// ...
sessionRecordingConfig: {
enable: true, // Must declare.
/**
* If autoStartSessionRecording is false, you can manually start & stop your session recording.
* Refer to Recording Manually Section.
**/
autoStartSessionRecording: true, // Automatically records your session when SDK is up.
recordConsoleEvents: true, // Will record all console events from dev tools. Levels: log, debug, warn, error, info, table etc..
sessionRecordingSampleRate: 100, // Percentage of overall sessions recording being tracked, defaults to 100% and applied after the overall sessionSampleRate.
},
});You can always start/stop your session recording manually as follows:
// To start manually the Session Recording
CoralogixRum.startSessionRecording();
// To stop the Session Recording
CoralogixRum.stopSessionRecording();To protect your users’ privacy and sensitive information, elements containing certain class names are blocked or masked in recordings, as follows:
CoralogixRum.init({
// ...
sessionRecordingConfig: {
// ..
blockClass: 'rr-block', // Use a string or RegExp to redact all elements that contain this class, defaults to rr-block.
ignoreClass: 'rr-ignore', // Use a string or RegExp to Ignore all events that contain this class, defaults to rr-ignore.
maskTextClass: 'rr-mask', // Use a string or RegExp to mask all elements that contain this class, defaults to rr-mask.
maskAllInputs: false, // Mask all input content as * (Default false), refer to Input types.
maskInputOptions: { password: true }, // Mask some kinds of input as *, By Default the SDK masking password inputs.
},
});Example:
<div class="rr-block">Dont record me</div>| Element | Action |
|---|---|
| .rr-block | An element with the class name .rr-block will not be recorded. Instead, it will replay as a placeholder with the same dimension. |
| .rr-ignore | An element with the class name .rr-ignore will not record its input events |
| .rr-mask | All text of elements and their children will be masked. |
If you want to mask all of your inputs and texts in the session, you can use the following configuration:
CoralogixRum.init({
// ...
sessionRecordingConfig: {
// ...
maskAllInputs: true,
maskTextSelector: '*',
},
});Session Recording works by recording incremental DOM changes that occur in your web application. To avoid performance issues, Session Recording will stop recording if it detects a large number of mutations (Default: 5,000).
CoralogixRum.init({
// ...
sessionRecordingConfig: {
// ...
// According to MutationObserver API, A large number of DOM mutations can negatively impact performance
maxMutations: 5000,
},
});By default, Session recording uses an inline web worker script to compress data before transmission. For added flexibility, you can host a custom worker script on your own domain. Simply host the following file on your server: worker.min.js
For a locally hosted worker file:
CoralogixRum.init({
// ...
sessionRecordingConfig: {
// ...
workerUrl: '/assets/worker.min.js',
},
});For an externally hosted worker file:
CoralogixRum.init({
// ...
sessionRecordingConfig: {
// ...
workerUrl: 'https://cdn.rum-ingress-coralogix.com/coralogix/browser/latest/worker.min.js',
},
});Screenshot is a feature that allows you to capture a screenshot of the user's screen at the time of an error or based on specific custom logic triggers.
Note that the Screenshot feature is a subset of session recording and shares the same configurations, including options like masking, sample rate and others.
sessionRecordingConfig must be enabled to use this feature.
CoralogixRum.init({
// ...
sessionRecordingConfig: {
enable: true,
// ...
},
});Capture a screenshot manually:
CoralogixRum.screenshot();
// or with a description
CoralogixRum.screenshot('Screenshot after the user logged in');Capture a screen automatically based on custom logic, using the beforeSend
CoralogixRum.init({
// ...
beforeSend: (event) => {
// ...
// automatically take a screenshot when an error occurs and append the screenshot id to the event
if (event.event_context.type === 'error' && event.session_context.user_name === 'CEO') {
const id = CoralogixRum.screenshot('creating a screenshot due to an error!');
event.screenshotId = id;
}
return event;
},
});The networkExtraConfig property is an array of configuration objects, each specifying custom rules for capturing network requests and responses. This feature collects data from Fetch and XMLHttpRequest calls, attaching specified request and response information, headers, and payloads to each network event.
CoralogixRum.init({
networkExtraConfig: [
{
url: 'http://example.com', // Capture requests to this specific URL or regex pattern
reqHeaders: ['Authorization', 'Content-Type'], // Capture 'Authorization' and 'Content-Type' headers in requests
resHeaders: ['Cache-Control', 'Date'], // Capture 'Cache-Control' and 'Date' headers in responses
collectReqPayload: true, // Collect request payload
collectResPayload: false, // Do not collect response payload
},
],
});The server must explicitly permit access to specific headers by listing them in the Access-Control-Expose-Headers response header. Due to restrictions in the Fetch and XHR APIs, header retrieval operates on a best-effort basis, meaning that some headers may occasionally be unavailable in the events collected by this integration. Additionally, any large payloads exceeding the allowed size will be dropped.
If your application is not a single page application (SPA), you can initialize the SDK with a configuration to retain the session ID after a reload/refresh. This will prevent multiple sessions from being created when the user navigates within the app.
CoralogixRum.init({
// ...
sessionConfig: {
// ...
keepSessionAfterReload: true,
},
});The ignoreErrors option allows you to exclude errors that meet specific criteria. This options accepts a set of strings and regular expressions to match against the event's error message. Use regular expressions for exact matching as strings remove partial matches.
import { CoralogixRum } from '@coralogix/browser';
CoralogixRum.init({
// ...
ignoreErrors: [/Exact Match Error Message/, 'partial/match'],
});The ignoreUrls option allows you to exclude network requests that meet specific criteria. This options accepts a set of strings and regular expressions to match against the event's network url. Use regular expressions for exact matching as strings remove partial matches.
import { CoralogixRum } from '@coralogix/browser';
CoralogixRum.init({
// ...
ignoreUrls: [/.*\.svg/, /.*\.ico/], // will ignore all requests to .svg and .ico files
});User interactions capture text from clickable elements only (button, label, link, input, option).
Elements text can be masked to prevent sensitive data exposure.
use maskInputTypes to specify the types of inputs to mask. defaults to: ['password', 'email', 'tel']
use maskClass to specify the class name that will be used to mask any clickable element. Default masking class is cx-mask.
CoralogixRum.init({
// ...
maskInputTypes: ['password', 'date'], // will only mask password and date inputs
maskClass: 'mask-me', // will mask any clickable element with class 'mask-me'
});Examples of masked elements:
<button class="cx-mask">
<span>Some Text</span>
</button>
<button>
<span class="cx-mask">Some Text</span>
</button>
<my-button-component class="cx-mask">
<button>Text</button>
</my-button-component>Provide labels based on url or event
import { CoralogixRum } from '@coralogix/browser';
const featurePageUrlLabelProvider = new UrlBasedLabelProvider({
urlType: UrlType.PAGE,
urlPatterns: [
{
regexps: [/apm/],
labels: { featureGroupId: 'apm' },
},
],
defaultLabels: {
featureGroupId: 'unknown-feature-group',
},
});
const regularExpErrorLabelProvider: GenericLabelProvider = {
providerFunc: (url, event) => {
if (event.error_context?.error_message?.includes('Invalid regular expression')) {
return {
regular_expression_error: 'true',
};
}
return {};
},
};
CoralogixRum.init({
// ...
labelProviders: [featurePageUrlLabelProvider, regularExpErrorLabelProvider],
});Modify the event's page or network url based on custom-defined functions.
import { CoralogixRum } from '@coralogix/browser';
CoralogixRum.init({
// ...
urlBlueprinters: {
pageUrlBlueprinters: [
(url) => {
const hostnameParts = new URL(url).hostname.split('.');
hostnameParts[0] = '{team-id}';
return 'https://' + hostnameParts.join('.');
// "https://alpha.company.com" => "https://{team-id}.company.com"
},
],
networkUrlBlueprinters: [(url) => url.replace('api/v1', '{server}')],
// "https://path/api/v1/logs" => "https://path/{server}/logs"
},
});Add trace context propagation in headers across service boundaries
CoralogixRum.init({
// ...
traceParentInHeader: {
enabled: true,
},
});When the backend domain is different from the app domain, specifying backend domains is necessary.
For example, if the app is hosted on https://app.com and the backend is hosted on https://webapi.com, you should specify the backend domain.
CoralogixRum.init({
// ...
traceParentInHeader: {
enabled: true,
options: {
propagateTraceHeaderCorsUrls: [new RegExp('https://webapi.*')],
},
},
});Specify the allowed URLs to propagate the trace header.
Note that if allowedTracingUrls is not specified, the trace header will be propagated to all URLs.
allowedTracingUrls works only on 1st party URLs. (see propagateTraceHeaderCorsUrls for 3d party URLs)
For example if you want to propagate the trace header only for URLs that contain the word alpha:
CoralogixRum.init({
// ...
traceParentInHeader: {
enabled: true,
options: {
allowedTracingUrls: [new RegExp('alpha')],
},
},
});CoralogixRum.init({
// ...
traceParentInHeader: {
enabled: true,
options: {
// ...
/* for B3 propagation */
propagateB3TraceHeader: {
singleHeader: true,
multiHeader: true,
},
/* for Aws propagation */
propagateAwsXrayTraceHeader: true,
},
},
});Enable event access and modification before sending to Coralogix, supporting content modification, and event discarding.
CoralogixRum.init({
// ...
beforeSend: (event) => {
// Discard events from @company.com users.
if (event.session_context.user_email?.endsWith('@company.com')) {
return null;
}
// Redact sensitive information from the page URL.
event.page_context.page_url = event.page_context.page_url.replace('sensitive-info', 'redacted');
return event;
},
});Proxy configuration to route requests.
By specifying a proxy URL, all RUM data will be directed to this URL via the POST method.
However, it is necessary for this data to be subsequently relayed from the proxy to Coralogix.
The Coralogix route for each request that is sent to the proxy is available in the request’s cxforward parameter
(for example, https://www.your-proxy.com/endpoint?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Fv1beta%2Flogs).
CoralogixRum.init({
// ...
coralogixDomain: 'EU1',
proxyUrl: 'https://www.your-proxy.com/endpoint',
});Determines whether the SDK should collect the user's IP address and corresponding geolocation data. Defaults to true.
CoralogixRum.init({
// ...
collectIPData: true,
});Custom measurement allows you to send numeric data to Coralogix for precise monitoring and analysis.
CoralogixRum.sendCustomMeasurement('my-page-load', 1000);Add timing is a simple API to add extra performance timing to your RUM data.
The timing relates to the time between the page load and the moment the timing is added.
For example, you can add a timing for the first click event.
window.addEventListener('click', function handler() {
window.removeEventListener('click', handler);
CoralogixRum.addTiming('first-click');
});OR
You can provide your own timing.
window.addEventListener('click', function handler() {
window.removeEventListener('click', handler);
CoralogixRum.addTiming('first-click', 1000);
});Custom time measurement allows you to track the time between two points by starting a timer with startTimeMeasure and stopping it with endTimeMeasure, using a unique name to identify each measurement. Labels can be added at the start for additional context.
CoralogixRum.startTimeMeasure('login', {
paymentMethod: 'visa',
userTheme: 'dark',
});CoralogixRum.endTimeMeasure('login');This feature allows you to track multiple applications on the same page.
Only errors with stacktrace are supported.
To support microfrontend, you need to install one of these plugins: webpack, esbuild and include them in your build process.
Plugins for other bundlers are coming soon.
When an error occurs, the SDK will find the correlated microfrontend and will add a label with the microfrontend app/version to the error event.
CoralogixRum.init({
// ...
supportMfe: true,
});Create your own custom spans to track specific operations in your application.
Each span will share the same trace ID, which will allow you to create flows in your application and see them in the Tracing view.
Labels can be added during span creation for additional context.
const customTracer = CoralogixRum.getCustomTracer();
const globalSpan = customTracer.startGlobalSpan('global-span', { page: 'posts' });
globalSpan.withContext(() => {
const customSpan = globalSpan.startCustomSpan('custom-span', { action: 'scroll' });
customSpan.endSpan();
});
// note: End the global span only after the operation is complete.
globalSpan.endSpan();After creating a global span, some of the instrumented events (network, errors, interactions) will automatically share the same trace ID, unless specifically ignored.
const customTracer = CoralogixRum.getCustomTracer({
ignoredInstruments: [CoralogixEventType.NETWORK_REQUEST, CoralogixEventType.ERROR, CoralogixEventType.USER_INTERACTION],
});
// ... your codeSoft navigations are navigations that do not trigger a full page reload, such as SPA navigations. Defaults to false. With this option enabled, the SDK will track soft navigations and Partial Web vitals metrics such as (TTFB, FCP, LCP, CLS, INP).
** This feature requires enabling the feature flag(#enable-experimental-web-platform-features) in the browser. **
CoralogixRum.init({
// ...
trackSoftNavigations: false,
});Memory usage is a feature that allows you to track the memory usage of your application. It uses the measureUserAgentSpecificMemory API.
The SDK will collect memory usage data every interval and send it to Coralogix.
To enable the feature, your website needs to be in a secure context.
CoralogixRum.init({
// ...
memoryUsageConfig: {
enabled: true,
interval: 300_000, // Defaults to 5 minutes
},
});You can also manually trigger memory usage data collection.
CoralogixRum.measureUserAgentSpecificMemory();Coralogix Browser SDK is also provided via CDN.
You can choose your desired version.
https://cdn.rum-ingress-coralogix.com/coralogix/browser/[version]/coralogix-browser-sdk.js
Replace [version] with a version from Releases page.
Note: CDN latest has no longer maintained, please use an explicit version instead.
<head>
...
<script src="https://cdn.rum-ingress-coralogix.com/coralogix/browser/[version]/coralogix-browser-sdk.js"></script>
</head>window.CoralogixRum.init(...);window.CoralogixRum.init(...);
// In case of warning from TSC
declare global {
interface Window {
CoralogixRum: CoralogixOtelWebType;
}
}Coralogix Browser SDK is also provided for Flutter web.
Add the following CDN to your index.html file:
<script src="https://cdn.rum-ingress-coralogix.com/coralogix/browser/[version]/coralogix-browser-sdk.js"></script>Then, in your Dart code, you can use the SDK as follows:
import 'package:flutter/material.dart';
import 'dart:js' as js;
void main() {
runApp(const MyApp());
var rum = js.JsObject.fromBrowserObject(js.context['CoralogixRum']);
rum.callMethod('init', [js.JsObject.jsify({
environment: 'test',
application: 'my-app',
version: '1.0.0',
public_key: 'my-key-123',
coralogixDomain: 'EU2',
})]);
}