Skip to content

Commit

Permalink
feat(Browser): Clarified browser install doc to include four installa…
Browse files Browse the repository at this point in the history 
…tion methods (#18074)

Got my PR approval, so I'm merging it in.

* feat(Browser): Clarified browser install doc to include four installation methods

* feat(Browser): Trying tabbed version of the page

* style(Browser): Improved writing style based on peer feedback

* style(Browser): Updated based on feedback
  • Loading branch information
@paperclypse
paperclypse committed Jul 19, 2024
1 parent 7769a53 commit bcc10d1
Showing 1 changed file with 76 additions and 58 deletions.
134 changes: 76 additions & 58 deletions ...cs/browser/browser-monitoring/installation/install-browser-monitoring-agent.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,67 +20,92 @@ redirects:
freshnessValidatedDate: never
---

import browserInstallBrowser from 'images/browser_screenshot-crop_install-browser.webp'

To get started with <InlinePopover type="browser" />, you'll need to add our browser agent to the HTML of the views you want to monitor. The browser agent is a snippet of JavaScript code that monitors the performance of your app/site and sends that data to New Relic. You can add that code manually to your site, or use our APM agents to inject that code for you.
To get started with <InlinePopover type="browser" />, add our browser agent to the HTML of the views you want to monitor. The browser agent is a snippet of JavaScript code that monitors the performance of your site and sends that data to New Relic.

## Before you begin [#before-start]

Before starting, you may want to check that your browser app meets our [compatibility and requirements](/docs/browser/new-relic-browser/getting-started/compatibility-requirements-browser-monitoring).
If you haven't done so, you may want to check that your browser app meets our [compatibility and requirements](/docs/browser/new-relic-browser/getting-started/compatibility-requirements-browser-monitoring).

## Install the browser agent [#install]

There are four ways to install the browser agent. Depending on your specific needs, you can:

Want to use our API to programmatically monitor your applications? See [Browser monitoring with NerdGraph](/docs/apis/nerdgraph/examples/browser-monitoring-config-nerdgraph).
<Tabs>
<TabsBar>
<TabsBarItem id="1">
Get JavaScript via UI
</TabsBarItem>
<TabsBarItem id="2">
Install via APM
</TabsBarItem>
<TabsBarItem id="3">
Create JavaScript via NerdGraph
</TabsBarItem>
<TabsBarItem id="4">
Instrument multiple apps via npm
</TabsBarItem>
</TabsBar>

## Install the agent [#install]
<TabsPages>
<TabsPageItem id="1">

To install the browser agent: Go to <DNT>**[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents > Browser and mobile > Browser monitoring**</DNT> and follow the instructions.
Go to <DNT>**[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents > Browser and mobile > Browser monitoring**</DNT> and follow the instructions to generate the browser JavaScript snippet in the UI.

<ButtonGroup>
<ButtonLink
role="button"
to="https://onenr.io/0MRNpYqNqQn"
variant="primary"
>
Install browser monitoring
Get your browser snippet
</ButtonLink>
</ButtonGroup>

Once you have the snippet, paste it as close to the top of your `<head>` tag as possible, but after any position-sensitive META tags (such as `X-UA-Compatible` and `charset`).

If you have questions about the install process, see [Install methods](#choose-deployment).
For more detailed information about the placing the snippet, see [JavaScript placement requirements](/docs/browser/new-relic-browser/page-load-timing-resources/instrumentation-browser-monitoring#javascript-placement).

<img
title="Install browser"
alt="Install browser"
src={browserInstallBrowser}
/>
<Collapser
id="browser_delay"
title="Delay browser monitoring"
>

## Look for your data in New Relic [#generate-traffic]

When you're done installing the browser agent, wait a few minutes and look for the data in [our browser monitoring UI](/docs/browser/browser-monitoring/getting-started/browser-summary-page).
<Callout variant="caution">
Delaying instantiation causes the agent to miss information until it's fully loaded and initialized. The order of execution of these scripts does lead to some loss in instrumentation data from the start of page views.
</Callout>

If it's been more than 15 minutes and you're not seeing data, see [Troubleshooting](/docs/browser/browser-monitoring/troubleshooting/troubleshoot-your-browser-monitoring-installation/).
For possible performance or other reasons, you may wish to delay the initialization of the browser agent from the start of the page load cycle. You won't be able to use the `newrelic` API until the agent is fully initialized. This delay also creates incomplete data in your browser monitoring UI.

## What's next? [#whats-next]
Once the agent is fully initialized, it functions as expected. Any delay also affects when the agent wraps globals or subscribes to events relative to other libraries or code that affects captured data.

Ideas for next steps:
You can delay the agent initialization in these ways:

* View your app data on the [Summary page](/docs/browser/browser-monitoring/getting-started/browser-summary-page).
* Now that you've instrumented with the browser agent, go deeper with your data with our [Improve your website tutorial](/docs/journey-performance/guide-to-monitoring-core-web-vitals).
* Learn how to optimize your browser monitoring experience with our [Best practices guide for browser monitoring](/docs/new-relic-solutions/best-practices-guides/full-stack-observability/browser-monitoring-best-practices-guide).
* Add a `script-src` tag with the `async` attribute.
* Add a `script-src` tag with the `defer` attribute.
* Use dynamic import or chronologically late placement of the loader code.

## Install methods [#choose-deployment]
Your page's `src` must point to a valid agent loader version in our CDN. For example, the URL that always contains our current Pro+SPA agent release is `https://js-agent.newrelic.com/nr-loader-spa-current.min.js`. [CSP is required](/docs/browser/new-relic-browser/getting-started/compatibility-requirements-browser-monitoring#csp) to load external third-party scripts.

When it comes to adding the browser agent to your webpages, you have two deployment methods:
To determine when you can start calling the `newrelic` API, subscribe to an event at the global scope:

* APM + browser monitoring: Use one of our APM agents to auto-instrument browser monitoring
* Browser monitoring only: Add our browser agent manually as a JavaScript snippet to your front-end HTML
```js
window.addEventListener('newrelic', (evt) => {
if (evt.detail.loaded) {
// you can start using newrelic.interaction(), etc. now
}
})
```

</Collapser>
</TabsPageItem>
<TabsPageItem id="2">

Here's some guidance on these two methods.

### APM + browser monitoring [#apm-agent]
With an APM agent, you can deploy browser monitoring without manually adding the snippet to your code. When you restart the agent, it automatically uses the latest version of the browser agent.

If you're using an APM (application performance monitoring) agent to monitor the backend of your browser app, then we'd recommend using this method. We recommend this option for non-[SPA](/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring) apps because the APM agent will automatically deploy the browser agent to every page of your website and you'll automatically get the latest version of the browser agent whenever you restart your APM agent.
If you're using an APM (application performance monitoring) agent to monitor the backend of your browser app and you've got a non-[SPA](/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring) app, then we recommend using this method.

If you want to customize APM agent behavior, you can use our APM agent APIs. Here are those docs:
There are specific steps for each APM agent:

* [Go](/docs/agents/go-agent/features/install-new-relic-browser-go-apps)
* [Java](/docs/agents/java-agent/instrumentation/page-load-timing-java)
Expand All @@ -89,41 +114,34 @@ If you want to customize APM agent behavior, you can use our APM agent APIs. Her
* [PHP](/docs/agents/php-agent/features/page-load-timing-php)
* [Python](/docs/agents/python-agent/supported-features/page-load-timing-python)
* [Ruby](/docs/agents/ruby-agent/features/page-load-timing-ruby)
</TabsPageItem>
<TabsPageItem id="3">

### Browser monitoring only [#copy-paste]
If you'd prefer to create your browser snippet programmatically, you can do so via our NerdGraph, our GraphQL API.

Use this method if you can't use APM for whatever reason, like if your APM agent isn't supported for auto-injection (as is true for Node.js and some Java apps). If you use this method, the UI provides you with a customized JavaScript snippet at the end of the install process that and you can add to the HTML of any pages you want to monitor on your site.
For more on this, see our [NerdGraph tutorial](/docs/apis/nerdgraph/examples/browser-monitoring-config-nerdgraph/) to create a browser snippet and configure it.

Paste the JavaScript snippet within the HTML `<head>` tag of your page. The head tag typically handles third party scripts, fonts, and other elements that load on all your app pages, so you only need to paste it into one place. Paste it as close to the top of the `<head>` as possible, but after any position-sensitive META tags (such as X-UA-Compatible and charset). For more about the snippet placement, see [JavaScript placement requirements](/docs/browser/new-relic-browser/page-load-timing-resources/instrumentation-browser-monitoring#javascript-placement).
Once you have the snippet, add it to the `<head>` tag of your app.
</TabsPageItem>
<TabsPageItem id="4">

Alternatively, and while we STRONGLY recommend the inline script path, you can also use a src script to insert the agent in an `async` or `defer` manner. For caveats and details, continue below.
If you want to automate browser monitoring deployment across multiple web apps, you can use NerdGraph and our browser agent npm package to configure and deploy the agent as part of your application build process.

### Delaying browser monitoring [#delayed-script]
For more on this, see [instrument multiple apps with npm and NerdGraph](/docs/apis/nerdgraph/examples/combining-npm-nerdgraph/).
</TabsPageItem>
</TabsPages>
</Tabs>

<Callout variant="caution">
Delaying instantiation causes the agent to miss information until it is fully loaded and initialized. The order of execution of these scripts does lead to some loss in instrumentation data from the start of page views.
</Callout>
## What's next? [#whats-next]

For possible performance or other reasons, you may wish to delay the initialization of the browser agent from the start of the page load cycle. You won't be able to use the `newrelic` API until the agent is fully initialized. This delay also creates incomplete data in your browser monitoring UI.
When you've installed the browser agent, wait a few minutes and look for the data in [our browser monitoring UI](https://one.newrelic.com/nr1-core?filters=%28domain%3D%27BROWSER%27%20AND%20type%3D%27APPLICATION%27%29&state=1f7bae2d-dd3a-0027-3079-b60bcd19ded9&_gl=1*15f78ub*_ga*MTE0MTA2MTA5MS4xNzE4OTI0MDkw*_ga_R5EF3MCG7B*MTcyMTMxMzk2MC41Ny4xLjE3MjEzMTg2MzcuNDcuMS4xMDYwNTI3Njcw).

Once the agent is fully initialized, it functions as expected. Any delay also affects when the agent wraps globals or subscribes to events relative to other libraries or code that affects captured data.
If it's been more than 15 minutes and you're not seeing data, see [troubleshoot your browser installation](/docs/browser/browser-monitoring/troubleshooting/troubleshoot-your-browser-monitoring-installation/).

You can delay the agent initialization in these ways:
Once you're seeing browser data in the UI, here are some next steps on how you can get the most out that data:

* Add a `script-src` tag with the `async` attribute.
* Add a `script-src` tag with the `defer` attribute.
* Use dynamic import or chronologically late placement of the loader code.

Your page's `src` must point to a valid agent loader version in our CDN. For example, the URL that always contains our current Pro+SPA agent release is `https://js-agent.newrelic.com/nr-loader-spa-current.min.js`. [CSP is required](/docs/browser/new-relic-browser/getting-started/compatibility-requirements-browser-monitoring#csp) to load external third-party scripts.

To determine when you can start calling the `newrelic` API, subscribe to an event at the global scope:

```js
window.addEventListener('newrelic', (evt) => {
if (evt.detail.loaded) {
// you can start using newrelic.interaction(), etc. now
}
})
```
* [View a high-level summary of your app data](/docs/browser/browser-monitoring/getting-started/browser-summary-page).
* [Monitor your core web vitals](/docs/journey-performance/guide-to-monitoring-core-web-vitals).
* [Learn how to optimize your browser monitoring experience](/docs/new-relic-solutions/best-practices-guides/full-stack-observability/browser-monitoring-best-practices-guide).

<InstallFeedback />
<InstallFeedback />

0 comments on commit bcc10d1

Please sign in to comment.