--- title: Send your logging data with our Log API source: https://docs.newrelic.com/docs/logs/log-api/introduction-log-api --- If our [log forwarding solutions](https://docs.newrelic.com/docs/logs/forward-logs/) don't meet your needs, you can use our Log API to send log data directly to New Relic via an HTTP endpoint. ## HTTP endpoint [#endpoint] Use the endpoint that's applicable for your New Relic account: United States (US) endpoint (default): ``` https://log-api.newrelic.com/log/v1 ``` [European Union](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center) (EU) endpoint: ``` https://log-api.eu.newrelic.com/log/v1 ``` [Japan](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center) endpoint: ``` https://log-api.jp.nr-data.net/log/v1 ``` FedRAMP endpoint: ``` https://gov-log-api.newrelic.com/log/v1 ``` ## HTTP setup [#setup] To send log data to your New Relic account via the Log API: 1. Get your license key. 2. Review the [limits and restricted characters](#limits) for your JSON payload. 3. Generate the JSON message using the required [headers](#json-headers) and [body](#json-body) fields. 4. Ensure that your `Api-Key` or `License-Key` is included in your [headers](#auth-headers) or [query parameters](#query-parameters). Refer to the [log JSON examples](#log-attribute-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` - Japan: `https://log-api.jp.nr-data.net/log/v1` - FedRAMP: `https://gov-log-api.newrelic.com/log/v1` 6. Generate some traffic and wait a few minutes, then [check your account](#what-next) for data. If no data appears after you enable our log management capabilities, follow our [troubleshooting procedures](https://docs.newrelic.com/docs/logs/log-management/troubleshooting/no-log-data-appears-ui/). ## HTTP headers [#json-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 [#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 [#auth-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](#query-parameters). | ### Option 2: Authenticate using query string parameter ("headerless" authentication) [#query-parameters] 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](#auth-header). | ## JSON body [#json-content] 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, String | Milliseconds or seconds since epoch (when set as an integer), or ISO8601-formatted timestamp (when set as a string) | No | If this field is not present or incorrectly specified, the message will be timestamped using the ingest time | | `"message"` | (any -- but String is recommended. See the [list of supported attribute types](#supported-types)) | any | 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 | (any -- see the [list of supported attribute types](#supported-types)) | any | No | These will become attributes of the log message. | **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](#json-common). | No | Any attributes that are common to all log messages | | `"logs"` | Array | See [logs](#json-logs). | Yes | Array with the log entries | ## Supported attribute types [#supported-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](#message-attribute-parsin)) | | Array | Arrays are converted to strings and then stored. OpenTelemetry logs support homogeneous arrays. For more information see [arrays in OpenTelemetry](https://docs.newrelic.com/docs/nrql/using-nrql/arrays-in-nrql/). | ## Limits and restricted characters [#limits] > #### ⚠️ 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](https://docs.newrelic.com/docs/logs/ui-data/long-logs-blobs). Some specific attributes have additional restrictions: - `accountId`: This is a reserved attribute name. If it is included, it will be dropped during ingest. - `appId`: Must be an integer. When using a non-integer data type, the data will be ingested but becomes unqueryable. - `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](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/what-entity-new-relic/#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 (either in seconds or in milliseconds) or an ISO8601-formatted timestamp. > #### ⚠️ 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. **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 a `Retry-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](http://support.newrelic.com). **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 a `Retry-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](http://support.newrelic.com). ### Log payload format [#payload-format] We accept any valid JSON payload. The payload must encoded as **UTF-8**. ## JSON message attributes [#attributes] **Common block attributes** This is a block containing attributes that will be common to all log entries in [`logs`](#json-logs): | Field | Value type | Format | Required | Notes | | -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ | | `"timestamp"` | Integer, String | Milliseconds or seconds since epoch (when set as an integer), or ISO8601-formatted timestamp (when set as a string) | 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, String | Milliseconds or seconds since epoch (when set as an integer), or ISO8601-formatted timestamp (when set as a string) | No | Message timestamp default to ingest time | | `"attributes"` | Object | JSON | No | This sub-object contains all other attributes of the message | | `"message"` | (any -- but String is recommended. See the [list of supported attribute types](#supported-types)) | (any) | 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 | | `"msg"` | String | (any string) | No | We will rewrite this string as the field `message` on ingest | ## JSON message attribute parsing [#message-attribute-parsin] 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: ```json { "timestamp": 1562767499238, "message": "{\"service-name\": \"login-service\", \"user\": {\"id\": 123, \"name\": \"alice\"}}" } ``` This will be treated as: ```json { "timestamp": 1562767499238, "service-name": "login-service", "user": { "id": 123, "name": "alice" } } ``` ## Log JSON examples [#log-attribute-examples] Attributes can be scalar JSON types like string and number. They can also be compound (or [nested](https://www.digitalocean.com/community/tutorials/an-introduction-to-json#working-with-complex-types-in-json)) 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: ```json "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-attribute-example] Log `POST` message example: ```bash POST /log/v1 HTTP/1.1 Host: log-api.newrelic.com Content-Type: application/json Api-Key: Accept: */* Content-Length: 319 [{ "common": { "attributes": { "logtype": "accesslogs", "service": "login-service", "hostname": "login.example.com" } }, "logs": [{ "timestamp": , "message": "User 'xyz' logged in" },{ "timestamp": , "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 [#example-post] 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: Accept: */* Content-Length: 133 { "timestamp": , "message": "User 'xyz' logged in", "logtype": "accesslogs", "service": "login-service", "hostname": "login.example.com" } ``` ## What's next? [#what-next] Explore [logging data across your platform](https://docs.newrelic.com/docs/logs/ui-data/use-logs-ui/). - Get deeper visibility into both your application and your platform performance data by forwarding your logs with our [logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-apm-agents/) capabilities. - Set up [alerts](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/alert-conditions/create-alert-conditions/). - [Query your data](https://docs.newrelic.com/docs/query-your-data/explore-query-data/get-started/introduction-querying-new-relic-data/) and [create dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards/).