Configuration and Method Reference

Configuration Reference

Configuration types

There are 2 types of configuration data -- context and payload. Context provides information about the environment of the error while payload describes information about the error itself.

Context

• Information about the environment of the error being sent to Rollbar
• e.g. server hostname, user's IP, custom fingerprint

Payload

• Information about the error -- usually custom
• e.g. The name of the javascript component that triggered the error

Configuration levels

Rollbar can be configured at 2 different levels -- global and notifier. All configuration is inherited at each level, so global configuration affects all notifiers while notifier configuration only affects the notifier being configured.

Global configuration

• Affects all notifiers
• Set by calling global() on any notifier
• Merges/updates previous configuration
• Currently, the only supported options are maxItems and itemsPerMinute

Notifier configuration - context and/or payload

• Affects only the notifier you call configure() on
• Merges/updates previous configuration for the notifier you call configure() on

Examples

Global

// Only send a max of 5 items to Rollbar per minute
Rollbar.global({itemsPerMinute: 5});

// Only send a maximum of 10 items to Rollbar per page load
Rollbar.global({maxItems: 10});

Notifier

// Set the top-level notifier's checkIgnore() function
Rollbar.configure({checkIgnore: function(isUncaught, args, payload) {
    // ignore all uncaught errors and all 'debug' items
    return isUncaught === true || payload.level === 'debug';
}});

// Set the onSendCallback() function
Rollbar.configure({onSendCallback: function(isUncaught, args, payload) {
    //do something
}});

// Set the environment, default log level and the context
Rollbar.configure({logLevel: 'info', payload: {environment: 'staging', context: 'home#index'}});
Rollbar.log('this will be sent with level="info"');

// Only send "error" or higher items to Rollbar
Rollbar.configure({reportLevel: 'error'});
Rollbar.info('this will not get reported to Rollbar since it\'s at the "info" level');

// Set the person information to be sent with all items to Rollbar
Rollbar.configure({payload: {person: {id: 12345, email: '[email protected]'}}});

// Add the following payload data to all items sent to Rollbar
// from this notifier
Rollbar.configure({payload: {sessionId: "asdf12345"}});

// Scrub any payload keys/query parameters named 'creditCardNumber'
Rollbar.configure({scrubFields: ['creditCardNumber']});

// Only allow items to be sent from certain domains
Rollbar.configure({hostSafeList: ['domain1.com', 'domain2.com']});

// Don't allow items to be sent from certain domains
Rollbar.configure({hostBlockList: ['domain1.com', 'domain2.com']});

// Set the uncaught error level to 'warning'
Rollbar.configure({uncaughtErrorLevel: 'warning'});

// Set the endpoint
Rollbar.configure({endpoint: 'https://api.rollbar.com/api/1/item'});

// Send the config
Rollbar.configure({sendConfig: true});

// Anonymize IP addresses
Rollbar.configure({captureIp: 'anonymize'});

// Capture uncaught exceptions and unhandled rejections
Rollbar.configure({captureUncaught: true, captureUnhandledRejections: true});

// Set the verbose option
Rollbar.configure({verbose: true});

// Enable automatic telemetry event collection with a max queue size of 50, and not including any input values in Telemetry events
Rollbar.configure({autoInstrument: true, maxTelemetryEvents: 50, scrubTelemetryInputs: true});

// Include previously logged items to Rollbar in the queue of telemetry events
Rollbar.configure({includeItemsInTelemetry: true});

For fine-grained control of the payload sent to the Rollbar API, you can override any keys by nesting them in the configuration under the payload key:

Rollbar.configure({payload: {fingerprint: "custom fingerprint to override grouping algorithm"}}).error(err);

For convenience, the configure method also accepts a second parameter of data to be automatically nested under the payload key, for example:

Rollbar.configure({enabled: true, payload: {somekey: 'somevalue'}}, {fingerprint: 'abc123'})

is equivalent to

Rollbar.configure({enabled: true, payload: {somekey: 'somevalue', fingerprint: 'abc123'}})

Moreover, the values in the second parameter take precedence over any which have a duplicate key nested under the payload key in the first parameter. For example,

Rollbar.configure(
  {
    enabled: true,
    payload: {
      a: 'b',
      somekey: 'somevalue'
    }
  },
  {
    somekey: 'other',
    fingerprint: 'abc123'
  }
)

is equivalent to

Rollbar.configure(
  {
    enabled: true,
    payload: {
      a: 'b',
      somekey: 'other',
      fingerprint: 'abc123'
    }
  }
)

Reference

Both global and context configuration have the following reserved key names that Rollbar uses to aggregate, notify and display.

Global

Context

Payload

These keys should all be within the payload key.

e.g.

Rollbar.configure({
  payload: {
    person: ...,
    context: ...
  }
});

Check out the method reference below for more information on how to use global/configure.

Method Reference

Rollbar.global()

(See the configuration reference above.)

Note: This method will update any existing global configuration.

Returns: undefined

Params

1. options: Object - A javascript object that contains global configuration.

Rollbar.configure()

(See the configuration reference above.)

Note: This method will update any existing configuration for the Rollbar instance used.

Returns: undefined

Params

1. options: Object - A javascript object that contains the notifier configuration.

Rollbar.handleUncaughtException()

This method is used to record uncaught exceptions from window.onerror. The Rollbar snippet will set window.onerror = Rollbar.uncaughtError if it was configured to do so via the captureUncaught config parameter given to the constructor of this Rollbar instance.

Returns: undefined

Params

1. message: String: The error message.
2. url: String: url that the error occurred on.
3. lineNo: Integer: The line number, (if known) that the error occurred on.
4. colNo: Integer: The column number that the error occurred on.
   Note: Only newer browsers provide this variable.
5. err: Exception: The exception that caused the window.onerror event to occur.
   Note: Only newer browsers provide this variable.

Rollbar.handleUnhandledRejection()

This method is used to record unhandled Promise rejections via the window event unhandledrejection. See the standard) for more information about when this is available.

To enable this handling, you should provide captureUnhandledRejections to the config given to this Rollbar constructor.

Returns: undefined

Params

1. message: Exception: The exception, or rejection being rejected.
2. promise: Promise: The originating promise object.

Rollbar.log()

Log a message and potentially send it to Rollbar. The level that the message or error is logged at is determined by the logLevel config option.

In order for the message to be sent to Rollbar, the log level must be greater than or equal to the reportLevel config option.

See the configuration reference above for more information on configuring log levels.

Returns: undefined

Params

Note: order does not matter, except that message and err arguments must come first if present. The first string will be interpreted as message, and the first Error type argument will be interpreted as err. At least one of message or err must be present.

• message: String - The message to send to Rollbar.
• err: Exception - The exception object to send.
• custom: Object - The custom payload data to send to Rollbar.
• callback: Function - The function to call once the message has been sent to Rollbar.

Examples

Log a debug message

// By default, the .log() method uses the
// "debug" log level and "warning" report level
// so this message will not be sent to Rollbar.
Rollbar.log("hello world!");

Log a warning along with custom data

Rollbar.configure({logLevel: "warning"});
Rollbar.log("Uh oh! The user pressed the wrong button.", {buttonId: "redButton"});

Log a debug message along with an error

try {
  foo();
} catch (e) {
  Rollbar.log("Caught an exception", e);
}

Log an error and call a function when the error is reported to Rollbar

Rollbar.configure({logLevel: "error"});

function continueFormSubmission() {
  // ...
}

try {
  foo();
  continueFormSubmission();
} catch (e) {
  Rollbar.log(e, continueFormSubmission);
}

Rollbar.debug/ info/ warn/ warning/ error/ critical()

These methods are all shorthand for Rollbar.log() with the appropriate log level set.

📘

For more information on rollbar.js, see the docs here.