Report New Relic-format traces via Trace API

New Relic's Trace API accepts two types of data formats:

  • zipkin for Zipkin trace data
  • newrelic for all other trace data

This document explains how to send newrelic-format traces.

Quick start: Send a trace to New Relic

This procedure explains how to send a sample newrelic-format trace to New Relic.

Note that this is only a simple trace, in order to show you how the API works. In practice, you might have a more complex trace structure, with additional attributes.

  1. You'll need an Insert API key. To access these keys: Go to insights.newrelic.com, select Manage data, and then select API keys from the upper navigation. If you don't have a key, create a new one by selecting Insert keys +.

    1. Insert your API key into the following JSON and then send the JSON to our endpoint. Tips:

          curl -i -H "Content-Type: application/json" \
           -H "Api-Key: [API KEY HERE]" \
           -H 'Data-Format: newrelic' \
           -H 'Data-Format-Version: 1' \
           -X POST \
           -d '[
                 {
                   "common": {
                     "attributes": {
                       "service.name": "Test Service A",
                       "host": "host123.test.com"
                     }
                   },
                   "spans": [
                     {
                       "trace.id": "123456",
                       "id": "ABC",
                       "attributes": {
                         "duration.ms": 12.53,
                         "name": "/home"
                       }
                     },
                     {
                       "trace.id": "123456",
                       "id": "DEF",
                       "attributes": {
                         "service.name": "Test Service A",
                         "host": "host456.test.com",
                         "duration.ms": 2.97,
                         "name": "/auth",
                         "parent.id": "ABC"
                       }
                     }
                   ]
                 }
               ]' 'https://trace-api.newrelic.com/trace/v1'
      
      • To copy the JSON, hover over the code to see a Copy button.
      • If 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.

Within a minute, the trace should be available in New Relic. To find it, go to the distributed tracing UI and run a query for the trace.id. In this example, it was 123456.

Trace API query by traceId

Learn more:

JSON requirements and recommendations

Requirements and guidelines for newrelic-format trace JSON:

  • Each JSON payload is an array of objects.
  • Each object should contain a required spans key.
  • Each object may contain an optional common key. Use this if you want 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 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 may 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 will have the trace.id 12345 and the custom attribute host: host123.test.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.test.com"
      }
    },
    "spans": [
      {
        "trace.id": "12345",
        "id": "abc",
        "attributes": {
          "user.email": "bob@newr.com",
          "service.name": "my-service",
          "duration.ms": 750,
          "name": "my-span"
        }
      },
      {
        "trace.id": "12345",
        "id": "def",
        "attributes": {
          "parent.id": "abc",
          "service.name": "second-service",
          "duration.ms": 750,
          "name": "second-span"
        }
      }
    ]
  }
]

Below are the attributes that can be placed in the attributes block of a newrelic-format JSON post:

Required attributes

These attributes are required in a JSON post. Requests without these attributes will be rejected, and an NrIntegrationError will be generated. These are the only attributes that don't belong under attributes.

attribute description
id
string
Unique identifier for this span.
trace.id
string
Unique identifier shared by all spans within a single trace.
timestamp
long
The span's start time in Epoch milliseconds. Defaults to the current time in UTC timezone.

While not required, these attributes are highly recommended and should be included for the best experience using your data. They are included in the attributes section.

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 displayed.
service.name
string
none The name of the entity that created this span.

Other attributes

You can add any arbitrary attributes you want, 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.

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.

For more help

Recommendations for learning more: