Report Zipkin-format traces via Trace API

Our Trace API accepts two types of data formats:

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

Zipkin data is only accepted for standard distributed tracing.

This document explains how to send Zipkin data.

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.

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. Get an Insert API key: Go to: one.newrelic.com > account dropdown > Account settings > API keys, and select Insights API keys. 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 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: INSERT_YOUR_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": {
                 }
             }
         ]' 'https://trace-api.newrelic.com/trace/v1'
    

Within a minute, the trace should be available in the our distributed tracing UI. To find it, run a query for the trace.id. In this example, it was test-zipkin-trace-id-1 and we search by the translated term of trace.id.

Distributed Tracing Zipkin Integration Searching for sample trace

Learn more:

Send data from existing Zipkin instrumentation

To report data from your Zipkin instrumentation, you will point the Zipkin tracer at the 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 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 we store and structure trace data, see How distributed tracing works.

Zipkin tag Stored in New Relic as... Details
traceId trace.id Unique identifier for a trace.
id id Unique identifier for a span.
parentId parent.id Identifier of the upstream span that called the service.
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 We use the Zipkin v2 service name 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 We do not currently support annotations in the 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

If you need more help, check out these support and learning resources: