Your data. Anywhere you go.

New Relic for iOS or Android


Download on the App Store    Android App on Google play


New Relic Insights App for iOS


Download on the App Store


Learn more

Close icon

Relic Solution: Using the Browser Agent API to capture custom attributes

levelup
rfb

#1

Adding user-defined attributes to PageView events

In this Level Up Solution, one common question customers ask me is “how can I send create and send custom attributes from my website to Insights”. This is possible using the Browser agent API (Browser Pro or Browser Pro Trial subscription required) we can create our custom attributes for PageView events which can then filter and view them in Insights.

Why do I need custom attributes?

The Browser agent has a predefined set of Browser API calls. These calls let you report additional data and sent this data to Insights. However, sometimes you may need additional data within the context of an initial page load or a route change(SPA agent required for route change), for example, user email address, user account information.

What are the prerequisites for custom attributes?

In order for the Browser agent to send custom attributes to Insights, the following must be true:

  • The Browser agent script need to be inline in the head tag, before other script tags.
  • The call needs to be made before the window load event fires (when that data is transmitted) in order for the attributes to be included in the PageView event.
  • PageView events require an Insights Pro subscription with your New Relic Browser subscription.

What are the parameters for custom attribute API call?

The API call requires two string values

  • $name Required. Name of the attribute. Appears as a column in the PageView event. It will also appear as a column in the PageAction event if you are using it.

  • $value Required. Value of the attribute. Appears as the value in the named attribute column in the PageView event.

Documentation
setCustomAttribute


Example

Here is an example of how you might call the Browser API and send it to Insights. I defined a custom attribute and named it 'userName, I inserted the API call in the header tag as the call needs to be made before the window load event fires.

<!DOCTYPE html>
    <html>
    	<head>
    		<meta charset="UTF-8">
    			<title>Title of the document</title>
    			<script type="text/javascript">window.NREUM||(NREUM={}),__nr_require=function(t,e,n){function r(n){if(!e[n]){var o=e[n]={exports:{}};t[n][0].call(o.exports,function(e){var o=t[n][1][e];return r(o||e)},o,o.exports)}return e[n].exports}if("function"==typeof __nr_require)return __nr_require;for(var o=0;o<n.length;o++)r(n[o]);return r}({1:[function(t,e,n){function r.......</script>
  				<script type="text/javascript">
    				newrelic.setCustomAttribute('userName', `Darren`);
    			</script>
		</head>
		<body>
    		Content of the document......
    	</body>
    </html>

Query Data with Insights*

The PageView event is a default event that the Browser agent reports to Insights. You can add custom attributes to the PageView event. Any custom attributes you add to the PageView event are also automatically added to the PageAction event.

View All Errors

SELECT `userName` from PageView WHERE `userName` IS NOT NULL and  appName = 'Browser Level Up Post' SINCE 24 hours ago

Counts of different types of errors

SELECT count(`userName`) from PageView  since 1 week ago FACET `userName

How many visits are we seeing for different browsers

SELECT count(*) from PageView where `userName` = 'Darren'  since 1 week ago FACET `userAgentName

Your Browser Pro subscription provides you with 8 days of Insights event retention for Browser events


Helpful Links


#2

Thanks for the post @ddoyle, it should answer some questions.

What would be the best approach to link the PageView session attribute with a back end transaction and what are the pros and cons of that method?


#3

@stefan_garnham - So the methods to link a PageView attribute with a Transaction event attribute are going to depend a little bit on if this is a copy/paste Browser app or a APM agent injected application.

For an APM agent injected Browser application, this is pretty easy and can be done almost automatically as documented here. (custom-attribute-forwarding from APM agent). This makes it pretty easy to do and allows you to group and query PageView and Transaction events in a single Insights query.

For a copy/pasted app, the data flow ends up needing to go manually from the APM agent where you generate some id or guid value while in the Transaction and use the New Relic Agent API to add that attribute to the Transaction and then also add it somewhere to the page (maybe in a hidden attribute or something) then scoop it up with the Browser agent and add to the PageView (or PageAction or Browser Interaction) via the Browser Agent API.

In both cases, the key is really just generating and ensuring some unique key/guid are attached to each event and then you are able to query across both of them to see the frontend and backend view of a user’s interaction with your systems.

As a third possible option, (especially for a SPA type app) you can generate the guid in the initial page view and then decorate your ajax calls with this attribute via a header or something and add it to the related Transaction events via the APM Agent API as well.

The specifics of each use case are going to depend on your specific implementation needs and shape of your application.