Browser Log Collection

@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

If you are not using a bundler, load it from the CDN instead and initialize window.ATATUS_LOGS with the same options:

<script crossorigin src="https://js-cdn.atatus.io/atatus-browser-agent/latest/atatus-logs.js"></script>

Initialize it once, alongside your RUM setup:

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

atatusLogs.init({
  licenseKey: '<license-key>',
  appName: '<app-name>',
  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, site, serverUrl, sessionSampleRate, trackingConsent, and the session storage settings. See Configuration for those. Pass the same site you pass to atatusRum.init() so logs and RUM reach the same region.

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: '<app-name>',
  beforeSend: (log) => {
    if (log.view && log.view.url) {
      log.view.url = scrub(log.view.url);
    }
    return true;
  },
});

Next steps

Error Tracking: how errors are collected in RUM.
API Reference: the full logs API.