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.

Compatibility and requirements

The Log API requires a New Relic license key (recommended) or Insert API key.

HTTP setup

To send log data to your New Relic account:

1. Get your New Relic license key (recommended) or register an Insert API key.
2. Generate the JSON message using the required headers and body fields.
3. Submit the JSON message to the HTTP endpoint in a POST request.
4. Generate some traffic and wait a few minutes, then check your account for data.

HTTP headers

When creating your HTTP headers, use these guidelines:

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

Log payload format

We accept any valid JSON payload.

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

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:

Example of stored logs block attributes example:

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.

For more help