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:

• Want to use Infinite Tracing? Follow the Set up a trace observer instructions. That walks you through creating a trace observer and sending a sample payload to the trace observer endpoint.
• Don't want Infinite Tracing? See how to send a sample payload (below).

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 license key 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

   Copy

   $
   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

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

The common object (optional)

Highly recommended attributes

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

Reserved attributes

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

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:

• Learn where Trace API data shows up in the UI.
• Learn how to decorate spans for a richer, more detailed UI experience. For example, you can have spans show up as datastore spans or display errors.
• Learn about general data limits, required metadata, and response validation.
• If you don't see your trace data, see Troubleshooting.