Oracle Cloud Infrastructure Documentation

Configure Additional APM Browser Agent Injection Settings

Once this APM Browser Agent feature is enabled, it's possible to customize the default settings and add additional ones depending on your requirements.

Update ProbeConfig.acml file

In ProbeConfig.acml file, there is a section called INJECTION with additional settings available to adjust how the browser agent injection is performed if desired. Each setting has a comment explaining what it does. 

INJECTION:
  ### Exclusion Settings ###
  # URLs that end in these extensions will be skipped for browser agent injection.
  excluded_extensions:
...
You can use these settings to:

  • Determine which pages should or should not have the browser agent injected into them.

  • The location in the page where the browser agent should be injected in.

  • Know how to respond to cases where the application server does not provide necessary information for the browser agent injection. For example: charset and MIME type of the page.

All of these settings can be updated without having to restart the application server.

The default behavior is the following:
  • The browser agent will be injected after the <head> tag of the HTML page.

    This is controlled by the inject_location_tag and inject_before settings.

    If the tag is missing, it will append to the end of the file. This is controlled by inject_mode setting.

  • Only "text/html" and "application/xhtml+xml" MIME types will be considered for injection.

    This is controlled by the valid_mime_types setting.

  • URLs that end in particular file extensions such as json, txt, gif and others, will skip browser agent injection.

    This is controlled by the excluded_extensions setting.

  • Applications with particular context roots will skip browser agent injection.

    This is controlled by the excluded_context_roots setting.

Update BrowserAgentTemplate.txt

This file determines what HTML is injected into the page.

The default behavior for APM Agent 1.3 and higher version is the following:
<script type="application/javascript">
window.apmrum = (window.apmrum || {});
window.apmrum.serviceName='@@SERVICE_NAME@@';
window.apmrum.webApplication='@@WEB_APPLICATION@@';
window.apmrum.ociDataUploadEndpoint='@@UPLOAD_ENDPOINT@@';
window.apmrum.OracleAPMPublicDataKey='@@PUBLIC_KEY@@';
</script>
<script type="application/javascript"async crossorigin="anonymous"src="@@UPLOAD_ENDPOINT@@/static/jslib/apmrum.min.js"></script>

The values surrounded by @@ are replaced before injection occurs, and they are values acquired from AgentConfig.properties file.

This template can be adjusted to account for browser agent-side configurations mentioned in the other sections of this documentation, such as the window.apmrum.rewriteRules. For information, see Hide Personally Identifiable Information.

Any changes made to this file will be picked up automatically, and will not require a restart of the application server.

Update Mime types

In order for injection to succeed the mime-type specified in the "Content-Type" header in the HTTP Response should always contain "text/html". There should be no problems/issues when this header is set properly.

However, some applications respond with an incorrect mime-type or no mime-type at all. When no mime-type is provided the Browser Agent injection uses the "default_mime_type" parameter in the ProbeConfig.acml file to decide what to do. The default value for this parameter is set to "text/plain" therefore injection will not happen in all such cases where the header is missing.

If you want injection in these cases then you should change the "default_mime_type" parameter to "text/html" to have that injection allowed.

In the opposite case, when the "Content-Type" header in the HTTP Response does contain "text/html", but the actual content is not HTML, we use a sophisticated signature/heuristic based content analysis algorithm to decide whether to inject or not. If we determine the content to be of a type that is not HTML, then we will not inject anything into the stream.