• EnglishEspañol日本語한국어Português
  • Log inStart now

Introduction to custom events and attributes

One of the ways to report custom data to New Relic is using custom events and/or custom attributes.


For event and attribute formatting requirements and best practices, see our data limits and requirements docs.

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 solutions for reporting custom data are reporting custom events and custom attributes. There are several ways to accomplish this, depending on your New Relic implementation and tools, and we'll go into more detail on this later in this doc. But first, here are some common use cases for why you'd use either custom events or custom attributes.

Use cases for custom attributes

Custom attributes are often used to add important business and operational context to existing events. For example, for New Relic , you might create a custom attribute to track the user name associated with a slow or failing request. This would then allow you to create queries and custom charts to analyze that data.

Custom attributes are a good option when you're using a New Relic solution (like APM, browser, , infrastructure, and synthetic monitoring) and want to decorate existing events with your own metadata.

Use cases for custom events

Whereas adding custom attributes adds metadata to an existing event, a custom event creates an entirely new event type. Create custom events to define, visualize, and get alerts on additional data, just as you would with any data we provide from our core agents. Custom events can be inserted through our agent APIs or directly via our Event API.

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 vary widely. Basically they're used for any type of activity that an organization deems important and that's not already being monitored. For example:

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

Use custom events

After creating a custom event, you can use it in a standard NRQL query the same way you would use any other event.

FROM YourCustomEvent

You can also use custom events with the metrics and events explorer by finding your custom events in the interface and selecting them to write your queries.

Send custom events and attributes

Methods for sending custom events and attributes include:


How to send custom data

APM agent

Use agent APIs to report custom events and custom attributes.

Browser monitoring agent

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

Forward APM agent custom attributes to the PageView event.

Event API

To report custom events not associated with other New Relic features, 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 other options for reporting custom data, see Custom data.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.