Instrument browser monitoring with Java agent API

Browser monitoring gives you visibility into how your users are interacting with your Java application by using a JavaScript snippet (or "agent") to instrument your app's webpages. To enable browser monitoring in our user interface, follow the procedures to install the Browser agent. For example, you can:

  • Enable an APM-monitored app.
  • Enable with the copy/paste method.
  • Enable by using the REST API.

You can also manually instrument your webpages by using the Java agent API, as explained in this document.

Use Java agent API

If your framework does not allow you to enable browser monitoring from our UI, with the copy/paste method, or by using our REST API, you can manually instrument monitoring for your webpages. To do this, use our Java agent API.

  1. Make sure you are using the latest Java agent version.
  2. Disable auto-instrumentation.
    Disable auto-instrumentation on all pages
    1. Set the auto_instrument flag under browser_monitoring to false in your newrelic.yml.
        auto_instrument: false
    2. Restart your application.
    3. Flush the app server's work cache.

    Flushing the work cache forces the app server to recompile JSPs, which is when auto-instrumentation occurs.

    Disable auto-instrumentation only on specific pages

    Use the disabled_auto_pages flag under the browser_monitoring stanza. For example, to disable auto-instrumentation on testpage_1.jsp and testpage_2.jsp, use the following:

       disabled_auto_pages: /WEB-INF/jsp/testpage_1.jsp, /WEB-INF/jsp/testpage_2.jsp
  3. Access the Java agent API class by adding newrelic-api.jar to your application class path.
  4. Add the appropriate method to start time tracking, for example: com.newrelic.api.agent.NewRelic.getBrowserTimingHeader().

    Add the appropriate method to stop time tracking, for example: com.newrelic.api.agent.NewRelic.getBrowserTimingFooter().

    Find the appropriate methods based on the framework you are using:

    JSP manual instrumentation
    Insert the header as close to the top of <head> tag as possible but after the meta tags. Insert the footer before the </body> tag.
    <!DOCTYPE html>
    <meta charset="utf-8">
    <meta name="description" content="Example header and footer call">;
    <%= com.newrelic.api.agent.NewRelic.getBrowserTimingHeader() %>
    <%= com.newrelic.api.agent.NewRelic.getBrowserTimingFooter() %>
    Raw HTML manual instrumentation
    To manually instrument using raw HTML, include page load timing code in the HTTP response.
    Thymeleaf 2.1 or higher manual instrumentation
    <div th:remove="tag" th:utext="${T(com.newrelic.api.agent.NewRelic).getBrowserTimingHeader()}"></div>
    <div th:utext="${T(com.newrelic.api.agent.NewRelic).getBrowserTimingFooter()}"></div>
    ColdFusion CFML page manual instrumentation
    <cfobject type="Java" class="com.newrelic.api.agent.NewRelic" name="newRelic"/>
    <cfset header = newRelic.getBrowserTimingHeader() />
    <cfset footer = newRelic.getBrowserTimingFooter() />
    Java Server Faces (JSF) frameworks

    Manual instrumentation is not available with JSF. To insert the Browser JavaScript snippet into your app's webpages, use the copy/paste method.

    Play Groovy template manual instrumentation
    Play 2.2 or higher Scala template manual instrumentation

    Add the following to build.sbt, substituting the latest agent version for 3.x.x:

    libraryDependencies += "" % "newrelic-api" % "3.x.x"

    In main.scala.html, add the following:

    Play 2.1 Scala template manual instrumentation

    Add the following to Build.scala, substituting the lastest agent version for 2.x.x:

    appDependencies += "" % "newrelic-api" % "2.x.x"

    In main.scala.html, add the following:

    @Html(com.newrelic.api.agent.NewRelic.getBrowserTimingFooter())**Manual instrumentation with Apache Velocity Template Language (VTL)**
    Apache Velocity Tools manual instrumentation

    If you are using Velocity Tools, define a NewRelic tool in toolbox.xml:


    Call the NewRelic API in your velocity template:

    Apache Velocity manual instrumentation
    1. To ensure that all of your Browser page views are not grouped under a single /velocity transaction (and to avoid metric grouping issues), disable your enable_auto_transaction_naming setting in your newrelic.yml file:

      enable_auto_transaction_naming: false
    2. Add newrelic-api.jar to the classpath of Tomcat, typically in .../tomcat/bin/



      Add the reference to this jar file to the end of an existing CLASSPATH=... line within that file.

    3. In each app, find WEB-INF/tools.xml and add the following tag:

      <toolbox scope="application"> <tool class="com.newrelic.api.agent.NewRelic" key="NewRelic" /> </toolbox>

      If a <toolbox scope="application"> tag already exists, put the <tool ... /> within the tag.

    4. In each app, edit the Velocity template that the other pages in the application use. Add this tag within the <head> stanza before any <link> and <script> declarations and after any meta tags:
    5. Add this tag within the <body> stanza as the line right before the </body> tag, at the very bottom of the body:

    6. Restart the Tomcat server:
      • If you are using Linux/Unix, add the following command line to the Users/Tomcat/bin directory:

      • If you are using Windows, go to your Users/Tomcat/bin directory, and add the following command line:
        % shutdown.bat
        % startup.bat
  5. Check the log file to verify that the agent is instrumenting correctly. Set the log_level setting in newrelic.yml to log_level: finer and check for the following messages:
    When the JSP engine compiles a JSP
    May 17, 2011 9:33:18 AM NewRelic FINE: Compiling JSP: /jsp/header.jsp
    May 17, 2011 9:33:18 AM NewRelic FINE: Injecting browser timing header into: /jsp/header.jsp
    May 17, 2011 9:33:36 AM NewRelic FINE: Compiling JSP: /jsp/footer.jsp
    May 17, 2011 9:33:36 AM NewRelic FINE: Injecting browser timing footer into: /jsp/footer.jsp
    After the agent connects to the server
    The JavaScript snippet is not inserted into the HTML response until after the agent connects to the server.
    May 17, 2011 9:43:21 AM NewRelic INFO: Real user monitoring is enabled with auto instrumentation
    When New Relic invokes the JSP
    May 17, 2011 9:43:23 AM NewRelic FINER: Injecting browser timing header in a JSP.  Content type is text/html
    May 17, 2011 9:43:23 AM NewRelic FINER: Injecting browser timing footer in a JSP.  Content type is text/html
    May 17, 2011 9:43:23 AM NewRelic FINEST: Got browser timing header in NewRelic API: <script>var    NREUMQ=[];NREUMQ.push(["mark","firstbyte",new Date().getTime()]);(function(){var d=document;var e=d.createElement("script");e.type="text/javascript";e.async=true;e.src="";var s=d.getElementsByTagName("script")[0];s.parentNode.insertBefore(e,s);})();</script>
    May 17, 2011 9:43:23 AM NewRelic FINEST: Got browser timing footer in NewRelic API: <script type="text/javascript" charset="utf-8">NREUMQ.push(["nrf2","","8512b4d93f",7449,"M1RTYksFDEYDUxdcDgoeZERQSwhGEmQGRhVL",0,413])</script>

For more help

If you need more help, check out these support and learning resources: