Website Monitoring API

The Global Object

The Instana JavaScript agent defines a new global function called ineum. This function is available immediately after the JavaScript snippet within the HTML document. That means that the function exists even when the agent itself has not been downloaded yet. This was done to make ineum API calls easy and efficient.

When the agent is not yet downloaded, ineum will queue all the executed API calls. Upon finished agent download, these API calls are executed synchronously in the order in which they were made. From that point forth, ineum will be replaced with a function that immediately executes API calls.

API Structure

All ineum calls follow the same structure. From a like typing perspective, it looks like this:

function ineum(commandName: string, ...args: any[]): void

The command name identifies what command should be executed, e.g. set meta data or report an error. The args themselves are specific to each and every command and are explained within the following sections in more detail. Note that ineum never returns anything.

APIs

The following sections describe the available commands with flowjs-like typings.

Monitoring Key

Monitoring keys can be set via the key command. The monitoring key can be seen when configuring websites within the Instana user interface.

ineum('key', trackingKey: string);

Page

Instana can segment website metrics by logical pages. To do so, it needs a hint what page the user is currently looking at. This page name can be set via the page command. We recommend to set the page as early as possible. Additionally, it is perfectly fine to change the page at some point to present document changes (e.g. for single-page applications).

ineum('page', pageName: string);

Generally speaking, we recommend not to use window.title or window.href to define pages. This will result in a large number of tracked pages that, will not provide value in the majority of cases, e.g. because window.title contains product names. Instead, we recommend the usage of a logical names for pages. For example product detail page or payment selection. This will result in fewer pages which will have a direct relation to actually existing code.

Meta Data

Meta data can be used to annotate page loads and AJAX calls. You can use this to track UI configuration values or user data fragments.

ineum('meta', key: string, value: string);

Reporting URL

When deployed in on-prem environments, the tracking script is not supposed to send its data to instana.io. Instead, it needs to send data to the on-prem installed Instana backend. The reportingUrl command can be used to configure this URL.

ineum('reportingUrl', reportingUrl: string);

Page Load Backend Trace ID

As part of the page load, a backend trace ID can be defined to allow for frontend/backend correlation. See our dedicated section on backend correlation for more details. This is only required in order to gain correlation between page loads’ backend and frontend processing. It is not required for correlation between XMLHttpRequest or fetch requests.

ineum('traceId', traceId: string);

Excluding URLs from Tracking

It is common to call some APIs from JavaScript (e.g. via XMLHttpRequest or fetch) to ensure that a connection is working or for WebSocket fallback purposes such as long polling. While this can be tracked, it is often not very helpful to track these types of AJAX calls. Using the ignoreUrls command, an array of regular expressions can be set for which not AJAX calls will be tracked.

ineum('ignoreUrls', ignoreUrls: RegExp[]);

Resource Timing Buffer Clearing

Whether or not the resource timing buffer is cleared after collecting resource timing information. This is used to ensure that the buffer always has sufficient capacity for new resource timing entries. This defaults to true.

ineum('autoClearResourceTimings', automaticallyClear: boolean);

Retrieving the Page Load ID

It can sometimes be useful to manually receive the ID of the page load, e.g. when wanting to do custom correlation. This function will return undefined as long as the JavaScript agent hasn’t been loaded yet. Once loaded, it will always return the same string.

ineum('getPageLoadId'): ?string;

Error Tracking

Manual Error Reporting

It is possible to report caught errors. This can be used to integrate Instana with frameworks and libraries that catch uncaught errors.

ineum('reportError', error: Error);

Excluding Errors from Tracking

It is possible to explicitly stop some errors from being reported to Instana. This can be used to ignore known / unfixable errors.

ineum('ignoreErrorMessages', ignoreErrorMessages: RegExp[]);

Insights Into Script Errors

Websites embedding a large number of third-party scripts typically encounter a steady number of Script Errors. We do provide guidance on how to make these errors accessible, i.e. how to get access to the real error message and stack. Sometimes though, you may not be able to follow these instructions, e.g. because the third-party will not add the necessary Access-Control-Allow-Origin header. For these case, we provide alternative means to improve insights into Script Errorss.

Please note that this mechanism is no silver bullet. It grants you improved visibility and you encounter more helpful tracked errors, but you will still see (a reduced number of) Script Errors. We still advise to read through and attempt implementation of the cross-origin guidance first.

Explicit Tracking Of DOM Event Listener Errors

This puts the Instana agent into the call stack of every DOM event listener. The Instana agent will automatically put try/catch statements around the event listeners’ functions. This allows better insights into cross-origin errors.

This feature is disabled by default.

ineum('wrapEventHandlers', enabled: boolean);
Explicit Tracking Of Timer Errors

This puts the Instana agent into the call stack of all timers. The Instana agent will automatically put try/catch statements around the timer handlers’ functions. This allows better insights into cross-origin errors.

This feature is disabled by default.

ineum('wrapTimers', enabled: boolean);
Ignoring Script Errors

If you aren’t able to get insights into script errors using any of the previously mentioned mechanisms, you may want to stop them from being reported to Instana. This can be useful in order to ensure that error statistics remain actionable. To stop script errors from being reported to Instana, you can use the following snippet.

ineum('ignoreErrorMessages', [/^script error/i]);

Single-Page Applications (SPA) Monitoring

Due to the asynchronous nature of SPAs, the SPA API is comprised of two calls. We capture several different transition states: beginning, end, error and aborted. For more examples on how to integrate SPA monitoring into popular JavaScript frameworks, please take a look at the SPA Instrumentation page.

Note: SPA support is currently in beta.

Start Page Transition

We use the startSpaPageTransition command to inform the agent about the beginning of route changes.

ineum('startSpaPageTransition');

End Page Transition

To indicate the end of the transition, we use the endSpaPageTransition command.

ineum('endSpaPageTransition', {
  status: 'completed' | 'aborted' | 'error',
  // The URL of the page that the page transition for done for. When undefined, the agent
  // will fall back to window.location.href. It is useful to specify a URL explicitly as
  // routers may have already reverted the in-browser url on failed transitions.
  url?: string?,
  // custom text explaining the transition
  explanation?: string
});

Cross-Origin Request Backend Correlation

Instana’s backend correlation works by setting custom headers on XMLHttpRequest / fetch requests. These headers are set by the JavaScript agent and then read by the server. Within the browser, the transmission of custom headers is restricted by the same-origin policy. More specifically, custom headers can only be set for same-origin requests or for requests to other origins which allow custom headers to be transmitted. For example, a website being served by https://example.com:443 cannot by default make XMLHttpRequests to https://shop.example.com:443 as these are two different origins.

To work around this security restriction, cross-origin resource sharing (CORS) is available. With CORS, origins can be whitelisted for cross-origin resource access. If you already have cross-origin resource access within your application, then you are most likely already using some CORS headers.

To enable Instana backend correlation, the following needs to be done:

  1. Allow Instana’s correlation headers for cross-origin requests by responding on the server side with the following header:
Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
  1. Inform the JavaScript agent that CORS was correctly configured and that it should set these correlation headers:
ineum('whitelistedOrigins', urls: RegExp[]);

Please make sure that your application works correctly after those changes. Instructing the JavaScript agent to add backend correlation headers (i.e. whitelisting origins) without configuring CORS, has a high probability of breaking your website!