blob: 43c435c62108b886ddce6d8128828632f0e65630 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
# OpenCensus Stackdriver Trace Exporter
[![Build Status][travis-image]][travis-url]
[![Windows Build Status][appveyor-image]][appveyor-url]
[![Maven Central][maven-image]][maven-url]
The *OpenCensus Stackdriver Trace Exporter* is a trace exporter that exports data to
Stackdriver Trace. [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][stackdriver-trace], you must:
1. [Create a Cloud project](https://support.google.com/cloud/answer/6251787?hl=en).
2. [Enable billing](https://support.google.com/cloud/answer/6288653#new-billing).
3. [Enable the Stackdriver Trace API](https://console.cloud.google.com/apis/api/cloudtrace.googleapis.com/overview).
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`:
```xml
<dependencies>
<dependency>
<groupId>io.opencensus</groupId>
<artifactId>opencensus-api</artifactId>
<version>0.12.2</version>
</dependency>
<dependency>
<groupId>io.opencensus</groupId>
<artifactId>opencensus-exporter-trace-stackdriver</artifactId>
<version>0.12.2</version>
</dependency>
<dependency>
<groupId>io.opencensus</groupId>
<artifactId>opencensus-impl</artifactId>
<version>0.12.2</version>
<scope>runtime</scope>
</dependency>
</dependencies>
```
For Gradle add to your dependencies:
```groovy
compile 'io.opencensus:opencensus-api:0.12.2'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.12.2'
runtime 'io.opencensus:opencensus-impl:0.12.2'
```
#### Register the exporter
This uses the default configuration for authentication and project ID.
```java
public class MyMainClass {
public static void main(String[] args) throws Exception {
StackdriverTraceExporter.createAndRegister(
StackdriverTraceConfiguration.builder().build());
// ...
}
}
```
#### Authentication
This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java),
for details about how to configure the authentication see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#authentication).
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](https://github.com/GoogleCloudPlatform/google-cloud-java),
for details about how to configure the project ID see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#specifying-a-project-id).
If you prefer to manually set the project ID use:
```
StackdriverTraceExporter.createAndRegisterWithProjectId("MyStackdriverProjectId");
```
#### 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][stackdriver-v1-api-url] which is not fully compatible with the OpenCensus data model. Trace
events like Annotations and NetworkEvents will be dropped.
[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master
[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java
[appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true
[appveyor-url]: https://ci.appveyor.com/project/opencensusjavateam/opencensus-java/branch/master
[maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-exporter-trace-stackdriver/badge.svg
[maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-exporter-trace-stackdriver
[stackdriver-trace]: https://cloud.google.com/trace/
[stackdriver-v1-api-url]: https://cloud.google.com/trace/docs/reference/v1/rpc/google.devtools.cloudtrace.v1#google.devtools.cloudtrace.v1.TraceSpan
|
