• /
  • Log in

Introduction to the Log API

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.

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

Compatibility and requirements

Requirements include:

HTTP setup

To send log data to your New Relic account:

  1. Get your New Relic license key.
  2. Generate the JSON message using the required headers and body fields.
  3. Ensure you're providing an Api-Key or License-Key via headers or query parameters
  4. Submit the JSON message to the HTTP endpoint in a POST request.
  5. 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

Content-Type

Required

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

Api-Key

Required

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

You can also use an Insights insert key but the license key is preferred.

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

HTTP query parameters

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

Query parameter

Value

Api-Key

Your license key. Use this key whenever you send a header.

You can also use an Insights insert key but the license key is preferred.

JSON body

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

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: 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.
  • 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.
  • 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.

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.

Important

Log management does not support white space in attribute names. For example, {"Sample Attribute": "Value"} would cause errors.

JSON message attributes

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": "my-service",
"user": {
"id": 123,
"name": "alice"
}
}

Important

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:

If no data appears after you enable Log management, follow the troubleshooting procedures.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.