• EnglishEspañol日本語한국어Português
  • Log inStart now

Browser monitoring and the Ruby agent

With the Ruby agent, you can add browser monitoring agent instrumentation to your webpages either automatically or manually. To enable in the UI, follow the procedures to install the browser agent. Then follow the procedures in this section to set up the Ruby agent.


Automatic browser instrumentation is supported for most recent versions of Rails:

  • New Relic Ruby agent (version 3.0.1 or higher)
  • For automatic instrumentation: Rails 2.3 or higher
  • For manual instrumentation: Rails 2.0 to 2.2

Use auto-instrumentation

Automatic instrumentation works with Rack, and requires Rails 2.3 or higher.

Configure the agent to automatically instrument pages with end user monitoring scripts, by adding or editing the following flag in newrelic.yml.

auto_instrument: true

This is the simplest way to monitor end users. The Ruby agent examines each page from your application and automatically injects the browser JavaScript in the header. Auto-instrumentation works for environments that support Rack. For performance reasons the agent scans only the first 50k of your application's response for the header instrumentation point. In cases where a X-UA-Compatible meta tag is present and the <head> tag is longer than 50k, auto-instrumentation will fail gracefully.

Auto-instrumentation will look for an X-UA-Compatible meta tag and insert the JavaScript directly after it. If the auto-instrumentation cannot find an X-UA-Compatible meta tag, it will insert after the opening head tag, and failing that it will insert after the opening body tag. If any of these tags are wrapped in conditionals or comments, the automatic instrumentation will likely fail.

If auto-instrumentation fails to correctly instrument your application’s pages, then you must manually instrument via agent API.

Manually instrument via agent API

If you are using Rails 2.1 to 2.2 or cannot use auto-instrumentation, you can still set up end user monitoring manually by including appropriate scripts in your pages. Use the New Relic Ruby agent's API to generate the script to be inserted into your pages.

For example, to modify your application's template to call the agent, use:

<%= ::NewRelic::Agent.browser_timing_header rescue "" %>
# existing template code ...

CSP Nonce support

CSP Nonce usage in our browser instrumentation is supported in version 7.1.0+ of the Ruby agent. To use a nonce with the browser instrumentation, you must disable browser monitoring auto instrumentation and use the manual instrumentation via the agent API.

You may now pass a nonce as an argument into the API method to allow the agent to insert the nonce into the browser instrumentation. For example, NewRelic::Agent.browser_timing_header(nonce).


If you do not see any browser data being reported, view the HTML source and confirm two blocks of script similar to this in your HTML head:

<script type="text/javascript">

If these are not present, check the auto-instrumentation settings or the placement of manual instrumentation in your template files.

In versions of the Ruby agent prior to 3.7.0, <%=::NewRelic::Agent.browser_timing_footer rescue "" %> also needed to be called as close to the bottom of the document as possible. With 3.7.0, all the required script is included by browser_timing_header. browser_timing_footer returns an empty string for compatibility.

Disable auto-instrumentation

The default value of auto-instrument is true (even when unspecified). To disable auto-instrumentation, set this flag to false.

To disable auto-instrumentation only for certain controllers or controller actions, use newrelic_ignore_enduser. Server-side instrumentation will be unaffected by this call.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.