• Log inStart now

Introduction to the Log API

If our log forwarding solutions don't meet your needs, you can use our Log API to send log data directly to New Relic via an HTTP endpoint.

Want to try out our Log API? Create a New Relic account for free! No credit card required.

HTTP endpoint

Use the endpoint that's applicable for your New Relic account:

United States (US) endpoint:

https://log-api.newrelic.com/log/v1

European Union (EU) endpoint:

https://log-api.eu.newrelic.com/log/v1

HTTP setup

To send log data to your New Relic account via the Log API:

  1. Get your New Relic license key.
  2. Review the limits and restricted characters for your JSON payload.
  3. Generate the JSON message using the required headers and body fields.
  4. Ensure that your Api-Key or License-Key is included in your headers or query parameters. Refer to the log JSON examples.
  5. Send your JSON message to the appropriate HTTP endpoint for your New Relic account in a POST request.
  • US: https://log-api.newrelic.com/log/v1
  • EU: https://log-api.eu.newrelic.com/log/v1
  1. Generate some traffic and wait a few minutes, then check your account for data.

If no data appears after you enable our log management capabilities, follow our troubleshooting procedures.

HTTP headers

When creating your HTTP headers, use these guidelines:

Header

Supported values

Content-Type

Required

  • application/json
  • json
  • application/gzip
  • gzip

Gzipped JSON formatting is accepted. If sending compressed JSON, please include the Content-Type: application/json and Content-Encoding: gzip headers.

Authentication

Your license key serves to authenticate your request to the Log API, and determines the New Relic account where your submitted log message(s) will be written. It needs to be passed as either an HTTP header or a query string parameter.

Option 1: Authenticate using HTTP header

Pass your license key by adding a custom HTTP header as described below:

Header

Supported values

Api-Key

A New Relic license key. You can also send this via query parameter.

Option 2: Authenticate using query string parameter ("headerless" authentication)

The license key can also be passed as a query string parameter in the URL. This is useful when sending logs from cloud-based sources that don't allow custom HTTP request headers.

Example: https://LOG_API_ENDPOINT/log/v1?Api-Key=YOUR_API_KEY_HERE

Query parameter

Value

Api-Key

Your license key. You can also send this via HTTP header.

JSON body

You can send your JSON message using either a simplified or detailed set of attributes:

Supported attribute types

Attributes may be of any of the following types:

Type in the JSON request

Type stored in the New Relic database

boolean

boolean

integer

integer

long

long

float

float

double

double

string

string (Note that if a string value is stringified JSON, it will be parsed and its fields extracted as variables. See JSON message attribute parsing)

Array

(unsupported)

Limits and restricted characters

Caution

Avoid calling our API from within the code of a customer-facing application. This can cause performance issues or block your application if response time is slow. If you need to do it this way, call our API asynchronously to avoid these performance issues.

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: The first 4,094 characters are stored in NRDB as a Log event field with the same name, such as message. If the string value exceeds 4,094 characters, we store the long string as a blob.

Some specific attributes have additional restrictions:

  • accountId: This is a reserved attribute name. If it is included, it will be dropped during ingest.
  • entity.guid, entity.name, and entity.type: These attributes are used internally to identify entities. Any values submitted with these keys in the attributes section of a metric data point may cause undefined behavior such as missing entities in the UI or telemetry not associating with the expected entities. For more information please refer to Entity synthesis.
  • eventType: This is a reserved attribute name. If it is included, it will be dropped during ingest.
  • timestamp: Must be a Unix epoch timestamp. You can define timestamps either in seconds or in milliseconds.

Important

Payloads with timestamps older than 48 hours may be dropped.

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.

Log payload format

We accept any valid JSON payload. The payload must encoded as UTF-8.

JSON message attributes

JSON message attribute parsing

Our log management capabilities will parse any message attribute as JSON. The resulting JSON attributes in the parsed message will be added to the event. If the message attribute is not JSON, it is left as is.

Here is an example message attribute:

{
"timestamp": 1562767499238,
"message": "{\"service-name\": \"login-service\", \"user\": {\"id\": 123, \"name\": \"alice\"}}"
}

This will be treated as:

{
"timestamp": 1562767499238,
"service-name": "login-service",
"user": {
"id": 123,
"name": "alice"
}
}

Log JSON examples

Attributes can be scalar JSON types like string and number. They can also be compound (or nested) objects. Compound attributes will have their associated attributes stored with flattened names.

For example, here is a compound user attribute in a log entry's attributes:

"attributes": {
"action": "login",
"user": {
"id": 123,
"name": "alice"
}
}

This will result in the following attributes being stored with the log event:

Attribute

Value

"action"

"login"

"user.id"

123

"user.name"

"alice"

Log POST message example

Log POST message example:

bash
$
POST /log/v1 HTTP/1.1
$
Host: log-api.newrelic.com
$
Content-Type: application/json
$
Api-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
$
}
$
}]
$
}]

This POST message would result in the following log messages being stored in New Relic:

Attribute

Value

"logtype"

"accesslogs"

"service"

"login-service"

"hostname"

"login.example.com"

Here's an example of stored logs block attributes:

Attribute

Value

"timestamp"

1550086450124

"message"

"User 'xyz' logged out"

"auditId"

123

JSON POST request example

Here's an example of a JSON POST request:

bash
$
POST /log/v1 HTTP/1.1
$
Host: log-api.newrelic.com
$
Content-Type: application/json
$
Api-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"
$
}

What's next?

Explore logging data across your platform.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.