--- title: Report browser monitoring custom events and attributes source: https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/report-browser-monitoring-custom-events-attributes --- You can use browser monitoring in New Relic to add [custom events and attributes](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/report-custom-event-data). ## Custom attributes [#attributes] Add custom attributes to all browser events so you can query or filter your data to answer more questions about your application. ## Custom events [#events] Use the browser API's [`recordCustomEvent`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/recordCustomEvent) method to capture any event with custom attribution. ## Page actions [#overview] Use the browser API's [`addPageAction`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action) call to capture events, actions, route changes, or any end-user interactions with your application. The `addPageAction` call adds an event named `PageAction` that contains the action name, metadata relating to your page and any custom attribute names and values you capture along with it. ## Prerequisites [#requirements] In order to report `Custom` events, verify these prerequisites: | **Requirement** | **Comments** | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent version | Your browser monitoring agent version must be [1.277.0 or higher](https://docs.newrelic.com/docs/browser/new-relic-browser/installation-configuration/upgrading-browser-agent#checking). | | Client browser version | To record `Custom` events, the browser must [support cross-domain XHRs](https://docs.newrelic.com/docs/browser/new-relic-browser/getting-started/compatibility-requirements#browser-types). | | Events per cycle | `Custom` events are buffered with other Browser events and are sent every 30 seconds. If 1,000 total events are observed, the agent will harvest the buffered events immediately, bypassing the harvest cycle interval. | | Event/attribute naming, data type, size | Ensure you follow [general requirements](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/data-requirements#general) around event/attribute naming syntax, data types, and size. | In order to report `PageAction` events, verify these prerequisites: | **Requirement** | **Comments** | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent version | Your browser monitoring agent version must be [593 or higher](https://docs.newrelic.com/docs/browser/new-relic-browser/installation-configuration/upgrading-browser-agent#checking). | | Client browser version | To record `PageAction` events, the browser must [support cross-domain XHRs](https://docs.newrelic.com/docs/browser/new-relic-browser/getting-started/compatibility-requirements#browser-types). | | Events per cycle | `PageAction` events are buffered with other Browser events and are sent every 30 seconds. If 1,000 events are observed, the agent will harvest the buffered events immediately, bypassing the harvest cycle interval. | | Event/attribute naming, data type, size | Ensure you follow [general requirements](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/data-requirements#general) around event/attribute naming syntax, data types, and size. | ## Create custom events [#creating-custom-events] To create a `custom` event: 1. Ensure the [browser agent is installed](https://docs.newrelic.com/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent) for your app. 2. Call the [`newrelic.recordCustomEvent`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/record-custom-event) function in the relevant part of your application's JavaScript. 3. Wait a couple minutes for the application to run and report relevant `custom` events under the eventType you specified. 4. Run a NRQL query of the event that includes the `eventType` attribute you used to capture the event (and any associated attributes you sent along with the event). - For example, if you sent a `custom` event with an `eventType` of `Foo` and an attribute of `bar: 123`, you could run a query like this: ```sql SELECT * FROM Foo WHERE bar = 123 ``` ## Create PageAction events [#creating-pageactions] To create a `PageAction` event: 1. Ensure the [browser agent is installed](https://docs.newrelic.com/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent) for your app. 2. Call the [`newrelic.addPageAction`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/newrelicaddpageaction-browser-agent-api) 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. 4. Run a [NRQL query](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/nrql-query-examples/insights-query-examples-new-relic-browser-spa) of the `PageAction` event that includes the `actionName` attribute you used to capture the event (and any associated attributes you sent along with the action). - For example, if you sent a `PageAction` event with an `actionName` of `Foo` and an attribute of `bar: 123`, you could run a query like this: ```sql SELECT * FROM PageAction WHERE actionName = 'Foo' AND bar = 123 ``` ## Add custom attributes to Browser events [#custom-attributes] You can add custom attributes to all Browser events. Any custom attributes you add using the `setCustomAttribute` API will be added to all events captured. There are two ways to add custom attributes: **Use `setCustomAttribute` browser API call** To add a custom attribute to Browser events via the browser agent, use the [`setCustomAttribute`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/newrelicsetcustomattribute-browser-agent-api) browser API call. **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](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/add-custom-attributes-apm-data). 2. Enable attribute forwarding in your agent configuration file: | Agent | Enable attribute forwarding | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Go | To enable attributes, add this to your config (disabled by default): ````go cfg.BrowserMonitoring.Attributes.Enabled = true ``` Then add the attributes you want to include: ```go cfg.BrowserMonitoring.Attributes.Include = []string{"request.*"} ``` ```` | | Java | Add the [`attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-browser-attributes-enabled) option in the `browser_monitoring` section and set it to `true`. | | .NET | Add the [``](https://docs.newrelic.com/docs/agents/net-agent/installation-configuration/net-agent-configuration#browser-attributes) element as a child of the `browserMonitoring` element: ````xml ... ... ... ... ``` If you are using [manual browser instrumentation](/docs/agents/net-agent/features/page-load-timing-net#manual_instrumentation) the attribute needs to be created before the `GetBrowserTimingHeader()` call. ```` | | Node.js | Add [`attributes: {enabled: true}`](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration#browser-debug-enabled) to the `browser_monitoring` section of your app's `newrelic.js` configuration file. | | PHP | Add the [`newrelic.browser_monitoring.attributes.enabled`](https://docs.newrelic.com/docs/agents/php-agent/attributes/enabling-disabling-attributes#cfg-browser-attributes-enabled) option and set it to `true`. | | Python | Add the [`browser_monitoring.attributes.enabled`](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-configuration#cfg-browser-attributes-enabled) option and set it to `true`. | | Ruby | Add the [`browser_monitoring.attributes.enabled`](https://docs.newrelic.com/docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration#browser_monitoring-attributes-enabled) option and set it to `true`. | ## Important considerations and best practices include: You should aim to limit the total number of custom event types to approximately five. Custom event types are meant to be used to encapsulate high-level categories. For example, you might create an event type called Gestures that contains many events with various purposes. Avoid using event type to name custom events. Create event types to house a category of data and use attributes within that category to differentiate events. While you can create numerous custom events, it's important to keep your data manageable by limiting the number of event types reported. ## Included Attribution Custom browser events are decorated with the following attributes intended to help you understand the context of the browser environment when the event occurred: **Custom event attributes** | Attribute | Description | | ---------------- | ------------------------------------------------------------------------- | | appId | The New Relic entity's application ID. | | appName | The New Relic entity's application name. | | asn | Autonomous System Number. | | asnLatitude | The latitude associated with the ASN | | asnLongitude | The longitude associated with the ASN | | asnOrganization | The organization associated with the ASN | | city | The city where the event occurred. | | countryCode | The country code where the event occurred. | | currentUrl | The URL where the event occurred, which includes soft navigations | | deviceType | The type of device on which the event occurred. | | entityGuid | The New Relic entity's GUID. | | name | The transaction name if supplied by APM | | pageUrl | The URL where the event occurred. | | regionCode | The region code where the event occurred. | | session | The session identifier tied to the user session where the event occurred. | | sessionTraceId | The session trace ID tied to the page load where the event occurred. | | timestamp | The unix timestamp of the event. | | userAgentName | The name of the user agent where the event occurred. | | userAgentOS | The operating system of the user agent where the event occurred. | | userAgentVersion | The version of the user agent where the event occurred. | ## Troubleshooting Here are some troubleshooting tips: | **Problem** | **Comments** | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Custom attributes missing | If your custom attributes do not appear on `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 on `PageView`. | | `PageAction` events | If your `PageAction` events do not appear when you query, review the [requirements](#requirements). If the requirements are met, check that you're not using [reserved attribute names or invalid values](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/inserting-custom-events-insights-api#limits). | | `Custom` events | If your `custom` events do not appear when you query, review the [requirements](#requirements). If the requirements are met, check that you're not using [reserved attribute names or invalid values](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/inserting-custom-events-insights-api#limits). |