Report Zipkin-format traces via Trace API

If you want to create your own tracing implementation, you can use our Trace API. This doc explains how to send Zipkin-format trace data to our Trace API. (For our general data format, see New Relic format.)

Zipkin version requirements

The Trace API supports data from Zipkin JSON v2 (or higher) without any modification. For details on this version, see Zipkin v2 release details and the Zipkin v2 schema.

Overview of using the Trace API

Using our Trace API is as simple as:

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

Our send-data instructions have options for enabling Infinite Tracing. To learn more about this, see Intro to Infinite Tracing and Sampling considerations.

To get started using the Trace API, choose an option:

• Send a sample trace: This shows a curl example of sending a trace to New Relic. This is useful for understanding how the Trace API works, and to verify you're seeing data in New Relic.
• Report data from existing Zipkin instrumentation: if you have an existing Zipkin implementation, you can simply change the endpoint of where your data gets sent.

Send sample Zipkin trace payload

This section describes how to send a simple Zipkin-format trace to our Trace API via curl request. You might choose to do this in order to learn how our API works and to verify that data is showing up in New Relic before doing in-depth instrumentation.

To get started sending a sample payload:

1. (Optional, to enable Infinite Tracing) First, you must set up a trace observer. That procedure includes instructions for sending a sample trace using our general new-relic format. When you get to that step, return here to instead learn how to send a Zipkin-format trace.
2. Send a Zipkin-format payload following the instructions below.

Send Zipkin-format payload

To send a sample Zipkin-format trace:

Get the license key for the account you want to report data to.

You'll be executing a curl request, below. Notes on this:

• Replace the license key placeholder with your license key.
• If you're using Infinite Tracing, use the YOUR_TRACE_OBSERVER_URL value in place of the standard endpoint.
• If you want to send more than one post, change the trace ID to a different value. Sending the same payload or span id multiple times for the same traceId may result in fragmented traces in the UI.

$
curl -i -H 'Content-Type: application/json' \
>
    -H 'Api-Key: NEW_RELIC_API_KEY' \
>
    -H 'Data-Format: zipkin' \
>
    -H 'Data-Format-Version: 2' \
>
    -X POST \
>
    -d '[
$
        {
$
            "traceId": "test-zipkin-trace-id-1",
$
            "id": "3e0f5885710776cd",
$
            "kind": "CLIENT",
$
            "name": "post",
$
            "duration": 508068,
$
            "localEndpoint": {
$
                "serviceName": "service-1",
$
                "ipv4": "127.0.0.1",
$
                "port": 8080
$
            },
$
            "tags": {
$
            }
$
        },
$
        {
$
            "traceId": "test-zipkin-trace-id-1",
$
            "parentId": "3e0f5885710776cd",
$
            "id": "asdf9asdn123lkasdf",
$
            "kind": "CLIENT",
$
            "name": "service 2 span",
$
            "duration": 2019,
$
            "localEndpoint": {
$
                "serviceName": "service-2",
$
                "ipv4": "127.0.0.1",
$
                "port": 8080
$
            },
$
            "tags": {
$
                "error.message": "Invalid credentials"
$
            }
$
        }
$
    ]' 'https://trace-api.newrelic.com/trace/v1'

Within a minute, the trace should be available in our distributed tracing UI. To find it, run a query for the trace.id. In this example, it was test-zipkin-trace-id-1. Note that you search by the transformed attribute of trace.id (not traceId).

To learn more:

• Learn where Trace API data shows up in the UI.
• Send data from an existing Zipkin instrumentation.
• Learn how to decorate spans by adding tags. This helps you customize how traces are displayed in our UI for a richer, more helpful experience.
• Learn about general endpoint information (data limits, required metadata, and response validation).
• Learn about how Zipkin data is transformed and stored in our format.
• If you don't see your trace data, see Troubleshooting.

Send data from existing Zipkin instrumentation

Preliminary notes:

• If you want to enable Infinite Tracing, you first must set up a trace observer.
• It can be helpful to first send a sample payload to verify things are working properly.

To report data from an existing Zipkin instrumentation, you'll point the Zipkin tracer at the appropriate Trace API endpoint with some required request metadata. You can send the required metadata as headers or query parameters (some Zipkin tracer versions don't allow specifying HTTP headers).

Here's an example of what it might look like to create a Zipkin OkHttpSender in Java configured for the Trace API:

OkHttpSender.create("https://trace-api.newrelic.com/trace/v1?Api-Key=NEW_RELIC_LICENSE_KEY&Data-Format=zipkin&Data-Format-Version=2");

Note that if you were using Infinite Tracing, or had an EU-region New Relic account, the endpoint would be different.

For an explanation of Api-Key and the other metadata, see Request metadata.

Transformation of Zipkin data

To create a consistent search/query experience, some Zipkin data will be transformed to match New Relic attribute naming. For more on how we store and structure trace data, see How distributed tracing works.

Add other tags/attributes

You can add any tags you want to the tags block, with the exception of the restricted tags. For example, you might want to add attributes like customer.id or user.id to help you analyze your trace data. Tags will be converted to New Relic attributes.

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.