New Relic Browser and the Java agent

With the Java agent, you can add New Relic Browser instrumentation to your webpages either automatically or manually. Ensure you have the latest Java agent release, and add newrelic-api.jar to your web application's lib directory if necessary (for example, to manually instrument New Relic Browser). To enable Browser in the user interface, see Browser settings. Then follow the procedures in this document to set up the Browser agent.

Use auto-instrumentation (Jasper JSPs)

The Java agent automatically adds Browser instrumentation to JSPs compiled with the Apache Jasper compiler, which is the default compiler for Tomcat, Jetty, and Glassfish.

If you use auto-instrumentation, the Java agent instrumentation process occurs during the Jasper JSP compilation. Auto-instrumentation works for most JSP applications. The agent examines each JSP that defines an <html> tag and automatically injects calls to the New Relic API that generates the JavaScript header and footer required for Browser monitoring.

  • Place the New Relic header tag after the first non-meta and non-title tag in the <head> section.
  • Place the New Relic footer tag before the </body> end tag.

Recommendation: In order to get the most accurate timing information, place meta tags immediately after the initial <head> tag. Place the <script> and <link> tags in the head section after all meta tags.

For more information about configuring JSP pages, see New Relic Java agent JSP best practices.

If pages do not compile or are not valid HTML, then you will need to turn off auto-instrumentation for the failing pages and follow the procedures to manually instrument using the agent API.

Disable auto-instrumentation on all pages

The default value of auto_instrument is true (even when unspecified). To disable auto-instrumentation on all pages:

  1. Set the auto_instrument flag under browser_monitoring to false in your newrelic.yml.
    browser_monitoring:
      auto_instrument: false
  2. Restart your application.
  3. Flush the app server's work cache.

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

Disable auto-instrumentation on specific pages

To 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:

 browser_monitoring:
   disabled_auto_pages: /WEB-INF/jsp/testpage_1.jsp, /WEB-INF/jsp/testpage_2.jsp

Manually instrument via agent API

If your application server does not use the Jasper JSP compiler (WebSphere and WebLogic), or if you are not using JSPs, you can still manually embed scripts to instrument end user monitoring. The New Relic Java agent has an API to generate the JavaScript header and footer that needs to be inserted into your page.

When manually instrumenting your code, disable auto-instrumentation by adding or editing the following flag in newrelic.yml:

 browser_monitoring:
   auto_instrument: false

To enable your web application to use the API, see Java agent API.

Insert the header JavaScript at the beginning of the <head> tag, but after the meta tags. Insert the footer JavaScript before the </body> tag. The footer includes timing metrics, so it is important to call getBrowserTimingFooter near the end of request handling so the metrics will be accurate.

Here is an example of the general format:

<!DOCTYPE html>
<html>
<head>
 <meta tags>
 {PLACE NEW RELIC HEADER TAG HERE}
 <script and link tags>
</head>
<body>
   ...
{PLACE NEW RELIC FOOTER TAG HERE}
</body>
</html>
JSP manual instrumentation
<%= com.newrelic.api.agent.NewRelic.getBrowserTimingHeader() %>
 ...
 ...
 <%= com.newrelic.api.agent.NewRelic.getBrowserTimingFooter() %>
Raw HTML manual instrumentation
 PrintWriter out = response.getWriter();
 ...
 out.println(com.newrelic.api.agent.NewRelic.getBrowserTimingHeader());
 ...
 ...
 out.println(com.newrelic.api.agent.NewRelic.getBrowserTimingFooter());
Thymeleaf 2.1 or higher manual instrumentation
<head>
...
<div th:remove="tag" th:utext="${T(com.newrelic.api.agent.NewRelic).getBrowserTimingHeader()}"></div>
</head>
<body>
...
<div th:utext="${T(com.newrelic.api.agent.NewRelic).getBrowserTimingFooter()}"></div>
</body>
ColdFusion CFML page manual instrumentation
<cfobject type="Java" class="com.newrelic.api.agent.NewRelic" name="newRelic"/>
<cfset header = "newRelic.getBrowserTimingHeader()"/>
<cfoutput>#header#</cfoutput>
...
...
<cfset footer = "newRelic.getBrowserTimingFooter()"/>
<cfoutput>#footer#</cfoutput>
Java Server Faces (JSF) frameworks

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

Play Groovy template manual instrumentation
${com.newrelic.api.agent.NewRelic.getBrowserTimingHeader().raw()}
...
...
${com.newrelic.api.agent.NewRelic.getBrowserTimingFooter().raw()}
Play 2.2 or higher Scala template manual instrumentation

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

libraryDependencies += "com.newrelic.agent.java" % "newrelic-api" % "3.x.x"

In main.scala.html add the following:

@Html(com.newrelic.api.agent.NewRelic.getBrowserTimingHeader())
...
...
@Html(com.newrelic.api.agent.NewRelic.getBrowserTimingFooter())
Play 2.1 Scala template manual instrumentation

Add to Build.scala (Substitute the current version):

appDependencies += "com.newrelic.agent.java" % "newrelic-api" % "2.x.x"

In main.scala.html

@Html(com.newrelic.api.agent.NewRelic.getBrowserTimingHeader())
...
...
@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:

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

Call the NewRelic API in your velocity template:

$NewRelic.getBrowserTimingHeader()
...
...
$NewRelic.getBrowserTimingFooter()
Enabling Browser on Apache Velocity

Here is an example of how to enable New Relic Browser using FFM TOMCAT:

  1. Disable browser auto-instrumentation in your newrelic.yml file, located in your newrelic directory.
    browser_monitoring:
     auto_instrument:false
    
  2. 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
    
  3. Add newrelic-api.jar to the classpath of Tomcat, typically in .../tomcat/bin/setenv.sh:

    CLASSPATH=$CLASSPATH:/opt/newrelic/newrelic-api.jar
    

    OR

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

  4. In each web 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.

  5. In each webapp, edit the Velocity template that is used by the other pages in the application. Add this tag within the <head> stanza before any <link> and <script> declarations, and after any meta tags:
    $NewRelic.getBrowserTimingHeader()
  6. Add this tag within the <body> stanza as the line right before the </body> tag, at the very bottom of the body:

    $NewRelic.getBrowserTimingFooter()
    
  7. Restart the Tomcat server:
    • If you are using Linux/Unix, add the following command line to the Users/Tomcat/bin directory:

      ./shutdown.sh
      ./startup.sh
      
    • If you are using Windows, go to your Users/Tomcat/bin directory, and add the following command line:
      % shutdown.bat
      % startup.bat
      

Verify log file

Check the log file to verify that the agent is instrumenting your JSPs correctly. Set the log_level setting in newrelic.yml to log_level: finer.

When the JSP engine compiles a JSP, you will see messages like this:

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

The JavaScript is not inserted into the HTML response until after the Agent has connected to the server. When it does you will see the log message about Browser:

May 17, 2011 9:43:21 AM NewRelic INFO: Real user monitoring is enabled with auto instrumentation

After that you will see these messages when the JSP is invoked:

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

You will see these messages when the header and footer API is called:

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="https://d7p9czrvs14ne.cloudfront.net/11/eum/rum.js";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","staging-beacon-1.newrelic.com","8512b4d93f",7449,"M1RTYksFDEYDUxdcDgoeZERQSwhGEmQGRhVL",0,413])</script>

For more help

Additional documentation resources include:

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.