@atatus/browser-logs sends logs from the browser to Atatus. It collects console output and unhandled errors for you, and gives you a logger for your own structured messages. When RUM is running on the same page, logs share its session and user, so you can jump from a session to the logs it produced.

This page covers setup, options, and the logger API.

Install and initialize

Install the package:

$ npm install @atatus/browser-logs

Initialize it once, alongside your RUM setup:

import { atatusLogs } from '@atatus/browser-logs';

atatusLogs.init({
  licenseKey: '<license-key>',
  appName: 'Storefront',
  env: 'production',
  sessionSampleRate: 100,
  forwardErrorsToLogs: true,
  forwardConsoleLogs: 'all',
});

Options

These options are specific to logs:

Option Default Purpose
forwardErrorsToLogs true Send uncaught errors and rejections as logs
forwardConsoleLogs [] 'all', or a list such as ['error', 'warn']
forwardReports [] 'all', or Reporting API types such as CSP violations
beforeSend None Change or drop a log before it is sent

The shared options also apply here, including licenseKey, appName, env, version, service, serverUrl, sessionSampleRate, trackingConsent, and the session storage settings. See Configuration for those.

Note:

forwardConsoleLogs: 'all' captures every console call, including console.log. On a chatty application that can be a lot of volume. Start with ['error', 'warn'] and widen it if you need more.

Write logs

Use the default logger for most messages. Pass an object as the second argument to attach structured context:

atatusLogs.logger.info('Checkout started', { cartId, itemCount: 3 });
atatusLogs.logger.error('Payment declined', { code }, err);

The third argument is an Error, and the agent reads its stack trace.

Levels

Nine levels are available, in ascending order of severity:

ok, debug, info, notice, warn, error, critical, alert, emerg

Set a minimum level to drop anything below it:

atatusLogs.logger.setLevel('warn');

Scoped loggers

Create a named logger per area of your application, so you can filter by it later:

const checkout = atatusLogs.createLogger('checkout', { level: 'info' });

checkout.warn('Retrying payment', { attempt: 2 });

Retrieve it elsewhere by name:

const checkout = atatusLogs.getLogger('checkout');

Add context to every log

Global context is attached to every log the SDK sends:

atatusLogs.setGlobalContext({ deployment: 'canary' });
atatusLogs.setGlobalContextProperty('tenantRegion', 'eu');

To attribute logs to a person or account, set the user and account, exactly as you do for RUM:

atatusLogs.setUser({ id: user.id, name: user.fullName, email: user.email });
atatusLogs.setAccount({ id: account.id, name: account.name });

Redact before sending

beforeSend runs on each log just before it is sent. Return false to drop it:

atatusLogs.init({
  licenseKey: '<license-key>',
  appName: 'Storefront',
  beforeSend: (log) => {
    if (log.view && log.view.url) {
      log.view.url = scrub(log.view.url);
    }
    return true;
  },
});

Next steps