Insert custom events via New Relic APM agents

New Relic APM lets you record custom event data via the New Relic language agent APIs, which you can then query in New Relic Insights.

Custom events sent via the agent API are not compatible with high security mode.

Record a custom event

Sending a lot of events can increase the memory overhead of the agent. Additionally, posts greater than 1MB in size will not be recorded regardless of the maximum number of events.

The New Relic agent sends event data to Insights as part of its normal harvest cycle every 60 seconds. The recommended way to verify if your custom events are showing up in Insights is to use the event data explorer to look for the event.

To record a custom event, follow the procedure for your New Relic language agent:

To add a custom Insights event to apps monitored by the New Relic Go agent, use RecordCustomEvent.

Custom event collection is enabled by default in Java agent version 3.13.0 or higher. To send custom events, simply call the relevant API. For example:

Map<String, Object> eventAttributes = new HashMap<String, Object>();
NewRelic.getAgent().getInsights().recordCustomEvent("MyCustomEvent" eventAttributes);

The first argument defines the name of your event type, and the second argument is a map with the attributes for your custom event. Event attributes must be strings or numbers. Ensure you limit the number of unique event type names that you create, and do not generate these names dynamically. For restrictions on event type names, see Limits and restricted characters and Reserved words.

You can change the maximum number of events recorded by the Java agent via a configuration parameter in newrelic.yml.

Specify the maximum number of events to record per minute as an integer. For example, if you want to send less than the default of 10000 events:

custom_insights_events:
  max_samples_stored: 5000

To disable custom events entirely, add the following to your newrelic.yml:​

custom_insights_events:
  enabled: false

For Java agent versions prior to 4.1.0, use the following YAML configuration:

custom_insights_events.enabled: true
custom_insights_events.max_samples_stored: 5000

Custom event collection is enabled by default in .NET agent version 4.6.29.0 or higher. To send custom events, simply call RecordCustomEvent(). For example:

var eventAttributes = new Dictionary<String, Object>();
NewRelic.Api.Agent.NewRelic.RecordCustomEvent('MyCustomEvent', eventAttributes);

The first argument defines the name of your event type, and the second argument is an IEnumerable with the attributes for your custom event. Ensure you limit the number of unique event type names that you create, and do not generate these names dynamically. For restrictions on event type names, see Limits and restricted characters and Reserved words.

You can turn off custom events entirely by setting customEvents.enabled to false in newrelic.config.

Custom event collection is enabled by default in Node.js agent version 1.15.0 or higher. To send custom events, simply call the relevant API. For example:

recordCustomEvent(eventType, attributes)

Use recordCustomEvent to record an event-based metric, usually associated with a particular duration. The eventType must be an alphanumeric string less than 255 characters. The attributes must be an object of key and value pairs. The keys must be shorter than 255 characters, and the values must be string, number, or boolean. For restrictions on event type names, see Limits and restricted characters and Reserved words.

To disable custom events entirely, add custom_insights_events.enabled: false to newrelic.js.

Custom event collection is enabled by default in PHP agent version 4.18 or higher. To send custom events, simply call the relevant API function. For example:

newrelic_record_custom_event("WidgetSale", array("color"=>"red", "weight"=>12.5));

The first argument defines the name of your event type, and the second argument is an array with the attributes for your custom event. Ensure you limit the number of unique event type names that you create, and do not generate these names dynamically. For restrictions on event type names, see Limits and restricted characters and Reserved words.

By default, the maximum number of custom events recorded per minute is 10,000. This setting cannot be changed.

To disable custom events entirely, add newrelic.custom_insights_events.enabled = false to your newrelic.ini and restart the agent.

Custom event collection is enabled by default in Python agent version 2.60.0.46 or higher. To send custom events, simply call the relevant API. For example:

newrelic.agent.record_custom_event(event_type, params, application=None)

The event_type defines the name (or type) of the custom event. Attributes of the custom event should be passed in as a dictionary via the params keyword argument. Ensure you limit the number of unique event type names that you create, and do not generate these names dynamically. For limits and restrictions on event_type and params, see Limits and restricted characters and Reserved words

If called outside of the context of a monitored web request or background task, the call will be ignored unless the application keyword argument is provided and an application object corresponding to the application against which the exception should be recorded is provided. A suitable application object can be obtained using the newrelic.agent.application() function.

To disable custom events entirely, set custom_insights_events.enabled to False in your newrelic.ini configuration file.

Custom event collection is enabled by default in Ruby agent version 3.9.8.273 or higher. To send custom events, simply call the relevant API. For example:

::NewRelic::Agent.record_custom_event('WidgetSale', color: 'red', weight: 12.5)

The first argument defines the name of your event type, and the second argument is a hash with the attributes for your custom event. Ensure you limit the number of unique event type names that you create, and do not generate these names dynamically. For restrictions on event type names, see Limits and restricted characters and Reserved words.

You can change the maximum number of events recorded by the Ruby agent via a configuration parameter in newrelic.yml:

  1. Add custom_insights_events.max_samples_stored: to your configuration file.
  2. Specify the maximum number of events to record per minute as an integer. For example, if you want to be able to send up to 5000 events per minute, add:

    custom_insights_events.max_samples_stored: 5000

To disable custom events entirely, add custom_insights_events.enabled: false to newrelic.yml.

Timestamps

You may not specify a timestamp on events that are collected and recorded via the agent. The agent will automatically assign a timestamp to events based on when they are recorded via the API.

Limits and restricted characters

See Insights custom data requirements for size limits, data types, and naming syntax requirements.

Reserved words

Before creating custom attributes, review New Relic's list of reserved terms used by NRQL and Insights. Otherwise unexpected results may occur.

For more help

Recommendations for learning more: