JavaScript agent API

Parameters

Note that the function ineum never returns anything (with the exception of command getPageLoadId, see as follows).

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);

if (window.location.hostname === 'example.com') {
  ineum('key', 'production monitoring key');
} else if (window.location.hostname === 'qa.example.com') {
  ineum('key', 'QA monitoring key');
} else {
  ineum('key', 'test monitoring key');
}

Reporting URL

Beacons are transmitted to this URL via HTTP GET and POST to deliver the monitoring data to Instana.

ineum('reportingUrl', reportingUrl);

Multiple backends

In some cases, it might be desirable to make a JavaScript agent report to multiple backends. In this case, use the reportingBackends command to make the JavaScript agent report to multiple backends.

ineum('reportingBackends', reportingBackends);

{
  reportingUrl: 'http://example.com',  // The URL to which to send website monitoring data to.
  key: 'monitoring key'                // The monitoring key for the website configuration in Instana.
}

ineum('reportingBackends', [
      { reportingUrl: 'http://backend1.example.com', key: 'monitoring key 1' },
      { reportingUrl: 'http://backend2.example.com', key: 'moniroting key 2' }
    ]);

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). This will enable Instana to track page transitions in addition to page loads.

ineum('page', pageName);

Page transition events are recorded whenever the page name is changed via API – with the exception of the first invocation of this API during the page load phase.

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 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.

We provide sample projects that show how to collect meaningful page names for a variety of frameworks and libraries. Should your framework/library be missing, feel free to raise a pull or support request.

ineum('page', 'shopping-cart');

// Do you want to change meta data and the page name at the same time?
// Make sure to change the page name last as this immediately
// triggers a page transition beacon.
ineum('meta', 'product', 'skateboard');
ineum('page', 'article-details');

ineum('autoPageDetection', enabled);

ineum('autoPageDetection', true);  
// page changes will be detected once set to true 

ineum('autoPageDetection', {mappingRule});
ineum('autoPageDetection', {titleAsPageName});

ineum('autoPageDetection',  {ignorePopstateEvent});

ineum('autoPageDetection',  {mappingRule: [[/.*checkuserdetails.*/i, 'User Details']]}); 
// matches the regex and sets page name as User Details
ineum('autoPageDetection',  {mappingRule: [[/.*product[0-9]+contains-[A-Za-z]+-productID,-account-([A-Za-z].*)\1+/, 'Product Page : id $1'],[[/.*aboutPage.*-([A-Za-z].*)/, 'About Page id: $1']]]});           
ineum('autoPageDetection',  {mappingRule: [[/^.*?-(profile.*?)-(accountId.*?)-(yes.*?)$/, '$1 : $2, Logged in: $3']]});

ineum('autoPageDetection',  {titleAsPageName:true});        

ineum('autoPageDetection',  {ignorePopstateEvent:true});        

Identifying Users

User-specific information can optionally be sent with data transmitted to Instana. This information can then be used to unlock additional capabilities such as:

• calculate the number of users affected by errors,
• to filter data for specific users and
• to see which user initiated a page load / AJAX call.

By default, Instana will not associate any user-identifiable information to beacons. Please be aware of the respective data protection laws when choosing to do so. We generally recommend identification of users via a user ID. For Instana this is a completely transparent string that is only used to calculate certain metrics. userName and userEmail can also be used to have access to more filters and a more pleasant presentation of user information.

It is important to note that data already transmitted to Instana's server cannot be retroactively updated. For this reason it is important to call this API as soon as possible in the page loading process. We recommend to call this API synchronously in the page loading process, e.g. by rendering the information into the HTML document on the server side. This ensures that all beacons carry user information, that the unique/affected user statistics are correct and that beacons can be correctly filtered and grouped when analyzing.

ineum('user', userId, userName, userEmail);

// Report everything to Instana
ineum('user', 'hjmna897k1', 'Tom Mason', 'tom@example.com');

// or only some data points
ineum('user', 'hjmna897k1');
ineum('user', null, null, 'tom@example.com');

Session Tracking

Session tracking can be used in order to gain insights into activity of end-users across page loads. Session tracking specifically enables Instana to determine end-user impact in the absence of defined user information.

In order to track sessions the JavaScript agent will use the localStorage browser API after making the trackSessions call. Technically a session is a random ID stored alongside two timestamps within browsers' localStorage under the key in-session.

Responsibility for adherence to privacy regulations lies with the caller of this API.

ineum('trackSessions', sessionInactivityTimeout, sessionTerminationTimeout);

// Starts tracking sessions with the default timeouts
ineum('trackSessions');

// or specify custom timeouts
ineum('trackSessions', 900000 /* 15min */, 3600000 /* 1h */);

ineum('terminateSession');

// Starts tracking sessions with the default timeouts
ineum('trackSessions');

// after some time…
ineum('terminateSession');

Metadata

Metadata can be used to annotate page loads and AJAX calls. Consider using this to track UI configuration values, settings, feature flags… any additional context that might be useful for analysis.

ineum('meta', key, value);

ineum('meta', 'version', '1.42.3');
ineum('meta', 'role', 'admin');

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. A trace id should be a hex string with 16 or 32 characters.

ineum('traceId', traceId);

ineum('traceId', '89jkbds891jkn321');

Excluding URLs from Tracking

This API allows you to define several regular expressions that, when at least one matches, will not result in data transmission to Instana. The regular expressions are evaluated in the following scenarios.

• Evaluation against the documents' URLs (the URLs visible in the address bar, i.e. window.location.href). All data transmission to Instana is disabled when one of the regular expressions matches.
• Evaluation against resources' URLs, e.g. URLs of JavaScript and CSS files. No information about resources matching one of the regular expressions will be transmitted to Instana.
• Evaluation against the target URLs of HTTP calls, e.g. via XMLHttpRequest and fetch. No information about HTTP calls matching one of the regular expressions will be transmitted to Instana.

ineum('ignoreUrls', ignoreUrls);

We also support stripping of secrets from document URLs, i.e. the URL visible in the browser address bar (see the secrets API). However, be aware that secrets stored in document URLs are almost certainly leaked to all third-parties. We have a dedicated example app with description that shows why secrets stored in document URLs are prone to being leaked to all third-parties. Please refer to this example app and description for more details. You may however choose to ignore all monitoring data collection for these URLs via this API.

ineum('ignoreUrls', [
  /\/comet.+/i,
  /\/ws.+/i,
  /.*(&|\?)secret=.*/i
]);

Redacting secrets from URLs

Query parameters in collected URLs may contain sensitive data. Therefore, the JavaScript agent supports the specification of patterns for query parameter keys whose values shall be redacted. Redaction happens within the JavaScript agent, i.e., within the web browser. Consequently, secrets will not reach the Instana servers for processing and will not be available for analysis in the UI or retrieval via API.

ineum('secrets', secrets);

If a query parameter matches an entry from the list, the value is redacted and not sent to the Instana backend. If no ineum('secrets') is defined, Instana uses [/key/i, /secret/i, /password/i] as matching rule by default.

ineum('secrets', [/account/i, /user/i]);

Redacting fragment from URLs

The fragment of collected URLs might contain sensitive information. Therefore, the JavaScript agent supports the specification of patterns for fragment values that can be redacted based on the URL path. This redaction takes place within the JavaScript agent in the web browser. As a result, sensitive information is prevented from reaching the Instana servers for processing. Sensitive information remains inaccessible for analysis in the UI or retrieval through the API.

ineum('fragment', fragment);

If a segment of your URL path matches an entry in the list, the fragment value is redacted and not sent to the Instana backend. By default, Instana does not redact URL fragments.

ineum('fragment', [/example.com/i]);

Excluding User-Timings from Tracking

We automatically collect markers and measures made via the User-Timing API and turn them into custom events. This means that the User-Timing API can be used as a vendor-neutral way to report pure timing data to Instana.

This API allows you to define several regular expressions that, when at least one matches, will not result in collection of specific user-timings. By default we are ignoring…

• React's user-timings, i.e. marks and measures that start with the ⚛️ or ⛔ emoji,
• Angular's user-timings, i.e. marks and measures that start with Zone and
• Marks and measures whose names start with either start or end .

ineum('ignoreUserTimings', ignoreUserTimings);

ineum('ignoreUserTimings', [
  /^\u269B/,
  /^\u26D4/,
  /^Zone(:|$)/,
  /mySecretTiming/i
]);

Configuring Maximum Waiting after Page Load

In order to collect additional metrics, e.g. first input delay and cumulative layout shift, the JavaScript agent will wait until…

• all of the metrics are available
• the page is unloaded (e.g. tab is closed) or
• until a maximum waiting time has elapsed.

You can use this API to re-configure the maximum waiting time. By default we will wait for up to one second after the page load is finished, i.e. the onLoad event has ended.

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);

ineum('maxMaitForPageLoadMetricsMillis', 500);

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');

var pageLoadId = ineum('getPageLoadId');
console.log(pageLoadId);

Error Tracking

ineum('reportError', error, opts);

{
  componentStack: '...' // an optional string

  meta: {               // An optional JavaScript object with `string` values which can be used
    widgetType: 'chart' // to send metadata to Instana just for this singular event. In contrast to
  }                     // the usage of the metadata API, this metadata is not included in subsequent
                        // beacons.
}

ineum('reportError', new Error('Something failed'), {
  componentStack: '…',
  meta: {
    widgetType: 'chart'
  }
});

componentDidCatch(error, info) {
  ineum('reportError', error, {
    componentStack: info.componentStack
  });

  // your regular error boundary code
}

import { ErrorHandler, NgModule } from '@angular/core';

class CustomErrorHandler implements ErrorHandler {
  handleError(error) {
    ineum('reportError', error);

    // Continue to log caught errors to the console
    console.error(error);
  }
}

@NgModule({
  providers: [{ provide: ErrorHandler, useClass: CustomErrorHandler }],
})
class MyModule {
  // the rest of your application code…
}

app.config.errorHandler = (err, instance, info) => {
  ineum('reportError', err);
  // your regular error handling code
}

ineum('ignoreErrorMessages', ignoreErrorMessages);

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

ineum('wrapEventHandlers', enabled);

ineum('wrapEventHandlers', true);

ineum('wrapTimers', enabled);

ineum('wrapTimers', true);

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

Reporting Custom Events

Disambiguation: Looking for Global Custom Events instead? Head over to the Events page.

Custom events enable reporting about non-standard activities, important interactions and custom timings to Instana. This can be especially helpful when analyzing uncaught errors (breadcrumbs) and to track additional performance metrics.

ineum('reportEvent', eventName, {
  duration: duration,
  timestamp: timestamp,
  backendTraceId: backendTraceId,
  error: error,
  componentStack: componentStack,
  meta: meta,
  customMetric: customMetric
});

ineum('reportEvent', 'login');

ineum('reportEvent', 'full example', {
  timestamp: Date.now(),
  duration: 42,
  backendTraceId: '31ab91fc109223fe',
  error: new Error('whooops – sorry!'),
  componentStack: 'a component stack',
  meta: {
    state: 'running'
  },
  customMetric: 123.2342  
});

Cross-Origin Request Backend Correlation

Instana's backend correlation works by setting custom headers on XMLHttpRequest / fetch requests. The JavaScript agent sets these headers which are then read by the server. Within the browser, the same-origin policy restricts the transmission of custom headers. More specifically, custom headers can be set only for same-origin requests or for requests to other origins which allow transmission of custom headers. For example, by default a website being served by https://example.com:443 cannot 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 allowed 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 headers.

   Please note that your server must respond with these headers for both preflight requests and regular requests. Preflight requests (identifiable via the OPTIONS HTTP method) are executed by the browser to verify that requests may be issued to the server.

   Access-Control-Allow-Origin: https://your-origin.example.com
   Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
   

2. Inform the JavaScript agent that CORS is configured correctly and that it should set these correlation headers:

   ineum('allowedOrigins', urls);
   

ineum('allowedOrigins', [/.*api\.example\.com.*/]);

Capture HTTP request or response headers

The HTTP request or response headers on XMLHttpRequest or fetch requests can be captured by the JavaScript agent. You can define the HTTP headers that you want the JavaScript agent to capture by the captureHeaders command.

Within the browser, the same-origin policy restricts the access of custom headers. Without cross-origin resource sharing (CORS) configuration, the JavaScript agent might not be able to capture all HTTP headers. To enable CORS, see Cross-Origin Request Backend Correlation. With CORS, only the CORS-satisfied request or response headers and the ones that are defined in Access-Control-Expose-Headers can be collected by the JavaScript agent.

ineum('captureHeaders', [/content-type/i]);