• English日本語한국어
  • Log inStart now

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 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.
bash
$
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:

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:

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.

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. If no value or an empty string is provided, the span is assigned to an "UNKNOWN" entity and will show as such in the UI. This value should be provided to get a complete experience in the UI.

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.