From 16a070db05fc7e634bc720b74986176be7c7683e Mon Sep 17 00:00:00 2001 From: Kayla Reopelle Date: Fri, 24 May 2024 09:48:16 -0700 Subject: [PATCH 1/3] chore: Update Ruby browser agent doc * Remove references to unsupported versions of Rails and the agent * Incorporate the new Ralis CSP nonce feature * Update wording --- .../features/new-relic-browser-ruby-agent.mdx | 70 ++++++++++++++----- 1 file changed, 51 insertions(+), 19 deletions(-) diff --git a/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx b/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx index 26ecb4db15b..d7a60a5db78 100644 --- a/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx +++ b/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx @@ -12,36 +12,34 @@ redirects: - /docs/agents/ruby-agent/features/page-load-timing-ruby --- -With the Ruby agent, you can add [browser monitoring agent](/docs/browser/new-relic-browser/getting-started/introduction-new-relic-browser) instrumentation to your webpages either automatically or manually. To enable browser monitoring in the UI, follow the procedures to [install the browser agent](/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent). Then follow the procedures in this section to set up the Ruby agent. +With the Ruby agent, you can inject the [browser monitoring agent](/docs/browser/new-relic-browser/getting-started/introduction-new-relic-browser) into your webpages either automatically or manually. By default, if the Ruby agent detects Javascript, it automatically installs the Browser agent. -## Requirements +If you prefer to add the browser monitoring agent manually or want to learn about the options to install the browser agent, [consult the browser agent installation guide](/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent). -Automatic browser instrumentation is supported for most recent versions of Rails: +## Requirements -* New Relic Ruby agent ([version 3.0.1 or higher](/docs/release-notes/agent-release-notes/ruby-release-notes)) -* For automatic instrumentation: Rails 2.3 or higher -* For manual instrumentation: Rails 2.0 to 2.2 +Automatic browser instrumentation is available [for all supported versions of the Ruby agent.](https://docs.newrelic.com/docs/apm/agents/ruby-agent/getting-started/ruby-agent-eol-policy/) You must set your content security policy to `'unsafe-inline'` or give the agent [a CSP nonce](#csp-nonce-support). ## Use auto-instrumentation [#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`. +New Relic's default configuration enables browser monitoring auto-instrumentation: ```yaml browser_monitoring: 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 `` tag is longer than 50k, auto-instrumentation will fail gracefully. +This is the simplest way to monitor end users. The Ruby agent examines each page of your application when it loads and automatically injects the browser JavaScript in the header. Auto-instrumentation works for environments using Rack. For performance reasons, the agent only scans the first 50k lines of your application's response for the header instrumentation point. In cases where a `X-UA-Compatible` meta tag is present and the `` tag is longer than 50k, auto-instrumentation will fail gracefully. + +Auto-instrumentation looks for an `X-UA-Compatible` meta tag and inserts the JavaScript directly after it. If the auto-instrumentation can't find an `X-UA-Compatible` meta tag, it will insert after the opening head tag. 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. -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. +Auto-instrumentation will not occur on pages with an attachment 'Content-Type' or when it detects streaming requests. -If auto-instrumentation fails to correctly instrument your application’s pages, then you must [manually instrument](#manual_instrumentation) via agent API. +If auto-instrumentation fails to correctly instrument your application's pages, then you must [manually instrument](#manual_instrumentation) via agent API. ## Manually instrument via agent API [#manual_instrumentation] -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. +You can 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. The API injects this script into your pages. For example, to modify your application's template to call the agent, use: @@ -54,24 +52,58 @@ For example, to modify your application's template to call the agent, use: ## 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. +The browser agent can be instrumented automatically if the content security policy is set to 'unsafe-inline'. If you want to use a [CSP Nonce](https://content-security-policy.com/nonce/), you may need to add some manual configuration. + +### Rails CSP Nonce + +[Rails versions 5.2+ include a feature to set a CSP nonce using an API.](https://guides.rubyonrails.org/security.html#adding-a-nonce) On Ruby agent versions 9.10.0+, the Rails CSP nonce will be automatically detected and applied to the browser agent injection script. + +You can disable this feature by updating your `newrelic.yml` to the following: + +```yaml + browser_monitoring: + content_security_policy_nonce: false +``` + +Or set the environment variable, `NEW_RELIC_BROWSER_MONITORING_CONTENT_SECURITY_POLICY=false`. + +### API call + +You can pass a CSP nonce to the `NewRelic::Agent.browser_timing_header` API in Ruby agent versions 7.1.0+. + +When passing a nonce to this method, you must disable browser monitoring auto-instrumentation and use manual instrumentation via the agent API. + +Update your `newrelic.yml` to: + +```yaml +browser_monitoring: + auto_instrument: false +``` + +Or set the environment variable, `NEW_RELIC_BROWSER_MONITORING_AUTO_INSTRUMENT=false`. 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)`. ## Troubleshooting -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: +If browser data ins't reported, view the HTML source and confirm two blocks of script similar to this are in your HTML head: ```html ``` -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. +If these aren't present, check: +* The auto-instrumentation settings +* The placement of manual instrumentation in your template files +* The way you're applying a nonce ## Disable auto-instrumentation [#disable_instrumentation] The default value of [`auto-instrument`](/docs/agents/ruby-agent/configuration/ruby-agent-configuration#browser_monitoring) 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`](/docs/agents/ruby-agent/installation-configuration/ignoring-specific-transactions#page-load-timing-rum). Server-side instrumentation will be unaffected by this call. +```yaml +browser_monitoring: + auto_instrument: false +``` + +To disable auto-instrumentation only for certain controllers or controller actions, use [`newrelic_ignore_enduser`](/docs/agents/ruby-agent/installation-configuration/ignoring-specific-transactions#page-load-timing-rum). Server-side instrumentation isn't affected by this call. From 8dfefa5d67e621bc646fe2d47352380caa7e959c Mon Sep 17 00:00:00 2001 From: "Kayla Reopelle (she/her)" <87386821+kaylareopelle@users.noreply.github.com> Date: Fri, 24 May 2024 11:34:45 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Hannah Ramadan <76922290+hannahramadan@users.noreply.github.com> --- .../agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx b/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx index e723100b776..2211f988657 100644 --- a/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx +++ b/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx @@ -87,7 +87,7 @@ You may now pass a nonce as an argument into the API method to allow the agent t ## Troubleshooting -If browser data ins't reported, view the HTML source and confirm two blocks of script similar to this are in your HTML head: +If browser data isn't reported, view the HTML source and confirm two blocks of script similar to the following are in your HTML head: ```html From b5b2355e0b7591f100ff5f06c9115194a4c66cb2 Mon Sep 17 00:00:00 2001 From: nbaenam Date: Mon, 27 May 2024 12:45:29 +0200 Subject: [PATCH 3/3] style(Ruby agent): Added some TW edits --- .../features/new-relic-browser-ruby-agent.mdx | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx b/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx index 2211f988657..596198cbfdb 100644 --- a/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx +++ b/src/content/docs/apm/agents/ruby-agent/features/new-relic-browser-ruby-agent.mdx @@ -1,15 +1,15 @@ --- title: Browser monitoring and the Ruby agent tags: - - Agents - - Ruby agent - - Features + - Agents + - Ruby agent + - Features metaDescription: Instrumentation for your New Relic Ruby agent to set up New Relic browser monitoring. redirects: - - /docs/agents/ruby-agent/features/new-relic-browser-ruby-agent - - /docs/ruby/real-user-monitoring-in-ruby - - /docs/ruby/page-load-timing-in-ruby - - /docs/agents/ruby-agent/features/page-load-timing-ruby + - /docs/agents/ruby-agent/features/new-relic-browser-ruby-agent + - /docs/ruby/real-user-monitoring-in-ruby + - /docs/ruby/page-load-timing-in-ruby + - /docs/agents/ruby-agent/features/page-load-timing-ruby freshnessValidatedDate: never --- @@ -17,11 +17,11 @@ With the Ruby agent, you can inject the [browser monitoring agent](/docs/browser If you prefer to add browser monitoring manually or want to learn about options to install the browser agent, [consult the browser agent installation guide](/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent). -## Requirements +## Requirements [#requirements] -Automatic browser instrumentation is available [for all supported versions of the Ruby agent.](https://docs.newrelic.com/docs/apm/agents/ruby-agent/getting-started/ruby-agent-eol-policy/) You must set your content security policy to `'unsafe-inline'` or give the agent [a CSP nonce](#csp-nonce-support). +Automatic browser instrumentation is available [for all supported versions of the Ruby agent](/docs/apm/agents/ruby-agent/getting-started/ruby-agent-eol-policy/). To make sure your environment is ready for automatic instrumentation, review the [browser monitoring compatibility and requirements guide](/docs/browser/new-relic-browser/getting-started/compatibility-requirements-browser-monitoring). -## Use auto-instrumentation [#auto_instrumentation] +## Use auto-instrumentation [#auto-instrumentation] New Relic's default configuration enables browser monitoring auto-instrumentation: @@ -32,13 +32,13 @@ browser_monitoring: This is the simplest way to monitor end users. The Ruby agent examines each page of your application when it loads and automatically injects the browser JavaScript in the header. Auto-instrumentation works for environments using Rack. For performance reasons, the agent only scans the first 50k lines of your application's response for the header instrumentation point. In cases where a `X-UA-Compatible` meta tag is present and the `` tag is longer than 50k, auto-instrumentation will fail gracefully. -Auto-instrumentation looks for an `X-UA-Compatible` meta tag and inserts the JavaScript directly after it. If the auto-instrumentation can't find an `X-UA-Compatible` meta tag, it will insert after the opening head tag. 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. +Auto-instrumentation looks for an `X-UA-Compatible` meta tag and inserts the JavaScript directly after it. If the auto-instrumentation can't find an `X-UA-Compatible` meta tag, it will insert it after the opening head tag. If it can't, it will insert it after the opening body tag. If any of these tags are wrapped in conditionals or comments, the auto-instrumentation is likely to fail. Auto-instrumentation will not occur on pages with an attachment 'Content-Type' or when it detects streaming requests. -If auto-instrumentation fails to correctly instrument your application's pages, then you must [manually instrument](#manual_instrumentation) via agent API. +If auto-instrumentation fails to correctly instrument your application's pages, you will need to [manually instrument](#manual-instrumentation) using the Agent API. -## Manually instrument via agent API [#manual_instrumentation] +## Manually instrument via agent API [#manual-instrumentation] You can 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. The API injects this script into your pages. @@ -51,13 +51,13 @@ For example, to modify your application's template to call the agent, use: ``` -## CSP Nonce support +## CSP Nonce support [#csp-nonce-support] -The browser agent can be instrumented automatically if the content security policy is set to 'unsafe-inline'. If you want to use a [CSP Nonce](https://content-security-policy.com/nonce/), you may need to add some manual configuration. +If the content security policy is set to 'unsafe-inline', you can automatically instrument the browser agent. If you want to use a [CSP Nonce](https://content-security-policy.com/nonce/), you may need to add some manual configuration. -### Rails CSP Nonce +### Rails CSP Nonce [#rails-csp-nonce] -[Rails versions 5.2+ include a feature to set a CSP nonce using an API.](https://guides.rubyonrails.org/security.html#adding-a-nonce) On Ruby agent versions 9.10.0+, the Rails CSP nonce will be automatically detected and applied to the browser agent injection script. +[Rails versions 5.2+](https://guides.rubyonrails.org/security.html#adding-a-nonce) include a feature to set a CSP nonce using an API. On Ruby agent versions 9.10.0+, the Rails CSP nonce will be automatically detected and applied to the browser agent injection script. You can disable this feature by updating your `newrelic.yml` to the following: @@ -68,7 +68,7 @@ You can disable this feature by updating your `newrelic.yml` to the following: Or set the environment variable, `NEW_RELIC_BROWSER_MONITORING_CONTENT_SECURITY_POLICY=false`. -### API call +### API call [#api-call] You can pass a CSP nonce to the `NewRelic::Agent.browser_timing_header` API in Ruby agent versions 7.1.0+. @@ -85,7 +85,7 @@ Or set the environment variable, `NEW_RELIC_BROWSER_MONITORING_AUTO_INSTRUMENT=f 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)`. -## Troubleshooting +## Troubleshooting [#troubleshooting] If browser data isn't reported, view the HTML source and confirm two blocks of script similar to the following are in your HTML head: @@ -98,9 +98,9 @@ If these aren't present, check: * The placement of manual instrumentation in your template files * The way you're applying a nonce -## Disable auto-instrumentation [#disable_instrumentation] +## Disable auto-instrumentation [#disable-instrumentation] -The default value of [`auto-instrument`](/docs/agents/ruby-agent/configuration/ruby-agent-configuration#browser_monitoring) is `true` (even when unspecified). To disable auto-instrumentation, set this flag to `false`. +The default value of [`auto-instrument`](/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#browser-monitoring) is `true` (even when unspecified). To disable auto-instrumentation, set this flag to `false`. ```yaml browser_monitoring: