UEM Health Check

Important

Make sure that the HTTP headers x-dtPostBody, x-dtHealthCheck, and x-dtAgentId do not get blocked in your environment. The UEM Health Check needs them to work properly.

In the AppMon Client Start Center, click the Select System Profile list box to select the System profile containing the applications to check. Then click Monitoring > UEM Health Check > Check your UEM configuration to run a UEM Health Check on those applications.

Basic checks

When you perform a UEM Health Check, AppMon executes a number of basic checks. These do not depend on any application-specific settings. AppMon also executes a check when applications are not selected for the UEM Health Check process.

License check

  • Volume Expired: If the UEM visits volume expires, you must redeem another voucher or purchase additional volume. See Manage UEM Visits Volume for more information.

  • Volume Exhausted: If the number of page visits in the license is expired, see Volume Expired to redeem or purchase a UEM Volume.

  • No UEM Volume Included in License: To purchase a UEM Volume, see Volume Expired.

  • License State Error: If the license is expired, invalid, not activated, locked to a different machine, or unknown, click here to contact support.

Agent check

This checks the availability of Agent Groups in the System Profile, and the mapping of Agents to Agent Groups. (Tiers)

  • Broken Sub-Agents: If there are configuration problems such as those related to shared memory, then the sub-Agent reports as broken. Find the reason and details in the Agent logs.

  • No Agent Group / Tier: Agent Groups / Tiers are not defined for the System Profile. To open System Profile preferences, double-click a System Profile or click Edit System Profile in the Configuration Panel (if available) and define at least one Agent Group / Tier with a mapping for your Agents.

  • No Agent Connected: An Agent is not connected to the Agent Group. Use the following tasks to diagnose the issue:
    • Check the mappings in your Agent Groups and make sure that at least one Agent is connected for each defined application.
    • Make sure that at least one Agent Group has an active and placed User Experience Sensor with at least one Agent connected.

Application checks

For each application that you select in the UEM Health Check wizard, AppMon performs the following application-specific checks:

If one of these application-specific checks terminates with an error, AppMon skips all dependent checks.

UEM enabled check

This check makes sure that capturing UEM data from the browser is enabled. It fails if capturing is enabled only for server-side data, or if capturing is disabled completely.

Change settings in System Profile preferences > User Experience.

  • UEM Disabled: UEM capturing is disabled completely for the checked application.

Make sure the slider is in the desired position.

  • Server Side Data Only - No Browser (UEM) Data: UEM capturing is set to capture only server-side data for the checked application.

  • Server Side Data Only - UEM Volume Exhausted for Application: UEM data capturing is turned off because there is no more UEM volume available for this application. This means either all remaining volume is reserved for other applications or that a reservation which applies to this application has been exhausted.

Injection check

This check verifies that the JavaScript Agent is injected correctly. Inject the JavaScript Agent into all pages manually or automatically. For automatic injection, a number of options restrict the injection.

Configure JavaScript Agent injection in System Profile preferences > User Experience. To configure for all applications, click the Default application tab and make your configuration settings Under JavaScript Agent. For Individual applications, Select the application specific tab. See System Profile - User Experience > JavaScript Agent for more information.

The JavaScript Agent is correctly injected if the src-attribute of the first script-tag in the HTML response body matches a certain file name pattern.

To Health Check each application, enter a URL. Click Start Center > Monitoring > Check your UEM configuration under UEM Health Check. If you have a web server master Agent, the connected sub-Agent may be from an earlier version and reports a different configuration.

Errors

The injection check may fail with the following messages:

  • Invalid Test URL: The specified test URL is not in a valid format.

  • Agent Matches to a Different System Profile: The provided validation URL does not match the current System Profile. Provide a validation URL which belongs to the profile.

  • Error During Health Check Request: The injection check requests the test page, but fails. Verify that you are connected to the Internet and that you can connect to the URL.

  • Error Requesting Test Page: The HTTP request to the specified test page returns with an HTTP status code other than 200 (OK). Check the URL. You may have to specify a proxy or a firewall may block requests.

  • UEM Sensor Inactive: The affected Agents' User Experience Sensor is set to an inactive state. Open the Agent's Sensor configuration and set the User Experience Sensor's capturing mode to active.

  • Server not Instrumented by Agent: Verify that the test page URL points to a server with an AppMon Agent installed. If you have an instrumented Java-based application server such as Apache Tomcat, set the agent's User Experience sensor to active.

  • Test Page is Invalid HTML: To inject the JavaScript Agent, the page must be valid HTML. The Agent tags the start of an HTML syntax violation automatically. The JavaScript Agent injects properly even if the document contains a violation tag. The document may have been assembled by multiple injected servlets and/or filters.

  • No Injection Point Found on Test Page: No injection point found for JavaScript Agent on this page, likely due to invalid HTML or unexpected end in transmission.

  • Test Page Does Not Have Content Type Header: No content-type header value is set, so the JavaScript Agent is not injected in the response body.

  • Test Page Has an Invalid MIME Type: Page does not have one of the two accepted MIME-Types: text/html or application/xhtml+xml. The JavaScript Agent is not injected. Verify that the URL points to an HTML page and not to an image, swf, or other non-HTML content.

  • Web or Application Server Agent Does Not Have a JavaScript Agent Available for Injection: The Agent may not have a connection to the Master Agent or to a Collector. Verify that the respective Agent appears in the Agent Overview Dashboard.

  • Test Page is a Special Page: The specified URL for the test page points to a page that servers use internally, for example bea_wls_ used by BEA Weblogic, where the JavaScript Agent is not injected. Specify a different test page URL.

  • Test Page is Special: The test URL belongs to a special web request by the Web Server Agent, such as the AppMon Agent or bandwidth test images. This cannot verify the correct injection of the JavaScript Agent. Specify a different URL.

  • Test page is Not HTML: The test page is not HTML, based on the file extension (for example .gif, .jpg, .png). Specify a different URL.

  • Manual Injection is Enabled; No Agent Has Been Injected by Developer: Verify that the JavaScript Agent is included in the HTML page and that it is the first script tag on the page.

  • JavaScript Agent Capturing is Disabled in Application Configuration: In the applicable System Profile Preferences, select > User Experience > Application Specific Settings tab to configure a JavaScript Agent injection for all applications or for each one separately.

  • JavaScript Agent Capturing is Disabled in Sensor configuration: In the applicable System Profile Preferences, select the desired Agent Group and choose Sensor Placement to configure a JavaScript Agent injection.

See Sensor Properties > User Experience for more information.

  • JavaScript Agent Injection is Disabled but JavaScript Agent is Injected: The JavaScript Agent is turned off for this web or app server, however the JavaScript Agent is still injected. This may be due to the following reasons:
    • The page is cached somewhere. Verify that the HTML pages for this application are not cached, or UEM may not work.
    • The JavaScript Agent was injected manually. Disable manual injection. See Sensor Properties > User Experience for more information.

  • Injection Disabled Because Dynatrace Header is On the Request: If the request and response, respectively, has an AppMon header, this is used for a Health Check.

  • Invalid Page Encoding: There is no injection due to incompatible encoding (must be UTF-8 or UTF-16 compatible).

  • Injection Threshold Reached: There is no injection because the content length is too long.

  • Chunked Transfer Encoding: The injection is disabled for pages that are delivered using chunked transfer encoding.

  • Agent Already Injected: There is no injection because the JavaScript Agent is already injected. This could be due to a (redundant) manual injection attempt.

  • UEM Disabled on Agent: UEM is disabled in the Agent configuration. The configuration is not communicated correctly between the server and Agent. This is because the Agent configuration (as stored on the server) is checked before the Injection check is executed, and this test did not fail.

  • JavaScript Agent URL/File Name Malformed: The URL of the injected JavaScript Agent is malformed. The correct URL / file name of the JavaScript Agent should look like this: dtagent_ax_6000500005176.js. This may occur if you inject manually, or delete a JS plugin.

  • JavaScript Agent has wrong version format: The URL of the injected JavaScript Agent does not have the correct format. A JavaScript agent URL >= 6.5 should look like this: dtagent_ax_6000500005176.js. All lower versions should look like: dtagent630_ax_5176.js.

  • UEM Capturing Disabled on Agent: UEM is enabled in the application's UEM settings, but the responding Agent does not retrieve the changed settings. Verify that the communication between the AppMon Server and the Agent, and/or any Collectors works correctly.

  • Servlet-Specific Injection: Servlet not Provided: The injection point of the User Experience Sensor is set to a specific servlet or filter. This may not exist, or the associated URL pattern is not part of the provided validation URL. Verify that the communication works between the AppMon Server and Agent.

  • Servlet-Specific Injection: Response-Header Missing: The injection point of the UEM Sensor is set to a custom servlet that is different from the one that responds to the Health Check request. This can occur when the Agent's UEM settings are not current. Verify that the communication between server and Agent works.

  • Web Server: UEM License Expired: The Web Server Agent is not injected because its license is expired. Extend or renew your license.

  • Failed for Unknown Reasons: If AppMon could not detect automatically why the injection did not work, the following reasons may explain why:

    • The test URL does not belong to this application. Make sure that the test URL is correct.
    • The page is cached somewhere such as a proxy or a CDN. Make sure that HTML pages for this application are not cached, else UEM may not work.
    • The UEM Health Check was not able to determine why the injection failed. Click here to contact support.
  • Wrong Version Format: The injected JavaScript Agent has the wrong version format. AppMon 6.5 and later has an updated new version format. See JavaScript Agent Configuration for more information. This may be a programming error. Click here to contact support.

Warning

The test may fail if the JavaScript Agent is not injected correctly. It may also return a number of warnings when the Agent is correctly injected. These warnings are a sign of a condition that may prevent AppMon from tracking visitors.

  • Server Agent Does Not Support Health Check: The Agent does not support the Health Check feature. This may occur if an earlier version of the Agent is installed. The Health Check can execute, but it may not find all the errors in the configuration. Update the server with the latest version of the Agent.

  • Injection Percentage Restrictions are Enabled: The injection of the JavaScript Agent is limited by percentage restrictions. The Agent is only injected in the specified percentage of requests.

  • Browser Injection Restrictions are Enabled: Injection restrictions based on browser type and version are enabled so certain browsers are not tracked.

  • Do Not Track Header is Enabled: Most modern browsers support this functionality.

  • Injection Restrictions Based on IP Ranges are Enabled: Only users with IP addresses that match the specified rules are tracked. The AppMon Client IP is excluded when you use a normal browser.

  • Manual Injection is Enabled: The application developers should manually inject the JavaScript Agent in all pages to be captured.

  • Multiple JavaScript Agents Found: If more than one JavaScript Agent is found in the validation page, the requested validation page is probably injected manually, by the application developers, and automatically, by the web server or application server.

  • AgentId Not On Response Header: The connected Agent(s) ID is not on the Health Check's response header. This occurs if the Agent is not updated automatically to version 5.5 or later.

  • Discard An Injection Due to an Unexpected Flush() Call: Some Java applications and frameworks use flush() to send portions of an HTML page to the browser before its entire content is generated. Rarely, this makes it necessary to discard an injection in the flushed portion of the HTML code. In this case, the JavaScript Agent gets injected at a later, potentially sub-optimal position.

Agent version check

Use this to check the Agent version in the Health Check's web request.

  • Agent(s) Not Up-To-Date: The Agents listed in the UEM Health Check run an earlier version than the AppMon Server and were not updated properly by the bootstrap Agent. Verify that the communication works between the AppMon Server and Agents.

  • The Health Check's HTTP Request Returned an Invalid Response From the Connected Agents: The following are some possible causes.
    • Missing response header which should contain the IDs of the connected Agents. This can happen when one of the connected Agents runs on a version earlier than 5.5.
    • Invalid response header modified by the connected Agents.
    • Agent that is unknown to the AppMon Server. Agent is connected to a different AppMon Server or none at all.

  • Master Agent Unknown or Not Found: One of the connected sub-Agent's master Agent is either not available or unknown to the server.

  • Versions For Sub-Agent and Master-Agent Do Not Match: The master Agent and one of the connected sub-Agents run on different versions. The following are some possible causes.
    • After installing an AppMon Update, the Web Server Agent or the master Agent are not restarted or are unable to retrieve the latest Agent version from the AppMon Server.
    • If you use IIS under Windows Vista, or later, the installation directory C:\Program Files may cause a shared memory problem.

JavaScript Agent delivery

This check verifies that a valid JavaScript Agent is injected into the requested web page.

  • The Agent is not delivered: The Agent URL is not reachable. The may be due to one of the following:
    • The Agent path is not handled by a web server with an installed Agent. A typical case is a Java server with an application that runs in a sub-path such as /app/ but no root application is available. The JavaScript Agent fails when requested from the root path.
    • The Agent path is not handled by the servlet engine itself, but by a custom part of the app server. (WebSphere sometimes does that for static content).
    • The Agent path is blocked by a firewall.

  • Agent Empty: The Agent URL is reachable but does not return content. Some firewalls or proxy servers return empty content, instead of a 404 HTTP error. Configure your firewall or proxy server to correctly serve the JS Agent URL.

  • Agent is Gzipped But was Requested Uncompressed: This occurs when a web server compresses the content for all requests, although the content was not requested with the Accept-encoding: gzip header enabled. This may be problematic for clients who do not support gzipped content. This can be caused by a servlet filter, an Apache module, or an ISAPI filter that does not respect the Accept-encoding header correctly.

  • Invalid Agent Content: The delivered Agent contains invalid JavaScript content which may trigger JS errors on the injected page and, therefore, is not a valid JS Agent. This can be caused by a Web server returning a default page instead of a HTTP 404 error when a page is not found. Typically, this is because the requests to the JavaScript Agent are not allowed by a firewall, proxy, or the web server.

  • Gzipping is Disabled: Sending JavaScript Agent in a compressed format is deactivated in the UEM Sensor configuration. This leads to more overhead when downloading the JavaScript Agent, but this setting may be necessary to avoid double gzipping of the Agent.

  • Agent not Gzipped Although Requested Compressed: This occurs when the Accept-encoding header is not passed to the AppMon Agent. It may not be a problem. It may indicate that gzipping does not work for this application. This may impact performance.

  • Agent is not Gzipped Although Gzip Header is Set: The Agent is requested as gzipped and the respective response header (content-disposition) is set, but the response does not contain gzipped content. There may be a problem in the web server configuration. This occurs when a web server compresses all responses and disregards the Content-disposition response header set to gzip.

Deactivate sending the JavaScript Agent gzipped in the UEM Sensor configuration, as a workaround.

  • JavaScript Agent is Gzipped Twice: The delivered JavaScript Agent is gzipped twice. Contact your system administrator or support.

AppMon monitor request check

This check verifies if the monitor request path is valid. See JavaScript Agent - Configuration for more information.

In the applicable System Profile Preferences, select > User Experience > Application Specific Settings tab to configure a JavaScript Agent injection for all applications or for each one separately.

A request is valid when both the http status code and the response body match specific values.

  • The HTTP status must always equal 200 (OK).
  • The response body must match the following pattern with valid status values OK, FL and valid server values Java, Web server:
status(server)

The following is an example of a valid request:

   HTTP Status: 200
   Response Body: OK(Java)

The AppMon Monitor request check may fail with the following messages:

  • Response Code Invalid: The HTTP request to the Monitor URL returned with an HTTP status code other than 200 (OK). Verify the specified Monitor URL. There may be a firewall that blocks requests to that URL.

  • Response Body Invalid: The HTTP request to the specified Monitor URL was successful but returned with an invalid response body. This may be due to an invalid Monitor URL. The web server redirects to a default error page and has an HTTP status 200 (OK).

  • Request Body Invalid: This error occurs if the Agent cannot read the parameters of the monitor signal request. This may cause a problem with UEM data, such as missing User Action PurePaths. Your firewall may block POST requests, or truncate or encode them. If you're not able to change these settings, select Split large signals inside your application's UEM settings. As a result, the requests are sent with the GET method.

  • Cookie Problem: During the Health Check execution, there is a problem with cookies when you access the Monitor URL. The following are a list of causes:
    • The required AppMon cookie dtCookie cannot be created. This problem is discovered when the Set-Cookie header is not found on the response headers. Verify the cookie policies of your application server or webserver.
    • The found session-cookie is invalid. Update the Agents versions.
    • The cookie's domain is set to an invalid value.

  • Unsafe Cookie Content: The injected application server may have a problem with unsafe cookie content; for example when a cookie contains characters like '<', '>' or '$'. The JavaScript agent is using a cookie named dtSa, which might be available if an action with a redirect happens. It stores information about the previous page, such as the encoded URL. Depending on the characters in that URL, the cookie might contain the previously listed problematic characters. If the monitored application does not include switches between different subdomains, the agent can be configured to use SessionStorage instead of a cookie. For AppMon 6.5.10 and later, the Disable subdomain source action support setting is available in debug mode. Contact support for information on selecting this setting.

Known Problems

Using GZIP compression on server

This occurs when custom or multiple GZIP-filters are installed on the application server. Install one GZIP-filter only or use an application URL which does not use a GZIP-filter.