• Log inStart now

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:

Endpoints

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

Data formats

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

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

entityGuid

string

Unique identifier for the entity that created this span. Generated from service.name, if available.

guid

string

Used for backwards compatibility with data from APM agents.

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:

Restricted attribute

description

entity.guid

string

Unique identifier for the entity associated with this span.

entity.name

string

Human-readable name of an entity, often used to identify an entity in the UI.

entity.type

string

Used to differentiate between different types of entities, like hosts, applications, etc.

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.

Important

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

Content-Type

No

Required. Must be application/json.

Content-Length

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.

Api-Key

Yes (case-sensitive)

Required. The Trace API requires a license key. If this is provided as both a header and a query parameter, the values must match.

Content-Encoding

No

Required if compressed payload. The value must be gzip.

Data-Format

Yes

Required for zipkin. Optional for newrelic.

If present, Data-Format-Version must also be present.

Data-Format-Version

Yes

Required for zipkin.

If present, Data-Format must also be present.

There are only two possible pairings for these values:

  • If Data-Format is zipkin, Data-Format-Version must be 2.
  • If Data-Format is newrelic, Data-Format-Version must be 1.

x-request-id

No

Optional - Reserved for future use. The value must be a valid UUID4. The value is expected to be unique for each request.

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

For trace-related limits, see How distributed tracing works.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.