1# OpenCensus Stackdriver Trace Exporter
2[![Build Status][travis-image]][travis-url]
3[![Windows Build Status][appveyor-image]][appveyor-url]
4[![Maven Central][maven-image]][maven-url]
5
6The *OpenCensus Stackdriver Trace Exporter* is a trace exporter that exports data to
7Stackdriver Trace. [Stackdriver Trace][stackdriver-trace] is a distributed
8tracing system that collects latency data from your applications and displays it in the Google
9Cloud Platform Console. You can track how requests propagate through your application and receive
10detailed near real-time performance insights.
11
12## Quickstart
13
14### Prerequisites
15
16To use this exporter, you must have an application that you'd like to trace. The app can be on
17Google Cloud Platform, on-premise, or another cloud platform.
18
19In order to be able to push your traces to [Stackdriver Trace][stackdriver-trace], you must:
20
211. [Create a Cloud project](https://support.google.com/cloud/answer/6251787?hl=en).
222. [Enable billing](https://support.google.com/cloud/answer/6288653#new-billing).
233. [Enable the Stackdriver Trace API](https://console.cloud.google.com/apis/api/cloudtrace.googleapis.com/overview).
24
25These steps enable the API but don't require that your app is hosted on Google Cloud Platform.
26
27### Hello "Stackdriver Trace"
28
29#### Add the dependencies to your project
30
31For Maven add to your `pom.xml`:
32```xml
33<dependencies>
34  <dependency>
35    <groupId>io.opencensus</groupId>
36    <artifactId>opencensus-api</artifactId>
37    <version>0.16.1</version>
38  </dependency>
39  <dependency>
40    <groupId>io.opencensus</groupId>
41    <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
42    <version>0.16.1</version>
43  </dependency>
44  <dependency>
45    <groupId>io.opencensus</groupId>
46    <artifactId>opencensus-impl</artifactId>
47    <version>0.16.1</version>
48    <scope>runtime</scope>
49  </dependency>
50</dependencies>
51```
52
53For Gradle add to your dependencies:
54```groovy
55compile 'io.opencensus:opencensus-api:0.16.1'
56compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.16.1'
57runtime 'io.opencensus:opencensus-impl:0.16.1'
58```
59
60#### Register the exporter
61
62This uses the default configuration for authentication and project ID.
63
64```java
65public class MyMainClass {
66  public static void main(String[] args) throws Exception {
67    StackdriverTraceExporter.createAndRegister(
68        StackdriverTraceConfiguration.builder().build());
69    // ...
70  }
71}
72```
73
74#### Authentication
75
76This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java),
77for details about how to configure the authentication see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#authentication).
78
79If you prefer to manually set the credentials use:
80```
81StackdriverTraceExporter.createAndRegisterWithCredentialsAndProjectId(
82    new GoogleCredentials(new AccessToken(accessToken, expirationTime)),
83    "MyStackdriverProjectId");
84```
85
86#### Specifying a Project ID
87
88This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java),
89for details about how to configure the project ID see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#specifying-a-project-id).
90
91If you prefer to manually set the project ID use:
92```
93StackdriverTraceExporter.createAndRegisterWithProjectId("MyStackdriverProjectId");
94```
95
96#### Enable Stackdriver Trace API access scope on Google Cloud Platform
97If your Stackdriver Trace Exporter is running on Kubernetes Engine or Compute Engine,
98you might need additional setup to explicitly enable the ```trace.append``` Stackdriver
99Trace API access scope. To do that, please follow the instructions for
100[GKE](https://cloud.google.com/trace/docs/setup/java#kubernetes_engine) or
101[GCE](https://cloud.google.com/trace/docs/setup/java#compute_engine).
102
103#### Java Versions
104
105Java 7 or above is required for using this exporter.
106
107## FAQ
108### Why do I not see some trace events in Stackdriver?
109In all the versions before '0.9.1' the Stackdriver Trace exporter was implemented using the [v1
110API][stackdriver-v1-api-url] which is not fully compatible with the OpenCensus data model. Trace
111events like Annotations and NetworkEvents will be dropped.
112
113### Why do I get a "StatusRuntimeException: NOT_FOUND: Requested entity was not found"?
114One of the possible reasons is you are using a project id with bad format for the exporter.
115Please double check the project id associated with the Stackdriver Trace exporter first.
116Stackdriver Trace backend will not do any sanitization or trimming on the incoming project id.
117Project id with leading or trailing spaces will be treated as a separate non-existing project
118(e.g "project-id" vs "project-id "), and will cause a NOT_FOUND exception.
119
120[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master
121[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java
122[appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true
123[appveyor-url]: https://ci.appveyor.com/project/opencensusjavateam/opencensus-java/branch/master
124[maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-exporter-trace-stackdriver/badge.svg
125[maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-exporter-trace-stackdriver
126[stackdriver-trace]: https://cloud.google.com/trace/
127[stackdriver-v1-api-url]: https://cloud.google.com/trace/docs/reference/v1/rpc/google.devtools.cloudtrace.v1#google.devtools.cloudtrace.v1.TraceSpan
128