Using Stackdriver Trace with Zipkin

This page describes how to use a Zipkin server to receive traces from Zipkin clients and forward those traces to Stackdriver Trace for analysis.

You might want to use a Zipkin server if your application is are already instrumented with Zipkin and either you don't want to run your own trace backend or you want access to Stackdriver Trace's advanced analysis tools.

This page describes several ways to set up your Zipkin server:

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 (GCP), such as on a Compute Engine instance or Google Kubernetes Engine cluster, the environment's default credentials are automatically captured and traces are automatically sent to Stackdriver Trace.

For the full setup process, go to the GitHub repository for the Zipkin Docker image.

As described on this page, you must also configure your Zipkin tracers.

Running your server outside of GCP

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

Create or select a project

  1. Sign in to your Google Account.


  2. Select or create a GCP project.

    Go to the project selector page

A billing account isn't required as the collector won't be running on GCP.

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 on this page.

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 the GitHub repository for the Zipkin Docker image.

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:

    Illustration of span limitations.

    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
Need help? Visit our support page.