---
title: APM: Report custom events and attributes
source: https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/apm-report-custom-events-attributes
---

If you have [APM](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/introduction-new-relic-apm), you can report custom [event data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#event-data). You can then [query](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/query-new-relic-data) and visualize your data in New Relic.

## Data considerations [#considerations]

New Relic agents send [event data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#event-data) to New Relic as part of the normal harvest cycle every five seconds for agent versions supporting [real time streaming](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/real-time-streaming).

Sending a lot of events can increase the memory overhead of the agent. New Relic enforces an upper limit of 833 custom events every 5 seconds. Additionally, posts greater than 1MB (10^6 bytes) in size will not be recorded, regardless of the custom event limit.

You can also send custom events using the [Event API](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/introduction-event-api) (without need for APM). However, be aware that custom events sent with the agent APIs are not compatible with [high-security mode](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security).

> #### 💡 TIP
>
> For more information, check out New Relic University’s tutorial [Adding custom data with the APM agent API](https://newrelic.wistia.com/medias/uwjlnrk4nk). Or, go directly to the full online course [Custom data with APM](https://learn.newrelic.com/custom-data-with-apm).

## Record custom events and attributes [#steps]

You can add your own custom APM events and [attributes](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/glossary#attribute), which you can then use for [querying and charting](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/query-new-relic-data). This is one of several ways to [report custom data](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/send-custom-data-insights).

To record a custom event, follow the procedures for your New Relic language agent. To add custom attributes to APM events, you must first enable them for your APM agent, and then make an API call to record the attribute. Follow the agent-specific custom attribute procedures.

When creating your own custom events and attributes, follow data requirements for:

-   [Size limits](https://docs.newrelic.com/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data/#general)
-   [Attribute types](https://docs.newrelic.com/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data/#general)
-   [Reserved words](https://docs.newrelic.com/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data/#reserved-words)

**Go**

To add a custom event to apps monitored by the Go agent, use [`RecordCustomEvent`](https://docs.newrelic.com/docs/agents/go-agent/features/create-custom-events-insights-go). You can then add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes#go-att) for your Go app.

**Java**

Custom event collection is enabled by default in Java agent version 3.13.0 or higher. To send custom events, call [`recordCustomEvent`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Insights.html). For example:

````java
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 our documentation about [limits and restricted characters](/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data) and [NRQL reserved words](/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#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:

```yml
custom_insights_events:
  max_samples_stored: 5000
```

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

```yml
custom_insights_events:
  enabled: false
```

You can then add [custom attributes](/docs/apm/other-features/attributes/collecting-custom-attributes#java-att) for your Java app.

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

```yml
custom_insights_events.enabled: true
custom_insights_events.max_samples_stored: 5000
```

````

**.NET**

Custom event collection is enabled by default in .NET agent version 4.6.29.0 or higher. To send custom events, simply call [`RecordCustomEvent()`](https://docs.newrelic.com/docs/agents/net-agent/net-agent-api/recordcustomevent-net-agent). For example:

````cs
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 our documentation about [limits and restricted characters](/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data) and [NRQL reserved words](/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words).

You can then add [custom attributes](/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes#net-att) for your .NET app.

You can turn off custom events entirely by setting [`customEvents.enabled`](/docs/agents/net-agent/installation-configuration/net-agent-configuration#customevents-enabled) to `false` in `newrelic.config`.

````

**Node.js**

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:

````js
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 our documentation about [limits and restricted characters](/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data) and [NRQL reserved words](/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words).

You can then add [custom attributes](/docs/apm/other-features/attributes/collecting-custom-attributes#nodejs-att) for your Node.js app.

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

````

**PHP**

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:

````php
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 our documentation about [limits and restricted characters](/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data) and [NRQL reserved words](/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words).

By default, the maximum number of custom events recorded per minute is 30,000. You can increase it up to 100,000 via the [newrelic.custom_events.max_samples_stored](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-custom-events-maxsamples) configuration setting.

You can also add [custom attributes](/docs/apm/other-features/attributes/collecting-custom-attributes#php-att) for your PHP app.

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

````

**Python**

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:

````python
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 our documentation about [limits and restricted characters](/docs/telemetry-data-platform/custom-data/custom-events/apm-report-custom-events-attributes/) and [reserved words](/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#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.

You can then add [custom attributes](/docs/apm/other-features/attributes/collecting-custom-attributes#python-att) for your Python app.

To disable custom events entirely, set [`custom_insights_events.enabled`](/docs/agents/python-agent/installation-configuration/python-agent-configuration#custom_insights_events_enabled) to `False` in your `newrelic.ini` configuration file.

````

**Ruby**

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:

````ruby
::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 our documentation about [limits and restricted characters](/docs/telemetry-data-platform/custom-data/custom-events/data-requirements-limits-custom-event-data) and [NRQL reserved words](/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#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:`](/docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration#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:

   ```yml
   custom_insights_events.max_samples_stored: 5000
   ```

You can then add [custom attributes](/docs/apm/other-features/attributes/collecting-custom-attributes#ruby-att) for your Ruby app.

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 [#limits]

See [Custom event data requirements](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/data-requirements) for size limits, data types, and naming syntax requirements.

## Reserved words [#keywords]

Before creating custom attributes, review New Relic's list of [reserved terms used by NRQL](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words). Otherwise unexpected results may occur.