If our logging solutions don't meet your needs, you can use our Log API to send log data directly to New Relic's Log management via an HTTP endpoint.
To use APIs and the rest of our observability platform, join the New Relic family! Sign up to create your free account in only a few seconds. Then ingest up to 100GB of data for free each month. Forever.
Compatibility and requirements
Requirements include:
- New Relic license key (recommended) or an Insert API key.
- For payload limits and restricted characters, see the Event API limits.
HTTP setup
To send log data to your New Relic account:
- Get your New Relic license key (recommended) or register an Insert API key.
- Generate the JSON message using the required headers and body fields.
- Submit the JSON message to the HTTP endpoint in a POST request.
- Generate some traffic and wait a few minutes, then check your account for data.
HTTP headers
When creating your HTTP headers, use these guidelines:
Header | Supported values |
---|---|
Required |
|
Exactly one of:
or
Required |
Use either your New Relic Insert API key (with Api-Key) or license key (with X-License-Key ). |
Gzipped JSON formatting is accepted. If sending compressed JSON, please include the application/gzip
header.
JSON body
You can send your JSON message using either a simplified or detailed set of attributes:
- Simplified JSON body message
-
When using the simplified format to create your JSON message, send a single JSON object with the following:
Field Value type Format Required Notes "timestamp"
Integer Either milliseconds or seconds since epoch No If the field is not specific as millisecond or seconds since epoch, the message will be timestamped using the ingest time "message"
String any string No This is the main log message field that is searched by default "logtype"
String any string No Primary field for identifying logs and matching parsing rules other_fields
(must not contain white space)
String any string No These will become attributes of the log message
Note: Log management does not support white space in attribute names
- Detailed JSON body message
-
When using the detailed format to create your body, it must be a JSON array containing one or more JSON objects, each of which with the following format:
Field Value type Format Required Notes "common"
Object See common. No Any attributes that are common to all log messages "logs"
Array See logs. Yes Array with the log entries
Limits and restricted characters
Restrictions on logs sent to the Log API:
- Payload total size: 1MB(10^6 bytes) maximum per POST. We highly recommend using compression.
- The payload must be encoded as UTF-8.
- Number of attributes per event: 255 maximum
- Length of attribute name: 255 characters
- Length of attribute value: 4096 maximum character length
Some specific attributes have additional restrictions:
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
: Can be a combination of alphanumeric characters,_
underscores, and:
colons.timestamp
: Must be a Unix epoch timestamp. You can define timestamps either in seconds or in milliseconds.
Rate limits on logs sent to the Log API:
- Maximum rate for HTTP requests sent to the Log API: 300,000 requests per minute
- Maximum rate of uncompressed Log JSON bytes sent to the Log API: 10 GB per minute
Rate limit violations
Exceeding rate limits affects how the Log API behaves. Follow these instructions if this happens.
- HTTP requests per minute
-
When the maximum request rate limit is exceeded for an account, the New Relic Log API returns a
429
response for the remainder of the minute. This response includes aRetry-After
header indicating how long to wait in seconds before resubmitting or sending new data.To resolve this issue, either reduce the number of data points you are sending, or request a rate limit change. Subsequent subscription changes do not impact modified rate limits. If an account change impacts your rate limit, you must notify us to adjust your rate limit.
To request rate limit changes, contact your New Relic account representative, or visit our Support portal.
- JSON bytes per minute
-
When the maximum Log JSON byte limit is exceeded for an account, the New Relic Log API returns a
429
response for the remainder of the minute. This response includes aRetry-After
header indicating how long to wait in seconds before resubmitting or sending new data.To resolve this issue, try to reduce the amount of log data you are sending, or spread it out over a larger period of time.
To request rate limit changes, contact your New Relic account representative, or visit our Support portal.
Log payload format
We accept any valid JSON payload. The payload must encoded as UTF-8.
Log management does not support white space in attribute names. For example, {"Sample Attribute": "Value"}
would cause errors.
JSON message attributes
- Common block attributes
-
This is a block containing attributes that will be common to all log entries in
logs
:Field Value type Format Required Notes "timestamp"
Integer Milliseconds or seconds since epoch No Message timestamp default to ingest time "attributes"
Object JSON No This sub-object contains all other attributes of the message - Logs block attributes
-
This is an array containing log entries with the following format:
Field Value type Format Required Notes "timestamp"
Integer Milliseconds or seconds since epoch No Message timestamp default to ingest time "attributes"
Object JSON No This sub-object contains all other attributes of the message "message"
String (any string) Yes This is the main log message field that is searched by default "log"
String (any string) No We will rewrite this string as the field message
on ingest"LOG"
String (any string) No We will rewrite this string as the field message
on ingest"MESSAGE"
String (any string) No We will rewrite this string as the field message
on ingest
JSON message attribute parsing
This will attempt to parse any message
attribute as JSON. If the message
attribute is JSON, it will be parsed and the resultant JSON attributes will be added to the event. If the message
attribute is not JSON, it is left as is.
For example, the event:
{ "timestamp": 1562767499238, "message": "{\"service-name\": \"login-service\", \"user\": {\"id\": 123, \"name\": \"alice\"}}" }
Will be treated as:
{ "timestamp": 1562767499238, "message": "{\"service-name\": \"my-service\", \"user\": {\"id\": 123, \"name\": \"alice\"}}", "service-name": "login-service", "user": { "id": 123, "name": "alice" } }
Log management does not support white space in attribute names. For example, {"Sample Attribute": "Value"}
would cause errors.
Log JSON example
Attributes may be scalar JSON types like string and number, but may also be compound (or nested) objects. Compound attributes will have their leaf attributes stored with flattened names.
For instance, a compound user
attribute in a log entry's attributes:
"attributes": { "action": "login", "user": { "id": 123, "name": "alice" } }
will result in the following attributes being stored with the log event:
Attribute | Value |
---|---|
"action" |
"login" |
"user.id" |
123 |
"user.name" |
"alice" |
Log POST example
Log POST
message example:
POST /log/v1 HTTP/1.1 Host: log-api.newrelic.com Content-Type: application/json X-License-Key: <YOUR_LICENSE_KEY>Accept: */* Content-Length: 319 [{ "common": { "attributes": { "logtype": "accesslogs", "service": "login-service", "hostname": "login.example.com" } }, "logs": [{ "timestamp": <TIMESTAMP_IN_UNIX_EPOCH>, "message": "User 'xyz' logged in" },{ "timestamp": <TIMESTAMP_IN_UNIX_EPOCH>, "message": "User 'xyz' logged out", "attributes": { "auditId": 123 } }] }]
The above POST
message would result in the following log messages being stored in Log management:
Example of stored common block attributes:
Attribute | Value |
---|---|
"logtype" |
"accesslogs" |
"service" |
"login-service" |
"hostname" |
"login.example.com" |
Example of stored logs block attributes example:
Attribute | Value |
---|---|
"timestamp" |
1550086450124 |
"message" |
"User 'xyz' logged out" |
"auditId" |
123 |
HTTP endpoint
Once configured, your JSON data can be sent to the following endpoint in a POST request:
United States (US) endpoint:
https://log-api.newrelic.com/log/v1
European Union (EU) endpoint:
https://log-api.eu.newrelic.com/log/v1
Here's an example of a JSON POST request:
POST /log/v1 HTTP/1.1 Host: log-api.newrelic.com Content-Type: application/json X-License-Key: <YOUR_LICENSE_KEY> Accept: */* Content-Length: 133 { "timestamp": <TIMESTAMP_IN_UNIX_EPOCH>, "message": "User 'xyz' logged in", "logtype": "accesslogs", "service": "login-service", "hostname": "login.example.com" }
Find log data
For where to find data sent via the Log API (including from integrations that use that API), see Find log data.
What's next?
Now that you've enabled Log management, here are some potential next steps:
- Explore your data using the Logs UI.
- Configure your agent to see contextual log data, such as distributed tracing, stack traces, application logs, and more.
- Query your data and create custom dashboards, charts, or alerts.
If no data appears after you enable Log management, follow the troubleshooting procedures.