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.

Requirements

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:

• Ensure you follow limits and requirements around event/attribute data types, naming syntax, and size.
• The amount of data you have access to over time depends on your data retention policy.

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 browser monitoring, 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, mobile monitoring, 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.

SELECT *
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:

For other options for reporting custom data, see Custom data.