Report Zipkin-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 Zipkin data.

Zipkin version requirements

The New Relic 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.

Quick start: Send Zipkin data via cURL request

This procedure describes how to send a simple Zipkin trace to New Relic. Alternatively, you can go to Report data from existing Zipkin instrumentation.

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 +.

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

    • To copy the JSON, hover over the code to see a Copy button.
    • If you send more than one post, change the traceId 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: [API KEY HERE]' \
     -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": {
                 }
             }
         ]' 'https://trace-api.newrelic.com/trace/v1'
    

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

Trace API query by traceId

Learn more:

Send data from existing Zipkin instrumentation

To report data from your Zipkin instrumentation, you will point the Zipkin tracer at the New Relic Trace API endpoint (https://trace-api.newrelic.com/trace/v1) 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 New Relic Trace API:

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

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 New Relic stores and structures trace data, see How distributed tracing works.

Zipkin tag Stored in New Relic as... Details
id id Unique identifier for a span.
kind kind Either Client or Server.
name name Name of span.
duration duration.ms Zipkin v2 spans must have durations specified in microseconds, and will be converted to milliseconds.
localEndpoint: serviceName service.name Zipkin v2 service name is used by New Relic to identify the entity that created this span.
localEndpoint: port localEndpoint.port All values in the localEndpoint object will be flattened to a span attribute called localEndpoint.key
tags reported as attributes Key:value pairs in the tags object in Zipkin v2 will be written as span attributes.
annotations not supported New Relic does not currently support annotations in our trace API. Spans will not be rejected if they contain annotations, but the annotations data will not be written.

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.

For more help

Recommendations for learning more: