• /
  • Log in
  • Free account

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 '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": "",
               "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": "",
               "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).

Distributed Tracing Zipkin Integration Searching for sample trace

To learn more:

Send data from existing Zipkin instrumentation

Preliminary notes:

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:


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.

Zipkin tag

Stored in New Relic as...




Unique identifier for a trace.



Unique identifier for a span.



Identifier of the upstream span that called the service.



Either Client or Server.



Name of span.



Zipkin v2 spans must have durations specified in microseconds, and will be converted to milliseconds.

localEndpoint: serviceName


We use the Zipkin v2 service name to identify the entity that created this span.

localEndpoint: port


All values in the localEndpoint object will be flattened to a span attribute called localEndpoint.key


reported as attributes

Key:value pairs in the tags object in Zipkin v2 will be written as span attributes.


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.

Create issueEdit page
Copyright © 2022 New Relic Inc.