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 two groups of people: developers who want to use Stackdriver Trace whose applications aren’t written in a language or framework that the official libraries yet support, and owners 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.

We’re providing the code for this server on GitHub with a permissive license, as well as a container image for quick set-up.

This tutorial provides instructions for three different scenarios:

Option 1: Using a container image to set up your server

A container image of the Stackdriver Trace Zipkin Collector is hosted in Google Container Registry. You can run this on your container host of choice.

To pull the image:

docker pull gcr.io/stackdriver-trace-docker/zipkin-collector

You must also configure your Zipkin tracers.

Option 2: Using a Maven JAR on Google Compute Engine to set up your server

To configure the collector on Google Compute Engine, you'll acquire the .jar file from Maven and run it on a new VM.

Create or select a project and enable billing

  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 Cloud Platform project.

    Go to the Projects page

  3. Enable billing for your project.

    Enable billing

Create a Compute Engine instance

When creating your instance, we recommend the default Debian GNU/Linux image.

When prompted, select the Compute Engine Default Service Account. Custom service accounts will also work if they have been granted a project editor role.

  1. In the Cloud Platform Console, go to the VM Instances page.

    Go to the VM Instances page

  2. Click the Create instance button.
  3. Click the Create button to create the instance.

Run the script

Run the following script. If you're using a Google-provided Linux image, you can configure this as a startup script directly in the Cloud Console. This will automatically fetch the JAR from Maven.

set -e
set -v

# Talk to the metadata server to get the project id
PROJECT_ID=$(curl -s "http://metadata.google.internal/computeMetadata/v1/project/project-id" -H "Metadata-Flavor: Google")

apt-get update
apt-get install -yq openjdk-8-jre-headless

wget -O collector.jar 'https://search.maven.org/remote_content?g=com.google.cloud.trace.adapters.zipkin&a=collector&v=LATEST'

PROJECT_ID=$PROJECT_ID java -jar collector.jar

Configure the firewall

If the collector will be receiving telemetry from tracers hosted outside of Google Cloud Platform, configure your project's firewall to accept TCP traffic on port 9411.

Configure Zipkin tracers

Follow the instructions in the common Configure Zipkin tracers section.

Option 3: Running your server outside of Google Cloud Platform

If you would like to build and run the collector outside of Google Cloud, such as on a VM on Amazon Elastic Cloud Compute or 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 Cloud Platform project.

    Go to the Projects 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.

Build the code

  1. Download the latest code from the master branch of the Stackdriver Trace Zipkin Collector project on GitHub. This can be done in one of two ways:
  2. Build the code: mvn package
  3. Configure credentials by setting the GOOGLE_APPLICATION_CREDENTIALS and PROJECT_ID environment variables by running the following script within the repository's working directory. Replace the placeholder values with your own specific values:
    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json" PROJECT_ID="my_project_id"
  4. Run the generated JAR file: java -jar collector/target/collector-*.jar
    1. If desired, you can configure this jar to run upon system startup.

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.

Configure Zipkin tracers

Follow the instructions in the common Configure Zipkin tracers section.

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 1.2.3.4, the following lines must be added to your Java codebase:

Reporter reporter = AsyncReporter.builder(OkHttpSender.create("1.2.3.4:9411/api/v1/spans")).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.

  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, as the initial release only supports write operations.

Q: How much does Stackdriver Trace cost?

You can use Zipkin with Stackdriver Trace for free.

Q: Can I use Stackdriver Trace to analyze my AWS, on-premises, or hybrid applications or is it strictly for services running on Google Cloud Platform?

Several projects already do this today! Stackdriver Trace will analyze all data submitted through its API, regardless of where the instrumented service is hosted, meaning that traces and spans collected from the Stackdriver Trace instrumentation libraries or through the Zipkin Collector can be used anywhere.

Send feedback about...

Stackdriver Trace Documentation