Configuration and Method Reference

Configuration options for rollbar.js

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

OptionDescription
itemsPerMinuteMax number of items to report per minute. The limit counts uncaught errors (reported through window.onerror) and any direct calls to Rollbar.log/debug/info/warning/error/critical(). This is intended as a sanity check against infinite loops, but if you're using Rollbar heavily for logging, you may want to increase this.

If you would like to remove this limit, set it to undefined.

Default: 60
maxItemsMax number of items to report per page load. When this limit is reached, an additional item will be reported stating that the limit was reached. Like itemsPerMinute, this limit counts uncaught errors (reported through window.onerror) and any direct calls to Rollbar.log/debug/info/warning/error/critical().

Default: 0 (no limit)

Context

OptionDescription
accessTokenSets the access token used to send payloads to Rollbar.

Items sent through a given access token arrive in that access token's project and respect the rate limits set on that access token.
addErrorContextEnables adding error context to the payload. For exception payloads, the error context will be read from error.rollbarContext.

Default: false
autoInstrumentAn object or boolean describing what events to automatically collect. If this value is false then we collect nothing, if it is true we collect everything, otherwise we do not collect events for the keys with a false value. The default structure for this object is:

json { network: true, log: true, dom: true, navigation: true, connectivity: true }
For more information on the possible structure of this object, please see here.
captureIpFor browser settings, this determines how we attempt to capture IP addresses from the client that submits items. For server settings, this determines how we capture IP addresses from requests.

Possible values are: true, false, or 'anonymize'.

If true then we will attempt to capture and store the full IP address of the client. If set to 'anonymize' we will do a semi-anonymization on the captured IP address by masking out the least significant bits. If set to false we will not attempt to capture any IP address.

Default: true
captureUsernameCapture the user's username
captureEmailCapture the user's email
captureLambdaTimoutsa configuration option that defaults to true and installs a watchdog to report potential timeouts one second before they occur based on the remaining time in the context. If you set this to false we will not install the timer. If you pass a second argument to lambdaHandler we will invoke that second argument as a function with the event, context, and callback with which the original function is called.
When captureLambdaTimeouts is set, the SDK sets a timer just a bit short of the timeout.

A Rollbar error is sent to report the Lambda timeout when that timer expires. This succeeds since the function hasn't been killed quite yet. One of the possible failure modes for Lambda functions is the event that they hit their timeout threshold. In that case, the Lambda is killed. Since that happens instantly, a Rollbar error can't be sent to report this failure. Additionally, it's possible to have false positives. When the error is sent, the timeout will likely occur, but it's also possible the function will complete.
captureUncaughtThis determines whether or not the client reports all uncaught exceptions to Rollbar by default.

Default: false
captureUnhandledRejectionsThis determines whether or not the client reports all uncaught rejections to Rollbar by default.

Default: false
checkIgnoreAn optional function that will be used to ignore uncaught exceptions based on its return value. The function signature should be: function checkIgnore(isUncaught, args, payload) { ... } and should return true if the error should be ignored.

Default: null

isUncaught: true if the error being reported is from the window.onerror hook.
args: The arguments to Rollbar.log/debug/info/warning/error/critical(). In the case of unhandled rejections, the last parameter is originating Promise.
* payload: The javascript object that is about to be sent to Rollbar. This matches the contents of the data key described here. This parameter is useful for advanced ignore functionality.
enabledIf set to false, no data will be sent to Rollbar for this notifier.

Note: callbacks for errors will not be called if this is set to false.

Default: true
endpointThe url to which items get POSTed. This is mostly relevant to our enterprise customers. You will, however, need this if you're proxying the requests through your own server, or you're an enterprise customer.

Default: 'https://api.rollbar.com/api/1/item'
exitOnUncaughtExceptionNode environment only. Exit the process after handling an uncaught exception. Requires captureUncaught to also be set.

Default: false
hostBlockListCheck payload frames for blocklisted URL patterns. This is an array of strings, each of which get compiled to a RegExp. If a file in the trace matches one of these URL patterns, the payload is ignored.
hostSafeListCheck payload frames for safelisted URL patterns. This is an array of strings, each of which get compiled to a RegExp. If a file in the trace matches one of these URL patterns, the payload is accepted. When you specify a domain, that will safelist all subdomains of that domain.
ignoreDuplicateErrorsWhen false, transmit all error events including consecutive duplicate errors. When true, only send the first error when identical consecutive errors are detected.

Default: true
includeItemsInTelemetryThis option determines if the client includes previously logged items to Rollbar in the queue of telemetry events. This includes both direct calls and indirect calls via uncaught exceptions.

Default: true in the browser and React Native targets, false for the server target.

* For more information on telemetry, please see here.
ignoredMessagesThe events that match the criteria of elements of the ignoredMessages array will not be transmitted.
This option applies for exception messages only.

This option is an array of strings and regex expressions

Example:
ignoredMessages: ['Exception message to ignore', /Cannot read properties of undefined/i]

Note the 2nd element in the array (the regex expression) is not a string. It does not have quotes.
localsNode.js only: Enables local variable capture with stack traces. For more information, see here.

Default: undefined
logLevelThe severity level used for calls to Rollbar.log(). One of "critical", "error", "warning", "info", "debug".

Default: "debug"
maxRetriesSets the per-payload maximum number of retries sending to the Rollbar API. Currently supported in browser only.

Default: undefined (No maximum is set)

See also: timeout, retryInterval
maxTelemetryEventsThis determines the size of the in-memory queue of telemetry events that gets built up over the lifecycle of a user interacting with your app. The size of the queue is fixed to be in the interval [0, 100], so while you can lower the size of the queue from 100, currently you can not increase the size of the queue beyond 100.

Default: 100

For more information on telemetry, please see here.
nodeSourceMapsThis setting when true enables source mapping in the application environment before sending the payload to Rollbar. (This is most often used for Typescript mapping.). When using this feature, source maps don't need to be uploaded to Rollbar.

Default: false
onSendCallbackAn optional function that will be called for every payload before it is sent to the API. The function signature is the same as that of the checkIgnore function, namely function onSendCallback(isUncaught, args, payload). The return value is ignored.

Default: null

isUncaught: true if the error being reported is from the window.onerror hook.
args: The arguments to Rollbar.log/debug/info/warning/error/critical(). In the case of unhandled rejections, the last parameter is originating Promise.
* payload: The javascript object that is about to be sent to Rollbar. This will contain all of the context and payload information for this notifier and error. This parameter is useful for advanced ignore functionality.
overwriteScrubFieldsIf this is true then only the fields set in your configured scrubFields array will be used for scrubbing. If this is false or not present, then the value set in scrubFields will be appended to the default list of fields.

Default: false
reportLevelUsed to filter out which messages will get reported to Rollbar. If set to "error", only "error" or higher serverity level items will be sent to Rollbar.

Default: "debug"
retryIntervalNumber of milliseconds between retries. If set, errors will be queued up in the event of a connection failure where we are unable to push the errors to Rollbar. Once a connection has been re-established, the queue will be flushed. If null, then connection failure will not be detected and errors will not be queued.

Default: null

See also: timeout, maxRetries
scrubFieldsA list containing names of keys/fields/query parameters to override the default scrubbing parameters. Scrubbed fields will be normalized to all * before being reported to Rollbar. This is useful for sensitive information that you do not want to send to Rollbar. e.g. User tokens

NOTE:
Setting scrubFields will append this value to the default set of fields. If you wish to overwrite the defaults, then make sure to set overwriteScrubFields to true.

Default scrubbed fields for servers: ["pw", "pass", "passwd", "password", "password_confirmation", "passwordConfirmation", "confirm_password", "confirmPassword", "secret", "secret_token", "secretToken", "secret_key", "secretKey", "api_key", "access_token", "accessToken", "authenticity_token", "oauth_token", "token", "user_session_secret", "request.session.csrf", "request.session._csrf", "request.params._csrf", "request.cookie", "request.cookies"]

Default scrubbed fields for browsers: ["pw", "pass", "passwd", "password", "secret", "confirm_password", "confirmPassword", "password_confirmation", "passwordConfirmation", "access_token", "accessToken", "secret_key", "secretKey", "secretToken", "cc-number", "card number", "cardnumber", "cardnum", "ccnum", "ccnumber", "cc num", "creditcardnumber", "credit card number", "newcreditcardnumber", "new credit card", "creditcardno", "credit card no", "card#", "card #", "cc-csc", "cvc2", "cvv2", "ccv2", "security code", "card verification", "name on credit card", "name on card", "nameoncard", "cardholder", "card holder", "name des karteninhabers", "card type", "cardtype", "cc type", "cctype", "payment type", "expiration date", "expirationdate", "expdate", "cc-exp"]
scrubPathsA list of exact paths to scrub in the payload. The scrub location is described using dot notation.

Example:
scrubPaths: ['request.query_string', 'client.javascript.plugins']

Default: undefined
scrubRequestBodyFor Node.js/server environment only. This flag is enabled by default and enables parsing of JSON request bodies and scrubbing specific keys within the parsed JSON. After scrubbing, the request is reserialized and the payload is updated at data.request. Disable this flag to prevent parsing and attempted scrubbing of the request.

Default: true
scrubTelemetryInputsThis is used for scrubbing telemetry-specific data related to inputs in the dom. If this is set to true then no input values will be included in the telemetry events.

Default: false

For more information on telemetry, please see here.
sendConfigInclude the configuration for Rollbar with each item sent to Rollbar. This can aid in debugging configuration issues.

Default: false
stackTraceLimitNode.js and some browsers, including Chrome and Safari, default to returning a maximum of 10 stack frames for any thrown Error. This option allows setting a larger maximum limit (e.g. 50).

Default: undefined (Uses the current default.)
timeoutSet the network timeout for Rollbar API requests in milliseconds. Currently supported in browser only.

Default: undefined (Does not set a timeout)

See also: maxRetries, retryInterval
transformOptional function to modify the payload before sending to Rollbar. For more information on this user defined function, please see here.

Default: null
transmitDetermines whether to send Rollbar events to the Rollbar API. When unset, events will be fully processed, but not sent.

Default: true
uncaughtErrorLevelThe severity level used when uncaught errors are reported to Rollbar.

Default: "error"
verboseThis determines whether or not the client also logs to console.log, in addition to sending the item to Rollbar.

Default: false
wrapGlobalEventHandlersIn the browser environment, Rollbar wraps many global event handlers in order to provide more detailed information when an error occurs in one of these handlers. Set this flag false to disable these wrappers.

Default: true

Payload

These keys should all be within the payload key.

e.g.

Rollbar.configure({
  payload: {
    person: ...,
    context: ...
  }
});
OptionDescription
personAn object identifying the logged-in user, containing an id (required), and optionally a username and email (all strings). Passing this will allow you to see which users were affected by particular errors, as well as all the errors that a particular user experienced.
contextName of the page context -- i.e. route name, url, etc. Can be used in the Rollbar interface to search for items by context prefix.
clientAn object describing properties of the client device reporting the error.

This object should have a key that points to another object, javascript which describes properties of the javascript code/environment to Rollbar.

client.javascript supports the properties in the following rows.

Example:
javascript Rollbar.configure({ scrubFields: ["creditCard"], payload: { client: { javascript: { code_version: "ce0227180bd7429fde128f6ef8fad77396d8fbd4", // Git SHA of your deployed code source_map_enabled: true, guess_uncaught_frames: true } } } });
client .javascript .code_versionVersion control number (i.e. git SHA) of the current revision. Used for linking filenames in stacktraces to GitHub.

Note: for the purposes of nesting under the payload key, only code_version will correctly set the value in the final item. However, if you wish to set this code version at the top level of the configuration object rather than nested under the payload key, we will accept both codeVersion and code_version with codeVersion given preference if both happened to be defined. Furthermore, if code_version is nested under the payload key this will have the final preference over any value set at the top level.
client .javascript .source_map_enabledWhen true, the Rollbar service will attempt to find and apply source maps to all frames in the stack trace.

Default: false
client .javascript .guess_uncaught_framesWhen true, the Rollbar service will attempt to apply source maps to frames even if they are missing column numbers. Works best when the minified javascript file is generated using newlines instead of semicolons.

Default: false
environmentThe environment that your code is running in.

Default: unspecified
serverAn object describing properties of the server that was used to generate the page the notifier is reporting on.

server supports the properties in the following rows.

Example configuration:
`js
Rollbar.configure({
logLevel: "warning", // Rollbar.log() will be sent with a level = "warning"
payload: {
server: {
branch: "master",
host: "web1.mysite.com"
}
}
});

`
server.branchThe name of the branch of the code that is running. Used for linking filenames in stacktraces to GitHub.

Default: "master"
server.hostThe hostname of the machine that rendered the page.

e.g. "web1.mysite.com"

e.g. in Python, use socket.gethostname()
server.rootIt is used in two different ways: source maps, and source control. If you are looking for more information on it please go to:
https://docs.rollbar.com/docs/source-maps
https://docs.rollbar.com/docs/source-control

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.