JavaScript Agent injection

Injecting Agents is what instruments a web site. Injection consists of:

  • Initialization code. It is an inline <script> tag. It must be injected as the very first script and consists of essential instrumentation parts of the JavaScript Agent.
  • Injecting a tag with a src-attribute. For the best capturing experience, the it should be injected right after the inline tag, before any other JavaScript.

Asynchronous injection

The JavaScript Agent injects asynchronously by default using the defer script tag attribute. See MDN Documentation for details.

Asynchronously loaded scripts do not block page loads, but there are a few drawbacks. Since the Agent cannot redefine any library variables if they already have been initialized (like jQuery or AngularJS), it is strictly recommended that defer is also used for any third party frameworks to be instrumented. The JavaScript Agent must be available before those frameworks start initializing, otherwise it is not possible to capture actions triggered by scripts.

You can always disable asynchronous injection by clearing the Load the JavaScript Agent asynchronously check box in <System Profile> > User Experience > Web applications.

Automatic injection

The following is a sample tag combination automatically injected by the Agent as first of script tags in <head> at delivery of the web page ‐ with settings according to the configuration in System Profile > User Experience:

<script type="text/javascript">(function(){var a=window;a.dT_?a.console&&a.console.log("Duplicate agent injection detected, turning off redundant   initConfig."):window.dT_||(window.dT_={cfg:"tp=0,50,10|lab=1|reportUrl=dynaTraceMonitor|agentUri=/ajax/dtagent_pqtx_0000000.js  
|auto=1|domain=#DOMAIN#|rid=RID_1640928385|rpid=1646377341|app=#APP#"})})();...</script>
<script type="text/javascript" src="/dtagent_bdpx_0000000.js"></script>

The first tag (without src-attribute) is the Agent's initialization code. It must be delivered inline and is executed synchronously. It performs early-wrapping of native browser functions and third party libraries if available to ensure capturing can be done reliably.

The second tag requests the part of the JavaScript Agent that can be loaded asynchronously and therefore won't block a page from being loaded. The filename defines it's version and which parts of the Agent should be delivered:

  • dtagent is the JavaScript Agent Name set in System Profile > User Experience > Global Settings.
  • 7000000001289 is the Agent version (major, minor, revision, buildnumber).
    Each part of the version string consists of four characters, trimming leading zeroes, such that it is read like this: 7 0000 0000 1289, which translates to 7.0.0.1289.
  • bdpx is the feature hash, and shows information captured by the Agent, such as bandwidth, dojo, perceived render time and basic XHR detection.

Automatic injection—tag placement rules

The following rules specify the criteria to determine a suitable location within an HTML document to inject the JavaScript Agent.

Please note, that the rule name appears in the Agent log in the following format: (NAME rule), for example (</head> tag rule).

Name Condition Action Overrules
(<?xml?> rule) an <?xml ...?> specification is encountered. Ignore it and continue to scan the document. non-<meta> tag

non-<head> tag

initial tag
initial tag A tag appears before <html> that is not one of the following:
  • <!DOCTYPE ...>
  • <html>
  • <link>
  • <meta>
  • <script>
  • <style>
Abort without injecting.
<html> tag The <html> tag is encountered. If a potential injection point is found earlier, inject there, and do not scan further. If there are multiples potential injection points, the earliest one wins.

Otherwise continue to scan the document
<!DOCTYPE> The <!DOCTYPE> tag is not <!DOCTYPE html>. Abort and do not inject.
comment The <!- comment -> tag is encountered. Ignore it and continue to scan the document. non-<meta> tag

non-<head> tag
<title> tag The <title> tag is encountered.
The rule is applicable to:
  • AppMon Agent platform until AppMon 2018 October.
  • Classic Agent platform.
Ignore everything until the </title> tag, then continue to scan the document. <body> tag
<title>/<noscript> tag The <title> or the <noscript> tag is encountered.
The rule is applicable only to AppMon Agent platform starting AppMon 2018 October.
Ignore everything until the </title> or the </noscript> tag, then continue to scan the document. <body> tag
<body> tag The <body> tag is encountered. Document scan stops. Any potential injection point found earlier is used. If there are multiples potential injection points, the earliest one wins.

If no rule matched earlier, inject after the <body>.
<script src> tag A <script src="..."> tag is found within <head>. If a potential injection point is found earlier, inject there, and do not scan further. If there are multiples potential injection points, the earliest one wins.

Otherwise, inject before this <script> tag and do not scan further.
non-<meta> tag

<base> tag
<link> tag A <link> tag is found within <head> that is not inline, i.e. it doesn't have the href="data:..." attribute.

The rule is deprecated for AppMon Agent platform starting AppMon 2018 October.
If a potential injection point is found earlier, inject there, and do not scan further. If there are multiples potential injection points, the earliest one wins.

Otherwise, inject before this <link> tag and do not scan further.
non-<meta> tag

<base> tag
flush Java only

Flush is called on the injecting stream/writer outside of the <head></head> section and a conditional injection awaits confirmation.
Discard the conditional injection point, propagate the flush and continue to scan the document for a new injection point. any conditional injection point found before by:

non-<head> tag
flush in <head> Java only
Flush is called on the injecting stream/writer inside <head></head> and conditional injection awaits confirmation.
Keep the injection point and continue to scan the document.

Disregard the flush.
<base> tag The <base> tag is encountered.
The rule is applicable to:
  • AppMon Agent platform until AppMon 2018 October.
  • Classic Agent platform.
Discard any conditional injection point found before. Continue to scan the document. any conditional injection point found before by:

non-<meta> tag

unclosed <meta>

non-<head> tag
<base>/<meta> tag Either the <base> or the <meta> tag is encountered.
The rule is applicable only to AppMon Agent platform starting AppMon 2018 October.
Discard any conditional injection point found before. Continue to scan the document. any conditional injection point found before by:

non-<meta> tag

unclosed <meta>

non-<head> tag
non-<meta> tag A tag is found within <head> that is neither <meta> nor <title>. Inject before it (conditional injection).

Continue to scan the document, in case this injection choice gets overruled.
non-<head> tag A tag is found after <html> but before <head> that is neither <head> nor <body>. Inject before it (conditional injection).

Continue to scan the document, in case this injection choice gets overruled.
unclosed <meta> The </head> tag arrives after a <meta> tag that doesn't get closed either by the closing </meta> tag or by the XML-style<meta ... /> tag. Add </meta> followed by the injection, both before the </head> (conditional injection).

Continue to scan the document, in case this injection choice gets overruled.
</head> tag The </head> tag encountered. If a potential injection point is found earlier, inject there, and do not scan further. If there are multiples potential injection points, the earliest one wins.

Otherwise, continue to scan the document.
end of file End of file is reached and scanning did not terminate before that. Do not perform an injection. any conditional injection point found before by:

non-<meta> tag

unclosed <meta>

non-<head tag
parse error The document's contents doesn't appear to exhibit the basic structure expected from HTML tags and attributes Document scan stops.

If a potential injection point is found earlier, inject there, and do not scan further. If there are multiples potential injection points, the earliest one wins.

If no rule provided an injection point earlier, do not perform an injection

Disabling JavaScript Agent injection for a specific files/locations

You can disable JavaScript Agent injection for specific files and/or locations.

To disable injection:

  1. Open the System Profile Preferences dialog box and select Agent group > Sensor Configuration item > User Experience, and click Properties.
  2. In the URI-specific injection behavior area, click +.
  3. Specify the file or location to be excluded from the injection, in the Condition and URI pattern fields. See User Experience sensor properties for parameters description.
  4. From the Injection Rule list, select do not inject on this agent, to allow agents from other groups to inject here or do not inject on this and subsequent agents, to completely disable agent injection.

Manual injection

If the preferable auto-injection is not possible you need to insert the initialization tag manually at design time as first script tag in <head>. Since the initialization tag and it's contained code varies depending on your application settings, it can easily be retrieved by using the JavaScript Agent initialization code REST API. The API is designed to be used during the build process of a web application and provides vital functionality the Agent needs to instrument a website. It is not recommended to request the snippet directly using a script tag, since this would unnecessarily decrease load times and require user privileges and direct access to the AppMon Server.

The initialization code performs operations to load the JavaScript Agent (either with or without the defer attribute) and updates it's configuration if required. It is not necessary to update the initialization tag every time you change the UEM configuration, though adjustments are applied faster for new visitors if you do so.

If you want to have less traffic to the instrumented server, you can manually download the JavaScript Agent file and locate it anywhere on your server. The Agent file differs depending on your configuration. You can retrieve it via the JavaScript Agent REST API. Be sure to configure the Agent location accordingly, so the initialization tag is capable of building the correct Agent tag. For statically served Agents you just need to inline the initialization tag. Upon configuration changes, just switch the Agent file.

You also need to adapt the properties of the User Experience sensor:

  1. Open the System Profile Preferences dialog box and select Agent group > Sensor Configuration item > User Experience, and click Properties.
  2. In the Injection Point point, select Inject manually.
  3. If the server providing the Agent and the one getting the monitoring data are different, you must configure the server, receiving data. Go to System Profile Preferences > User Experience > <application< > Web application > Advanced configuration and select the Send the Dynatrace monitor request to a foreign domain (CORS) check box.
  4. In the Monitor request path field, specify the receiving server. For Cordova/PhoneGap make sure this reference resolves through the domain whitelist and CORS is disabled. See PhoneGap Whitelist Guide for more information.