Insights custom data requirements and limits

You can insert custom events and attributes into New Relic Insights using the New Relic Event API, APM agent APIs, Browser agent APIs, and the Mobile SDK.

This document contains general requirements and rules for inserting and using your custom data. Additional requirements may apply based on the method you use.

General requirements

Access to your custom data depends on your Insights subscription's data retention.

When inserting custom events and attributes to Insights, follow these general requirements for supported data types, naming syntax, and size:

Requirement Description
Payload

Total maximum size or length: 1 MB maximum per POST. We highly recommend using compression.

The Event API has additional HTTP rate limits.
Attribute data types

Attribute values can be either a string or a numeric integer or float.

If your attribute values contain date information, define it as an unformatted Unix timestamp (in seconds or milliseconds) by using the Insights data formatter.
Attribute size

Maximum name size: 255 bytes.

Maximum attribute value size:

  • Custom attributes sent by the agent: 255 bytes

  • Attributes attached to custom events sent using the Event API: 4KB

    Insights charts only show the first 255 characters of attribute values. To read full attribute key/values, use the JSON chart type or Query API.

Maximum total attributes per event: 254. Exception: If you use the APM agent API, the max is 64.
Naming syntax

Attribute names can be a combination of alphanumeric characters, colons (:), periods (.), and underscores (_).

Event types (using the eventType attribute) can be a combination of alphanumeric characters, colons (:), and underscores (_).

Do not use words reserved for use by NRQL and Insights.
Null values The database does not store any data with a null value.

Reserved words

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, it's a good practice to avoid using MySQL-reserved words to avoid collision with future New Relic functionality.

Keyword Description
accountId

This is a reserved attribute name. If it is included, it will be dropped during ingest.
appId

Value must be an integer. If it is not an integer, the attribute name and value will be dropped during ingest.
eventType

The event type as stored by New Relic Insights. New Relic agents and scripts normally report this as eventType. Can be a combination of alphanumeric characters, colons (:), and underscores (_). Be sure to review the prohibited eventType values and eventType limits.
Prohibited eventType values

For your eventType value, avoid using Metric, MetricRaw, and strings prefixed with Metric[0-9] (such as Metric2 or Metric1Minute). Events passed in with these event types will be dropped. These event types are reserved for use by New Relic.
timestamp

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.
NRQL syntax terms

If you need to use NRQL syntax terms as attribute names, they must be enclosed in backticks; for example, `LIMIT`. Otherwise, avoid using these reserved words:

ago, and, as, auto,

begin, begintime,

compare,

day, days,

end, endtime, explain,

facet, from,

hour, hours,

in, is,

like, limit,

minute, minutes, month, months,

not, null,

offset, or,

second, seconds, select, since,

timeseries,

until,

week, weeks, where, with

Additional Browser PageAction requirements

For additional requirements for using New Relic Browser's custom PageAction event, see Insert custom data via New Relic Browser agent.

Additional Insights API requirements

For more requirements and details, see Insights Event API.

Event type limits

The current limit for total number of eventType values is 250 per sub-account in a given 24-hour time period. If a user exceeds this limit, New Relic may filter or drop data. Event types include:

  • Default events from New Relic agents
  • Custom events from New Relic agents
  • Custom events from Insights custom event inserter

If you have a use case that requires to need to store more than 250 unique event types in a given 24-hour period, file a New Relic Support ticket at support.newrelic.com.

For more help

Recommendations for learning more: