Using Cloud Trace with Zipkin

This page describes how to use a Zipkin server to receive traces from Zipkin clients and forward those traces to Cloud 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 Cloud 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 Cloud Trace Zipkin Collector is available on GitHub. This repository contains the Docker build definition and layers Google Cloud 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, 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 Cloud 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 Google Cloud

If you would like to build and run the collector outside of Google Cloud, 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.

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

  2. In the Cloud Console, on the project selector page, select or create a Cloud project.

    Go to the project selector page

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

Create a service account

To allow your service to authenticate to the Cloud 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 Cloud Trace Zipkin collector and the Cloud Trace API are encrypted and authenticated, as are connections sourced from the Cloud 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 Cloud 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 Cloud 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), 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 Cloud 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 Cloud 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 Cloud Trace use different formats for propagating trace context between services.

    For this reason we recommend that projects wanting to use Cloud Trace either exclusively use Zipkin-compatible tracers along with the Zipkin Collector, or use instrumentation libraries that work natively with Cloud 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 Cloud Trace.