Insert custom data via New Relic Browser agent

Use the addPageAction Browser API call to capture events, actions, route changes, or any end-user interactions with your application. The addPageAction call adds an event named PageAction to Insights that contains the action name and any custom attribute names and values you capture along with it. The PageAction event also contains any custom attributes you added to the PageView event.

Add custom attributes to the PageView event so you can query or filter your data to answer more questions about your application.

Requirements

In order to send PageAction events to New Relic Insights, you must meet these requirements:

Requirement Comments
Subscription level This feature requires an Insights Pro or Browser Pro subscription. The instrumentation level setting for an application does not affect the availability of JavaScript API functions.
Agent version

Your New Relic Browser agent version must be 593 or higher.

Client browser version

To record PageAction events, the browser must support cross-domain XHRs.

Max events per cycle PageAction events are sent to Insights every 30 seconds, with a maximum of 60 events per 30-second harvest cycle, per browser. After the 60-event limit is reached, additional events are not captured for that cycle.
Event/attribute naming, data type, size Ensure you follow general requirements around event/attribute naming syntax, data types, and size.

Create PageAction events

To create a PageAction event:

  1. Ensure the Browser agent is installed for your app.
  2. Call the newrelic.addPageAction function in the relevant part of your application's JavaScript.
  3. Wait a couple minutes for the application to run and report relevant PageAction events to Insights.
  4. Use the Insights event explorer to query the PageAction event for the actionName attribute you used to capture the event (and any associated attributes you sent along with the action).

Add custom attributes to PageView event

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.

There are two ways to add custom attributes to the PageView event:

Use setCustomAttribute Browser API call

To add a custom attribute to the PageView event via the Browser agent, use the setCustomAttribute Browser API call. This allows you to capture an attribute to be annotated on any PageAction event.

Forward custom attributes from APM data

If you added custom attributes to the APM Transaction event via an APM agent, you can forward those custom attributes to the PageView event automatically:

  1. Insert custom attributes by following the agent-specific instructions.
  2. Enable attribute forwarding in your agent configuration file:

    Agent Instructions
    Java Add the attributes.enabled option in the browser_monitoring stanza and set it to true.
    .NET

    Add the <attributes enabled="true"> element as a child of the browserMonitoring element:

    <configuration xmlns="urn:newrelic-config">
      ...
      <browserMonitoring autoInstrument="true">
        ...
        <attributes enabled="true">
          ...
        </attributes>
      </browserMonitoring>
      ...
    <configuration>

    If you are using manual Browser instrumentation the attribute needs to be created before the GetBrowserTimingHeader() call.

    Node.js

    Add attributes: {enabled: true} to the browser_monitoring: { section of your app's newrelicjs configuration file.

    PHP Add the newrelic.browser_monitoring.attributes.enabled option and set it to true.
    Python Add the browser_monitoring.attributes.enabled option and set it to true.
    Ruby Add the browser_monitoring.attributes.enabled option and set it to true.

PageAction and PageView default attributes

For a full list of the default attributes that the PageAction and PageView events contain, see Browser default events and attributes.

Troubleshooting

Here are some troubleshooting tips:

Problem Comments
Custom attributes missing If your custom attributes do not appear in PageView events, verify you are calling setCustomAttribute before the Load event on your page. If the custom attribute is called after the page load occurs, it will not be visible in PageView.
PageAction events

If your PageAction events do not appear in New Relic Insights, check that your account is compatible.

If your account is compatible, check that you are not using reserved attribute names or invalid values.

For more help

Recommendations for learning more: