Oracle Cloud Infrastructure Documentation

Troubleshooting APM Browser Agent Injection

Users may encounter various errors during the APM Browser Agent injection configuration. Causes and recommended actions for such errors are listed below.

Page is not automatically injected with the Browser Agent

Possible Causes:

  • APM Browser Agent injection is not enabled correctly.

    Action: Review how to enable the feature. For details, see Enable APM Browser Agent Injection.

  • The application server is not supported by APM.

    Action: Confirm that the application server is supported by checking the OCI APM certification matrix.

  • The page is not served by the Application server where the APM Agent is running.

    Action: Check to see if the page is truly served by the Application server where the APM Agent is running.

    • If the page is served from a cache (e.g., CDN) or a Webserver (e.g., Oracle HTTP Server or Apache) then the content server must have the injected page.

    • If the page is cached by the browser, try performing a hard refresh (e.g., Shift and Reload) or clear your browser's cache.

  • Check if the HTML page contains "valid" HTML. The W3C consortium has many rules and validators that you can check for page validity.

    Action: Some simple ways to check are the following:

    • In your browser, view the page source and check that it starts with either "<html", "<!--" or "<!doctype html".

      If it starts with some other tag and you still need to force the injection, then you can add that tag to the "valid_html_start" parameter in the ProbeConfig.acml file.

    • Using your browser's development tools, check to see if the "Content-Type" header in the HTTP response contains "text/html".

  • If there's no clear error message available, you can do the following:

    • Set the log level to DEBUG in the AgentConfig.properties file by adding the com.oracle.apm.agent.logging.level=DEBUG parameter.

      After that, reload the page in the browser and look for messages in the Agent.log file containing the string "DEBUG <Filter>".

    • Review the ProbeConfig.acml file and make sure it doesn't hit any of the exclusion settings under the INJECTION section. In particular, review the following configurable settings:
      • excluded_extensions
      • excluded_context_roots
      • excluded_patterns
  • Additional functionality information:

    1. The HTML must be generated by a Servlet or a JSP where the APM Java Agent is running. If you generate HTML in a filter or via some other mechanism, it is unlikely to work.

    2. The Servlet must make a call to getOutputStream() and write the HTML into a valid ServletOutputStream OR it must make a call to getWriter() and write the HTML into a valid PrintWriter.

      The Oracle InjectionFilter must be a part of the servlet chain (added to application's filter chain automatically). If any other filter is used to bypass it, then the injection will not be possible.

    3. Transfer-encoding. The Agent must be able to intercept and inject before the HTML response stream is transformed by:
      • Transfer-Encoding: chunked.
      • Transfer-Encoding: compress.
      • Transfer-Encoding: deflate.
      • Transfer-Encoding: gzip.

Page is not rendered successfully

Action: First, try disabling the APM Browser Agent injection using the AgentConfig.properties file. For details, see Disable APM Browser Agent Injection. After doing that, wait about a minute, and retry the page in question. You do not need to restart the Application Server.