• /
  • Log in
  • Free account

Report custom events and attributes

One of the ways to report custom data to New Relic is with custom events and attributes.

Have questions about why you'd use custom data? See Introduction to custom data.


For event and attribute formatting requirements and best practices, see Limits and requirements.

Avoid rate limits

Reporting a large number of custom events and/or attributes can cause degraded query performance. It may also result in approaching or passing data collection rate limits. For optimal performance, first think about what data you want to analyze, and then create only the events and/or attributes necessary to meet these specific goals.

Be aware of the following data and subscription requirements for inserting and accessing custom data:

Example use cases

Two popular custom data solutions are custom events and custom attributes. There are several ways to accomplish this (more on that later in this doc), depending on your New Relic implementation and tools.

Here are some common use cases for implementing custom events and attributes.

Using custom attributes

Custom attributes are often used to add important business and operational context to existing events.

Business context might include:

  • Customer token
  • Customer market segment
  • Customer value classification
  • Workflow control values not obvious in the URIStem
  • User/product/account privilege context

Operational context might include:

  • Which feature flags were used
  • What datastore was accessed
  • What cache was accessed
  • What errors were detected and ignored (fault partitioning)

Using custom events

Event data is one of New Relic's four core data types. We recommend reading that definition to understand what we mean by "event" and why that data type is most used for reporting specific types of activity.

The use cases for custom events varies widely: basically they are used for any type of activity that an organization deems important and that is not already being monitored. A couple examples:

  • An event might represent an activity involving multiple actions, like a customer purchasing a certain combination of products.
  • An event might record backup activity. For example, they might set up reporting of events that represent production backups of their SOLR instances into an event table, with a timestamp of when it occurred, which cluster, and the duration.

Send custom events and attributes

Methods for sending custom events and attributes include:


How to send custom data

APM agent

Use APM agent APIs to report custom events and custom attributes.

Browser monitoring agent

Add custom attributes to the PageView event via the browser API call addCustomAttribute. Send PageAction event and attributes via browser API.

Forward APM agent custom attributes to PageView event.

Event API

To report custom events not associated with other New Relic products, use the Event API.

Infrastructure monitoring agent

Add custom attributes to default Infrastructure events. Use the Flex integration tool to report your own custom event data.

Mobile monitoring agent

Use the mobile agent API to send custom events and attributes.

Synthetic monitoring

Add custom attributes to the SyntheticCheck event via the $util.insights tools.

For ways to report other types of custom data, see:

Extend data retention

To learn how to extend how long events are retained in your account, see our documentation about event data retention.

Create issueEdit page
Copyright © 2022 New Relic Inc.