Skip to main content

Web Agent Options

  • Updated
Print Friendly and PDF

Web Agent Options

This page describes all the options you can set on the injected javascript.

The JavaScript can be loaded async or blocking, some features like exception collection requires that the JavaScript is loaded blocking in the top of the head section after any meta tags.

Load async

<html>
<head>
  <meta charset="utf-8" />
  <!-- Start of UXM Web Agent - Add following snippet to your webpage -->
  <script type="text/javascript">
  (function (w, d, s, sn, on, ne, fse) {
      w['McgUxmObj'] = on; w[on] = w[on] || function () {(w[on].iargs = w[on].iargs || []).push(arguments)}, w[on].jsst = 1 * new Date();
      ne = d.createElement(s), fse = d.getElementsByTagName(s)[0]; ne.async = 1; ne.src = sn; fse.parentNode.insertBefore(ne, fse)
    })(window, document, 'script', '//repo.uxmapp.com/uxm/web/latest/uxm_web_agent.min.js', 'uxm_web');
    uxm_web('server', 'customername.uxmapp.com');
    uxm_web('key', window.location.host);
  </script>
  <!-- End of UXM Web Agent snippet -->
  <title>Title of web page</title>
</head>
<body>
<h1> some text </h1>
</body>
</html>

Load blocking

Copy script to own server and load blocking to support capturing all JavaScript errors/exceptions. (Currently it doesn't support running function to capture username)

It's not recommended to load script from UXM CDN because the monitored webpage would freeze while loading if server hosting monitoring JavaScript is down.

<html>
  <meta charset="utf-8" />
  <!-- Start of UXM Web Agent - Add following snippet to your webpage -->
  <script src="uxm_web_agent.min.js" data-config="server: 'customername.uxmapp.com', xhr.capture: true, sendScreenSize: true, error.capture: true" type="text/javascript"></script>
  <!-- End of UXM Web Agent snippet -->
  <title>Title of web page</title>
</head>
<body>
<h1> some text </h1>
</body>
</html>

 

General Options

 

UXM Collector IP/DNS

If you have installed an on-premise collector enter your internal UXM IP/DNS, note that the FQDN name has to be reachable from your visitors browser locations. You can open firewall or setup a reverse proxy that redirects traffic to the UXM collector.

If you are using UXM SaaS solution please contact support@uxmapp.com for information about you collector DNS.

Manual script tag: server: 'customername.uxmapp.com | on-premise-fqdn'

 

Key

Enter unique key that identifies the server/application, normally we use the format ServerName_SiteName.

You will need to assign the agent in the administration interface afterwards, before data is visible in UXM. Please see Administration Web Agents for more information.

Manual script tag: key: 'ServerName_WebsiteName'
Default value: window.location.host

 

XHR Options

Capture XHR calls

Monitors all XHR calls, was called captureAjax and hookAjax in older versions.

Manual script tag: xhr.capture, captureAjax or hookAjax: false | true
Default value: true

 

Capture XHR Headers

Comma separated string about which headers that should be taken out from monitored XHR calls.

XHR call has to be to server running script or CORS policies will kick in and deny reading the header, remember to set cors: auto.

Manual script tag: xhr.capture.headers: 'x-sharepointhealthscore,spiislatency,sprequestduration'
Default value: ''

 

XHR Timeout

How long time UXM agent waits for XHR/Fetch call to finish in seconds. XHR requests can have infinitive timeouts, UXM will wait for 5 minutes per default and stop the measurement and report the data.

Manual script tag: xhr.timeout
Default value: 300

 

XHR Minimum detection wait time

Defines how long time the Web agent script wait for XHR/Fetch calls to be made after page has loaded, default is 850 milliseconds.

Manual script tag: xhr.minWaitTime or ajaxMinWaitTime
Default value: 850

 

XHR skip/ignore urls

The Web agent will out of the box try to capture all XHR requests, you will have to exclude polled resources, if your application polls specific XHR urls frequently.

Example: /check/session is being polled every 30 seconds and generates a measure in the Splunk app, using xhr.exclude.regex: '/check/' will ignore these polled requests.

Regular expressions is supported, for example:
Ends with extension: '.htc$'
Contains /check/: '/check/'

Manual script tag: xhr.exclude.regex or ajaxSkipRegex: '/urlToIgnore/'
Default value: '.htc$ /adrum dynaTraceMonitor /rb_ keepalive'

 

CORS - Cross-origin resource sharing (XHR capture size and headers capturing)

The Web agent will out of the box try to capture the size of XHR calls, this could violate CORS cross-domain policies, if XHR resources are loaded from another origin and give the warning: Refused to get unsafe header "Content-Length" in the console log.

Example: www.uxmapp.com load XHR resource from cdn.uxmapp.com.
Response headers doesn't allow Content-Length:
Access-Control-Allow-Headers: origin, content-type
Access-Control-Allow-Origin: http://cdn.uxmapp.com

Manual script tag: cors: 'auto' | 'force' | 'off'
Default value: 'auto'

auto: Web agent will try to load XHR size via Content-Length header if Origin is the same.
force: Web agent will always try to load XHR size, might give warnings in console log, you will have to alter your Access-Control-Allow-Headers and allow Content-Length.
off: Web agent will never try to load resources that would give CORS violations.

 

Capture

Under the capture tab you can enable additional agent properties. Dependent on the type you selected more or less may already be enabled.

  • Capture screen resolution

    The clients screen size + depth will be send in each request, visible under Snapshots.

    Manual script tag: sendScreenSize: false | true

  • Capture full iFrame /XHR query

    Capture the full url + query of the iFrame and XHR requests.

    Manual script tag: captureFullQuery: false | true

    Example:

    Normal Full

    /CRM/userdefined/edit.aspx

    /CRM/userdefined/edit.aspx? _gridType=1 &etc=1 &id={1169D99A-00F3-E411-A05E-000C290A2E01} &pagemode=iframe &preloadcache=1430815477727 &rskey=30212249
  • Slow resources limit (Available from version 2016.03.15)

    The Web agent script can gather timings from Images,CSS, XHR calls and display in a waterfall chart, this affects how many timings that are collected, default is top 5 slow resources.

    Manual script tag: resourcesTop: 5

  • Slow resources minimum time (Available from version 2016.03.15)

    Limits the slow resources gathering to only include resource if it's above the minimum time, default is 50 ms.

    Manual script tag: resourcesMinTime: 50

 

Errors/Exceptions

Allows the UXM Web agent to capture JavaScript errors and exceptions that's not handled in a try catch, the errors is captured by overriding window.onerror function.

Please note that exceptions occurring during page load (before the UXM Web JavaScript is fully loaded) will not be captured, we therefore recommend that the UXM Web JavaScript is added blocking in the beginning of the head section before any scripts is loaded, and that the script is loaded from own server to capture all exceptions during page load and avoid blocking wait if the server hosting the JavaScript is down.

External javascript have to be loaded with crossorigin to avoid that CORS restrict exception collection, this is done by adding crossorigin attribute to the script tag and ensuring that remote server replies with correct access-control-allow-origin header:
<script src="https://download.uxmapp.com/tests/js-with-exceptions.js" crossorigin></script>

  • Capture errors/exceptions

    The UXM Web agent will hook into the onerror event and capture all errors that occurs in application.

    Manual script tag: error.capture: false | true

  • Maximum captured error text length

    Maximum length of the error message and source, default is 512 characters. StackTraces won't be limited by this setting.

    Manual script tag: error.max.length: 512

  • Maximum captured errors per page request

    Maximum number of errors captured per page request, default is 5.

    Manual script tag: error.max.per.request: 5

 

Advanced Options

Username collection via custom JavaScript

The agent enables you to activate a small JavaScript code on the clients to get their username, this requires that the username is visible in the HTML output.

SharePoint and CRM have automatic builtin username detection.

There are two ways to gather username depending on how you have injected the JavaScript:

 

Option 1: if you are using async load with dynamic options, you can run a function that returns the username from the HTML page. Note that all functions used has to be available on the page we execute the JavaScript on.

You can use the Chrome Console and create + test it for example the jQuery command available on this monitored site can be taken out with: jQuery("a[title|='User account'] strong").text()

 

Injected JavaScript with username capturing, the function() {...} is executed when the results are send to the UXM server.

<html>
<head>
  <!-- UXM Web performance monitor -->
  <script type="text/javascript">
  (function (w, d, s, sn, on, ne, fse) {
      w['McgUxmObj'] = on; w[on] = w[on] || function () {(w[on].iargs = w[on].iargs || []).push(arguments)}, w[on].jsst = 1 * new Date();
      ne = d.createElement(s), fse = d.getElementsByTagName(s)[0]; ne.async = 1; ne.src = sn; fse.parentNode.insertBefore(ne, fse)
    })(window, document, 'script', '//repo.uxmapp.com/uxm/web/latest/uxm_web_agent.min.js', 'uxm_web');
    uxm_web('server', 'customername.uxmapp.com');
    uxm_web('key', window.location.host);
    uxm_web('username', function() {return jQuery("a[title|='User account'] strong").text()});
  </script>
</head>
<body>
<h1> some text </h1>
</body>
</html>

 

Option 2: Via script appended to the /uxm_web_agent.min.js file.

/*jslint plusplus: true */
/*global window, document */

// Fetch custom username from DOM.
(function () {
    'use strict';
	var apm = window.McgAPM;

    /**
	 * Returns the innerText of the object.
	 * IE/Chrome has obj.innerText.
	 * FireFox uses obj.textContent. (TextContent isen't available in IE8.
	 */
	function getInnerText(obj) {
        if (obj) {
            return obj.innerText || obj.textContent;
        }
        return '';
	}
    
	if (apm && apm.initialized) {

		// Try to get username after page is loaded and DOM is ready.
		apm.Attach(window, 'load', function () {
            try {
                apm.SetMetric('un', apm.TrimString(getInnerText(document.querySelector('.HeaderLink span.style2'))));
				
			} catch (e) {
				apm.OnError("WARNING: Getting username cast exception: " + apm.GetExceptionError(e), '', 0);
			}
		});
	}
}());

 

JavaScript URL (Load balancer support)

For load balancing support, the Web agent is normally injected via the path /uxm_web_agent.min.js.

Not all load balancers support this, you can change the url to /loadbalancedfolder/ if you receive a 404 - NOT FOUND while loading /uxm_web_agent.min.js.

Manual script tag: None link to uxm_web_agent.min.js file is changed.

 

Enabling the secure cookie option will force the browser (or other http clients) to send cookies over SSL connections ONLY.
Our tracing cookies will not be available to any part of the monitored site that is not secure.
If you have a mixed mode site HTTP/HTTPS sites only the HTTPS sites will be able to track the user.

Manual script tag: secureCookie: false | true

 

Force HTTPs

Force the clients to send the data to the collector via a secure connection.

WARNING: Your UXM Collector server must have a valid HTTPs certificate and you must use a DNS name in the UXM Collector field.

Manual script tag: forceHttps: false | true

 

Force HTTP

Force the clients to send the data to the collector via http.
Only recommended if your collector service do not have a valid HTTPS certificate.

Please note some browsers may display warnings in newer Browsers about mixed HTTP/HTTPS content.

Manual script tag: forceHttp: false | true

 

When true, group nested iframes in one capture of data, URL is the main page.

When false, each nested iframe will send one additional capture of data to collector, URL is the iframe's URL.

This option can be used either in the main document and in the documents which are loaded as iframes:

  • If set to true in both main page and the iframe, then the iframe's timings will be grouped into the main page collected data.
  • If set to true in main page and false in the iframe, then an additional set of data will be collected containing the iframe's timings.
  • If set to false in main page, then an additional set of data will be collected for each nested iframe containing the iframe's timings.

Default value is false.

Manual script tag: iframe.link: false | true

 

 

Related articles

On this page