Trace API general requirements and limits

Information about Trace API data requirements, including:

• Data specifications and max limits
• Required metadata (headers, query parameters)
• Response validation details

This document applies to the Trace API overall. For rules regarding specific data formats, see:

• New Relic-format trace data
• Zipkin-format trace data

Endpoints

All trace data is sent via HTTPS POST to a Trace API endpoint. We have a few endpoints, depending on your setup:

• Default Trace API endpoint: https://trace-api.newrelic.com/trace/v1
• EU data centers: https://trace-api.eu.newrelic.com/trace/v1 (see other EU endpoints).
• Infinite Tracing: when you complete the Trace observer setup, you get a custom YOUR_TRACE_OBSERVER_URL value to use as an endpoint. If you're using an integration that uses the Trace API (for example, these integrations), you must configure that integration with that endpoint. You will also want to adjust the sampling of your tracing service to send us 100% of spans.
• For FedRAMP, see FedRAMP endpoints.

Data formats

Currently, the Trace API accepts two types of data formats:

• zipkin: For reporting Zipkin trace data. Zipkin data must be Zipkin JSON v2.
• newrelic: For reporting all other trace data.

Restricted attributes

The attributes in the table below are restricted in the newrelic-format JSON (in the attributes block) and in the zipkin-format JSON (in the tags block). Any values with these keys will be omitted:

The attributes in the table below 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:

Request metadata (headers and query parameters)

The following table shows the required request metadata for all trace data formats. This metadata can be sent as HTTP headers on an ingest request or, in some cases, provided as query parameters, which may be required for tracing frameworks that don't allow header modification.

Response validation

A response for successfully sending trace data will include a requestId. For example:

{"requestId":"c1bb62fc-001a-b000-0000-016bb152e1bb"}

There are two ways success/errors are signaled:

• HTTP status code (synchronous). Authentication and request errors will be signaled via HTTP status code.

  See HTTP status codes

  Code	Meaning
  202	Data accepted. This means that you've passed preliminary checks, but is not a guarantee that the data has been successfully parsed and indexed as part of a distributed trace.
  400	The structure of the request was invalid. Errors with query parameters, etc.
  403	Authentication error. May occur with an invalid license key or if you lack necessary entitlement to use the Trace API.
  404	The request path is incorrect.
  405	For any request method other than POST.
  408	The request took too long to reach the endpoint.
  411	The Content-Length header wasn’t included.
  413	The payload was too big.
  414	The request URI was too long.
  415	The Content-Type or Content-Encoding was invalid.
  429	The request rate quota has been exceeded.
  431	The request headers are too long.
  5xx	There was a server error (please retry).

• NrIntegrationError events (asynchronous). Errors with the JSON payload or other semantic errors are asynchronously signaled via NrIntegrationError events that are stored in the account whose license key is associated with the request. For all errors of this type, the attribute newRelicFeature will be Distributed Tracing and requestId will be the requestId from the endpoint response.

If you receive a 202 response and don't see an NrIntegrationError event, your data should be visible in New Relic One's global distributed tracing UI in about a minute. You should be able to find the trace using a standard trace search like:

traceId = TRACE_ID_SENT

Data limits

Distributed tracing rate limits are set per account and data type. For details about data limits, see New Relic data usage limits and policies.

When you exceed your span rate limit, an NrIntegrationError event is generated. You can query rate limit messages with this NRQL:

SELECT * FROM NrIntegrationError WHERE newRelicFeature = 'Distributed Tracing' AND category = 'RateLimit' AND rateLimitType = 'SpansPerMinute'

To get a notification when you exceed the limit, you can set up a NRQL alert.

We calculate a rolling 10-minute average based on your span rate limit. This allows for temporary rate bursts, and lets us prioritize keeping and dropping complete traces instead of indiscriminately dropping spans on a per minute limit basis.

In the example below of exceeding the rate, the rate limit is the default 100,000 spans per minute. New Relic allows a burst above 100K for a couple of minutes without downsampling, because the remaining minutes in the 10-minute window averaged under 100K spans/minute. For the previous 10 minutes (8:50 - 9:00) the service received 60,000 spans/minute.