• EnglishEspañol日本語한국어Português
  • Log inStart now

Report traces via the Trace API (New Relic format)

If you want to create your own tracing implementation, you can use our Trace API. This doc explains how to send traces in our general format, also known as newrelic format. (To send Zipkin-format data, see Zipkin.)

Get started

Using our Trace API is as simple as:

  • Sending trace data in the expected format (in this case, our newrelic format).
  • Sending that data to the appropriate endpoint.

Before using the Trace API, you should decide whether you want to use Infinite Tracing. To learn more about this, see Intro to Infinite Tracing and Sampling considerations.

To get started using the Trace API, follow one of these paths:

Send sample trace payload (non-Infinite Tracing)

The following explains how to send a standard (non-Infinite Tracing) payload to the Trace API using our newrelic format.

  1. Get a for the account you want to report data to.

  2. Insert that key into the following JSON and then send the JSON to our endpoint. Note: if you have a EU New Relic account, use the EU endpoint instead.

    bash
    $
    curl -i -H 'Content-Type: application/json' \
    >
    -H 'Api-Key: YOUR_LICENSE_KEY' \
    >
    -H 'Data-Format: newrelic' \
    >
    -H 'Data-Format-Version: 1' \
    >
    -X POST \
    >
    -d '[
    $
    {
    $
    "common": {
    $
    "attributes": {
    $
    "service.name": "Test Service A",
    $
    "host": "host123.example.com"
    $
    }
    $
    },
    $
    "spans": [
    $
    {
    $
    "trace.id": "123456",
    $
    "id": "ABC",
    $
    "attributes": {
    $
    "duration.ms": 12.53,
    $
    "name": "/home"
    $
    }
    $
    },
    $
    {
    $
    "trace.id": "123456",
    $
    "id": "DEF",
    $
    "attributes": {
    $
    "error.message": "Invalid credentials",
    $
    "service.name": "Test Service A",
    $
    "host": "host456.example.com",
    $
    "duration.ms": 2.97,
    $
    "name": "/auth",
    $
    "parent.id": "ABC"
    $
    }
    $
    }
    $
    ]
    $
    }
    $
    ]' 'https://trace-api.newrelic.com/trace/v1'

    Tip

    If you're sending more than one POST, change the trace.id to a unique value. Sending the same payload or span id multiple times for the same trace.id may result in fragmented traces in the UI.

  3. If your test returned HTTP/1.1 202 Accepted, go to our UI to see a query of your test data using the span attribute service.name = Test Service A.

    Tip

    Traces may take up to one minute to be processed by both the trace observer and the Trace API.

Trace API payload (New Relic format)

The Trace API JSON payload is an array of objects, with each object representing a single trace. Each of these objects requires a spans key and may also include a common key. spans (required) contains an array of objects, with each object representing a span. common (optional) shares information across multiple spans.

The Span object in the spans array

field

type

description

required

default

id

string

Unique identifier for this span.

yes

N/A

trace.id

string

Unique identifier shared by all spans within a single trace.

yes

N/A

timestamp

long

Span start time in milliseconds since the Unix epoch.

no

Current time in UTC time zone

attributes

object

Any set of key: value pairs that add more details about a span. duration.ms, name, and parent.id are strongly recommended to add.

no

N/A

Requests without the required keys above will be rejected, and an NrIntegrationError will be generated.

The common object (optional)

field

type

description

required

default

attributes

object

Any set of key: value pairs that add common details about spans in the payload. If a span contains an attribute that has been set in common, the key in the span attributes object will take precedence. duration.ms, name, and parent.id are strongly recommended to add.

no

N/A

While not required, these attributes should be included for the best experience with your data in the attributes object for each span.

attribute

default

description

duration.ms

float

none

Duration of this span in milliseconds.

name

string

none

The name of this span.

parent.id

string

none

The id of the caller of this span. Value is null if this is the root span. Traces without a root span will not be displayed.

service.name

string

none

The name of the entity that created this span. If no value or an empty string is provided, the span is assigned to an "UNKNOWN" entity and will show as such in the UI. This value should be provided to get a complete experience in the UI.

Reserved attributes

These attributes are currently reserved for internal New Relic usage. While they are not explicitly blocked, we recommend not using them.

attribute

default

description

entity.name

string

service.name

This is derived from the service.name attribute.

entity.type

string

service

The entity type is assumed to be a service.

entity.guid

string

None

The entity.guid is a derived value that uniquely identifies the entity in New Relic's backend.

Other attributes

You can add any arbitrary attributes you want in the attributes object in either common or each span object, with the exception of the restricted attributes. For example, you might want to add attributes like customer.id or user.id to help you analyze your trace data.

Requirements and guidelines for trace JSON using the newrelic format:

  • Each JSON payload is an array of objects.
  • Each object should contain a required spans key.
  • Each object can contain an optional common key. Use this if you want to share information across multiple spans in a object.
  • Any keys on a span have precedence over the same key in the common block.
  • The value for a spans key is a list of span objects.
  • Certain attributes are required, and must be included either in the optional common block, or in each span.
  • Recommended and custom attributes can be optionally included in a list of key-value pairs under a key named attributes, in the optional common block and/or in each span.

In the following example POST, there are two spans, both of which have the trace.id 12345 and the custom attribute host: host123.example.com. The first span has no parent.id, so that is the root of the trace; the second span's parent.id points to the ID of the first.

[
{
"common": {
"attributes": {
"host": "host123.example.com"
}
},
"spans": [
{
"trace.id": "12345",
"id": "abc",
"timestamp": 1603336834823,
"attributes": {
"user.email": "bob@newr.com",
"service.name": "my-service",
"duration.ms": 750,
"name": "my-span"
}
},
{
"trace.id": "12345",
"id": "def",
"timestamp": 1603336834899,
"attributes": {
"parent.id": "abc",
"service.name": "second-service",
"duration.ms": 750,
"name": "second-span"
}
}
]
}
]

To learn how to control how spans appear in New Relic (for example, adding errors or setting a span as a datastore span), see Decorate spans.

Explore more about distributed tracing:

Copyright © 2024 New Relic Inc.

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