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:
Endpoints
All trace data is sent via a 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.
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.
Data limits
Data limits and rules:
Condition | Limit |
---|---|
Max age of span | 20 minutes. |
Max payload size | 1MB (10^6 bytes) (gzip compression supported) |
Max requests per minute | 100K |
Max spans per minute per account family | Dependent on agreement. Max limit: 2M. |
Max spans per trace | 50K |
Max attributes per span | 200 |
Max span attribute value length | 4000 characters |
Allowed HTTP protocols | HTTPS only |
Cross-account visibility of span details | Potential data obfuscation |
To see an example of how span limits are enforced, see Exceeding limits.
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:
Restricted attribute | description |
---|---|
string | Unique identifier for the entity that created this span. Generated from |
string | Used for backwards compatibility with data from APM agents. |
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.
重要
Security note: We suggest using headers because query parameters are present in the URL and may be logged before being encrypted and received by New Relic. All data sent as query parameters must be URL-safe.
Header | Query param? | Details |
---|---|---|
| No | Required. Must be |
| No | Required. The length of the request body in octets (8-bit bytes) unless sent with chunked encoding. This header is generally set by default by the underlying HTTP client sending the data and in most cases should not require any additional effort by the end user. |
| Yes (case-sensitive) | Required. The Trace API requires the Insights insert key. If this is provided as both a header and a query parameter, the values must match. |
| No | Required if compressed payload. The value must be |
| Yes | Required for If present, |
| Yes | Required for If present, There are only two possible pairings for these values:
|
| No | Optional - Reserved for future use. The value must be a valid |
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.
NrIntegrationError
events (asynchronous). Errors with the JSON payload or other semantic errors are asynchronously signaled viaNrIntegrationError
events that are stored in the account whose license key is associated with the request. For all errors of this type, the attributenewRelicFeature
will beDistributed Tracing
andrequestId
will be therequestId
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
Exceeding span limits
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.
Minute | Spans sent to API | Total for past 10 minutes |
---|---|---|
8:59 | 60,000 | 600,000 |
9:00 | 40,000 | 580,000 |
9:01 | 50,000 | 570,000 |
9:02 | 250,000 | 760,000 |
9:03 | 220,000 | 920,000 |
9:04 | 125,000 | 985,000 |
9:05 | 70,000 | 995,000 |
9:06 | 50,000 | 985,000 |
9:07 | 40,000 | 965,000 |
9:08 | 40,000 | 945,000 |
9:09 | 40,000 | 925,000 |
その他のヘルプ
さらに支援が必要な場合は、これらのサポートと学習リソースを確認してください:
- Explorers Hubでは、コミュニティからのサポートを受けたり、ディスカッションに参加したりすることができます。
- 当社サイトで答えを見つけて、サポートポータルの使用方法を確認してください。
- Linux、Windows、およびmacOS向けトラブルシューティングツールであるNew Relic Diagnosticsを実行してください。
- New Relicのデータセキュリティとライセンスドキュメント をご確認ください。