This document contains general requirements and rules for inserting and using custom events and their associated attributes. Additional requirements may apply based on the method you use.
You can report custom events to New Relic in several ways, including:
- agent APIs
- Event API (There are additional requirements when using the Event API.)
- Agent APIs and (There are additional requirements with the custom
- Mobile monitoring SDK
When reporting custom events and attributes, follow these general requirements for supported data types, naming syntax, and size:
Total maximum size or length: 1MB (10^6 bytes) maximum per POST. We highly recommend using compression.
The payload must be encoded as UTF-8.
The Event API has additional HTTP rate limits.
Attribute data types
Maximum length of attribute name: 255 characters.
Maximum length of custom attribute values:
Naming syntax for events and attributes
Event names can be a combination of alphanumeric characters, colons (
We recommend starting names with a letter: if it starts with something else, you'll need to put backticks around the name when querying. For more on when backticks are required in a query, see NRQL reference.
Do not use words reserved for use by NRQL.
Maximum length of event name: 255 characters.
The database does not store any data with a null value.
Avoid using the following reserved words as names for events and attributes. Otherwise, unexpected results may occur.
This is not a complete list. In general, avoid using MySQL-reserved words to avoid collision with future New Relic functionality.
This is a reserved attribute name. If it's included, it will be dropped during ingest.
Value must be an integer. If it is not an integer, the attribute name and value will be dropped during ingest.
The event type as stored in New Relic. New Relic agents and scripts normally report this as
Must be a Unix epoch timestamp. You can define timestamps either in seconds or in milliseconds. It must be +/-1 day (24 hours) of the current time on the server.
Log forwarding terms
The following keys are reserved by the infrastructure agent's log forwarding feature:
NRQL syntax terms
If you need to use NRQL syntax terms as attribute names, including dotted attributes, they must be enclosed in backticks; for example,
Event type limits
The current limit for total number of
eventType values is 250 per account (not per organization) in a given 24-hour time period. If an account exceeds this limit, New Relic may filter or drop data. Event types include:
- Default events from New Relic agents and integrations
- Custom events from agents or
- Custom events from Event API