Installation and Configuration for Browser Monitoring

Atatus Browser monitoring provides deep visibility and insight into how your users are interacting with your application or website. Atatus measures page load timing, also known as real user monitoring (RUM), but it goes far beyond that to measure:

  • Individual page performance
  • AJAX requests
  • Session traces
  • JavaScript errors
Install snippet

To start with you have to signup and create a project in Atatus. When you create one, you will see your API Key and a small snippet of code below, which you have to copy into the head tag of every html page. Please make sure that you add it before other script tags as well. You can also find the same snippet inside the Settings of your project as well.

A sample snippet would be

<script src="//dmc1acwvwny3.cloudfront.net/atatus.js"></script>
<script type="text/javascript"> atatus.config('YOUR_API_KEY').install(); </script>

If you work on Ionic Framework or any other hybrid mobile app frameworks, you have to use full URL instead of protocol-relative URL.

<script src="https://dmc1acwvwny3.cloudfront.net/atatus.js"></script>
<script type="text/javascript"> atatus.config('YOUR_API_KEY').install(); </script>

Replace the YOUR_API_KEY string with the API Key that is assigned for your project. You're done.

Install From Package Managers

If you want to include Atatus script with your source, you can take it from package managers such as bower and npm

With Bower

bower install atatus-js

With NPM

npm install atatus-js --save

You can include the local script in your source as follows

<script src="/PATH_TO_ATATUS/atatus.min.js"></script>
<script type="text/javascript"> atatus.config('YOUR_API_KEY').install(); </script>
Test your installation

You can test your installation as follows

  • Navigate your browser to a page that has the above code installed
  • Type the following code into the browser console and press enter:

    atatus.notify(new Error('Test Atatus Setup'));

This simulates an error. It should appear in the Atatus within a few seconds.

Configuration options

Atatus provides a few pieces of functionality to control and improve the error tracking in your web applications.

Pass in an object as the second parameter to the config() function containing one or more of these configurations mentioned below and a boolean to define its behavior:

Option Description
tagsarray Tags are used to search a specific error. Tags may contain release stage, plan and etc. Set tags (array of strings) to send to Atatus with every error.
customDataobject Set additional meta-data (object) to send to Atatus with every error. It helps you to fix the error. Custom data cannot be searchable.
versionstring This will allow you to filter the errors in the dashboard by that version.
consoleboolean Atatus will watch all console activity and include that information in the Timeline. Also any calls to console.error() will automatically trigger an error. By default, it is disabled. If you want to capture console activity, set this option to true to enable it.
offlineboolean Offline saving is disabled by default. The provider has a feature where if errors are caught when there is no network activity they can be saved (in Local Storage). When an error arrives and connectivity is regained, previously saved errors are then sent.
anonymizeIpboolean In some countries, you are not allowed to track IP addresses of the users. In this case, you can set this option to true to anonymize the IP address of your users. By default, it is disabled.
disableSessionboolean Session tracking is enabled by default. Set this option to true/false to disable/enable reporting of session traces for better debugging of performance issues.
ignoreErrorsarray Very often, you will come across specific errors that are a result of something other than your application, or errors that you’re completely not interested in. ignoreErrors is a list of these messages to be filtered out before being sent to Atatus as either array of regular expressions or strings.
allowedDomainsarray Captures page views, AJAX and JS Errors from the given set of domains. Ignores the rest of the domains.
beforeSendfunction This callback function will be called immediately before the payload is sent. A function that allows mutation of the data payload right before being sent to Atatus. Also you can inspect the payload and decide whether or not to send it.
beforeErrorSendfunction This callback function is very specific for error payload and it will be called for every error payload. This function allows mutation of the error payload right before being sent to Atatus.
groupingKeyCallbackfunction You can control custom grouping for error instances by passing in a callback. This will override the automatic grouping and be used to group error instances together. Errors with the same key will be placed within the same error group.
atatus.config('YOUR_API_KEY', {
    tags: ['production', 'premium'],
    customData: {
      name: "John Doe",
      plan: "premium",
      beta_access: true
    },
    version: '1.0.0',
    console: true,
    offline: false,
    ignoreErrors: ['num.substr is not a function', /Random Exception.*/],
    allowedDomains: ['www.acme.com', 'api.acme.com', 'api.other.com'],
    beforeSend: function (payload) {
      // You can modify the payload or filter out sensitive information
      // Return true to send or false to abort the send
      return true;
    },
    groupingKeyCallback: function (error) {
      // Inspect the error and return a string derived from the properties you want
      return error.message;
    }
}).install();
Sending custom exceptions

All unhandled exceptions will be automatically captured by Atatus. If you want to push your own exception, you can do so using the following method

try {
  // code that could throw an exception
  throw new Error('Something went wrong!');
} catch(e) {
  atatus.notify(e);
}

Sending Tags

You can tag any errors with information like release stage, plan and etc. Tags are used to search the specific errors in the Atatus. Tags can be set as array of strings.

On initialization:

Tags (array) can be passed in options object in the config() call.

atatus.config('YOUR_API_KEY', { tags: ['production', 'premium'] }).install();
Using set method:

They can also be set by calling the setTags function on the Atatus object:

atatus.setTags(['production', 'premium']);
On notify call:

Pass tags in as the third parameter:

atatus.notify(err, null, ['production', 'premium']);

Sending custom data

Custom data helps you to debug and fix the error easily.

On initialization:

Custom data variables (objects) can be passed in options object in the config() call.

atatus.config('YOUR_API_KEY', { customData: { name: "John Doe" } }).install();
Using set method:

They can also be set by calling the setCustomData function on the Atatus object:

atatus.setCustomData({
      name: "John Doe",
      plan: "premium",
      beta_access: true
    });
On notify call:

Pass custom data as the second paramter. This lets you send variables from catch blocks.

atatus.notify(err, { name: "John Doe" });

Heads up! Custom data cannot be searchable. If you want to search a specific error, then use tags.

Allowed domains

For RUM (Page Views and AJAX) and JS Errors, Atatus will send it for all domains. You can restrict sending exceptions and performance data for specific domains only. This option can be used to block third party domains, in which you are not interested in monitoring or during development you can block localhost.

Note that, you need to add "api.acme.com" in your allowed domains if you want to capture metrics of AJAX calls over "api.acme.com".

If you want to allow all your sub domains, then you can just include your domain name like [ "acme.com" ].

On initialization:

Allowed domains (array) can be passed in options object in the config() call.

atatus.config('YOUR_API_KEY', { allowedDomains: ['www.acme.com', 'api.acme.com', 'api.other.com'] }).install();
Using set method:

They can also be set by calling the setAllowedDomains function on the Atatus object:

atatus.setAllowedDomains(['www.acme.com', 'api.acme.com', 'api.other.com']);
Exclude domains:

You can also pass REGEX in the allowed domains array. If you want to exclude certain domains (like acme.com and example.com) from monitoring, then you can do it as follows

atatus.setAllowedDomains([/^((?!acme.com|example.com).)*$/g]);
Offline saving

If JavaScript errors are caught when there is no network activity they can be saved (in Local Storage). When the connectivity is regained, previously saved JavaScript errors are sent. This is useful in environments like WinJS, where a mobile device's internet connection is not available always.

Offline saving is disabled by default. You can enable it immediately after your config() call:

atatus.enableOffline(true)

If a JavaScript error is caught and no network connectivity is available (in this case Atatus API cannot be reached) or if the request times out after ten seconds, the JavaScript error will be saved to LocalStorage. This is validated in Chrome, Firefox, IE10/11, Opera and WinJS.

Application version

You can set a version for your app by calling:

atatus.setVersion('1.0.0');

This will be sent along with each errors. This will be used to group the error occurrences. Versioning is recommended when you works with source map. The version number must be a string.

User tracking

You can set currently logged in user or customer as follows. This will help you to filter performances data and errors by user.

atatus.setUser('unique_user_id', 'emailaddress@company.com', 'Full Name');
Anonymize IP addresses

In some countries, you may be required to anonymize all of your users' IP addresses. Atatus allows you to easily do it by anonymizeIp option as follows.

atatus.config('YOUR_API_KEY', { anonymizeIp: true }).install();
Adding custom breadcrumbs

Atatus automatically includes user actions to the timeline. If you want to add your custom actions that led up to an error, you can attach breadcrumbs as follows:

atatus.leaveBreadcrumb(message, type);

Where:
message - Required. message to be displayed in the timeline.
type - Optional. It can be either info, warn, error. By default, it is info.

Eg:

atatus.leaveBreadcrumb('Your breadcrumb message');
onBeforeSend

A function that allows mutation of the data payload right before being sent to Atatus. If, after inspecting the payload, you wish to discard it and abort the send to Atatus, simply return false.

atatus.onBeforeSend(function (payload) {
    // You can modify the payload or filter out sensitive information
    return true; // Return false here to abort the send
});

If you want to capture hash based route change in pages, you can do it as follows

atatus.onBeforeSend(function (payload) {
    if (payload && payload.request && payload.request.url) {
      payload.request.url = payload.request.url.replace('/#/', '/');
    }
    return true;
});
onBeforeErrorSend

To have more fine grained control over what errors are sent to Atatus, you can implement a onBeforeErrorSend function. If, after inspecting the payload, you wish to discard it and abort the send to Atatus, simply return false.

atatus.onBeforeErrorSend(function (error) {
    // You can modify the error payload or filter out sensitive info.
    if (error && error.url) {
        error.url = 'https://www.my-custom-url.com';
    }
    return true; // Return false here to abort the send
});
setGroupingKeyCallback

You can control custom grouping for error instances by passing in a callback. This will override the automatic grouping and be used to group error instances together. Errors with the same key will be placed within the same error group. The callback's signature should take in the error payload and return a string, ideally 64 characters or less. If the callback returns null or or a non-string the error will be grouped using Atatus's server side grouping logic (this can be useful if you only wish to use custom grouping for a subset of your errors).

atatus.setGroupingKeyCallback(function (error) {
    // Inspect the error and return a hash derived from the properties you want
    return error.message;
});
Console options

Atatus will watch all console activity and include that information in the Timeline. Also any calls to console.error() will automatically trigger an error. By default, it is disabled. You can enable this options as follows

atatus.config('YOUR_API_KEY', {

   // Enable or Disable all console activity
   console: true,

   // By default Atatus will watch all console activity and include that information in the Timeline
   consoleTimeline: true,

   // Set this to false if you don't want your users seeing anything when the dev tools open.
   consoleDisplay: true

   // Set this to false if you don't want console.error() to trigger errors.
   consoleErrorNotify: true,

   // Specify levels only if you want to watch certain console functions
   consoleTimelineLevels: ["log","debug","info","warn","error"]

 }).install();

Blackboxing

You may also notice that console messages and stacktraces contain references to atatus.js. This is a side-effect of our wrapping. If you’re developing in Chrome, you can exclude our script by Blackboxing it. Also the debugger will not jump into that atatus.js file when stepping through code you're debugging.

Blackboxing
Disable Atatus

Atatus automatically capture errors and performance metrics. If you don't want, you can disable Atatus as follows

atatus.uninstall()

You can disable real user monitoring(RUM) feature alone as follows

atatus.config('YOUR_API_KEY', { disableRUM: true }).install();

You can disable exception tracking feature alone as follows

atatus.config('YOUR_API_KEY', { disableErrorTracking: true }).install();

Document Sections