Using Stackdriver Trace with Zipkin

This tutorial uses a Zipkin server to receive traces from Zipkin clients and forward those traces to Stackdriver Trace for analysis.

The Zipkin server is useful for developers of applications that are already instrumented with Zipkin who either don’t want to run their own trace backend or want access to Stackdriver Trace’s advanced analysis tools.

Note that this functionality is maintained by the Zipkin project itself and is not officially supported by Google.

There are several ways to set this up:

Using a container image to set up your server

A container image of the Stackdriver Trace Zipkin Collector is available on GitHub. This repository contains the Docker build definition and layers GCP support on the base Zipkin Docker image, in addition to detailed setup steps.

You can run this on your container host of choice, including Google Kubernetes Engine.

To run the image:

$ docker run -d -p 9411:9411 \
-e STORAGE_TYPE=stackdriver \
-e GOOGLE_APPLICATION_CREDENTIALS=/root/.gcp/credentials.json \
-e STACKDRIVER_PROJECT_ID=your_project \
-v $HOME/.gcp:/root/.gcp:ro \

If you are running this container within the Google Cloud Platform (such as on a Compute Engine instance or Google Kubernetes Engine cluster), it will automatically capture the environment's default credentials and will attempt to send traces to Stackdriver Trace.

See the full setup process here.

You must also configure your Zipkin tracers.

Running your server outside of Google Cloud Platform

If you would like to build and run the collector outside of GCP, such as on a physical server running on-premises:

Create or select a project

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

A billing account is not required, as the collector will not be running on Google resources.

Create a service account

To allow your service to authenticate to the Stackdriver Trace API:

  1. Create a service account.
    1. Ensure that the new service account has been granted a project editor role so that it can write data to the Trace API.
    2. Select Furnish a new private key and choose JSON.
    3. Save the JSON credentials file to a directory on the machine that will be running the collector service.

Configure your firewall

Configure your network configuration to allow TCP traffic on port 9411 to pass to the machine running the Zipkin collector.

If you'll be submitting traces from applications hosted outside of the firewall, note that Zipkin tracer to collector traffic is not encrypted or authenticated. Connections between the Stackdriver Trace Zipkin Collector and the Stackdriver Trace API are encrypted and authenticated, as are connections sourced from the Stackdriver Trace instrumentation libraries.

Set up your server with the container image

See Using a container image, above.

Configure Zipkin tracers

Follow the instructions in the common Configure Zipkin tracers section.

Modifying an existing Zipkin server

The Zipkin project maintains instructions on how to use Stackdriver Trace as a storage destination for an existing Zipkin server. These are available on GitHub here.

How to Configure Zipkin tracers

No matter how you host the Stackdriver Trace Zipkin Collector, you'll need to configure your Zipkin tracers to send data to it.

The collector can be referenced by its internal IP address, external IP address (if it will be receiving traces from applications hosted outside of Google Cloud Platform), or hostname. Each Zipkin tracer is configured differently - for example, to point a Brave tracer at a collector with the IP address, the following lines must be added to your Java codebase:

Reporter reporter = AsyncReporter.builder(OkHttpSender.create("")).build();
Brave brave = Brave.Builder("example").reporter(reporter).build()

Frequently asked questions

Q: What are the limitations?

This release has two known limitations:

  1. Zipkin tracers must support the correct Zipkin time and duration semantics. For more information, go to Instrumenting a library and scroll down to the section on Timestamps and duration.

  2. Zipkin tracers and the Stackdriver Trace instrumentation libraries can't append spans to the same traces, meaning that traces that are captured in one library won't contain spans for services instrumented in the other type of library. For example:

    Requests made to the Node.js web application will be traced with the Zipkin library and sent to Stackdriver Trace. However, these traces will not contain spans generated within the API application or for the RPC calls that it makes to the Database. This is because Zipkin and Stackdriver Trace use different formats for propagating trace context between services.

    For this reason we recommend that projects wanting to use Stackdriver Trace either exclusively use Zipkin-compatible tracers along with the Zipkin Collector, or use instrumentation libraries that work natively with Stackdriver Trace (like the official Node.js, Java, or Go libraries).

Q: Will this work as a full Zipkin server?

No, this feature only writes data to Stackdriver Trace.

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Trace Documentation