OpenCensus Stackdriver Trace Exporter

The OpenCensus Stackdriver Trace Exporter is a trace exporter that exports data to Stackdriver Trace. Stackdriver Trace is a distributed tracing system that collects latency data from your applications and displays it in the Google Cloud Platform Console. You can track how requests propagate through your application and receive detailed near real-time performance insights.

Quickstart

Prerequisites

To use this exporter, you must have an application that you'd like to trace. The app can be on Google Cloud Platform, on-premise, or another cloud platform.

In order to be able to push your traces to Stackdriver Trace, you must:

1. Create a Cloud project.
2. Enable billing.
3. Enable the Stackdriver Trace API.

These steps enable the API but don't require that your app is hosted on Google Cloud Platform.

Hello “Stackdriver Trace”

Add the dependencies to your project

For Maven add to your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-api</artifactId>
    <version>0.16.1</version>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
    <version>0.16.1</version>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-impl</artifactId>
    <version>0.16.1</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

compile 'io.opencensus:opencensus-api:0.16.1'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.16.1'
runtime 'io.opencensus:opencensus-impl:0.16.1'

Register the exporter

This uses the default configuration for authentication and project ID.

public class MyMainClass {
  public static void main(String[] args) throws Exception {
    StackdriverTraceExporter.createAndRegister(
        StackdriverTraceConfiguration.builder().build());
    // ...
  }
}

Authentication

This exporter uses google-cloud-java, for details about how to configure the authentication see here.

If you prefer to manually set the credentials use:

StackdriverTraceExporter.createAndRegisterWithCredentialsAndProjectId(
    new GoogleCredentials(new AccessToken(accessToken, expirationTime)),
    "MyStackdriverProjectId");

Specifying a Project ID

This exporter uses google-cloud-java, for details about how to configure the project ID see here.

If you prefer to manually set the project ID use:

StackdriverTraceExporter.createAndRegisterWithProjectId("MyStackdriverProjectId");

Enable Stackdriver Trace API access scope on Google Cloud Platform

If your Stackdriver Trace Exporter is running on Kubernetes Engine or Compute Engine, you might need additional setup to explicitly enable the trace.append Stackdriver Trace API access scope. To do that, please follow the instructions for GKE or GCE.

Java Versions

Java 7 or above is required for using this exporter.

FAQ

Why do I not see some trace events in Stackdriver?

In all the versions before ‘0.9.1’ the Stackdriver Trace exporter was implemented using the v1 API which is not fully compatible with the OpenCensus data model. Trace events like Annotations and NetworkEvents will be dropped.

Why do I get a “StatusRuntimeException: NOT_FOUND: Requested entity was not found”?

One of the possible reasons is you are using a project id with bad format for the exporter. Please double check the project id associated with the Stackdriver Trace exporter first. Stackdriver Trace backend will not do any sanitization or trimming on the incoming project id. Project id with leading or trailing spaces will be treated as a separate non-existing project (e.g “project-id” vs "project-id "), and will cause a NOT_FOUND exception.