• Home
Name Date Size #Lines LOC

..--

src/03-May-2024-2,4011,740

README.mdD03-May-20247.7 KiB172134

build.gradleD03-May-2024866 3022

README.md

1# OpenCensus Stackdriver Stats Exporter
2
3The *OpenCensus Stackdriver Stats Exporter* is a stats exporter that exports data to
4Stackdriver Monitoring. [Stackdriver Monitoring][stackdriver-monitoring] provides visibility into
5the performance, uptime, and overall health of cloud-powered applications. Stackdriver ingests that
6data and generates insights via dashboards, charts, and alerts.
7
8## Quickstart
9
10### Prerequisites
11
12To use this exporter, you must have an application that you'd like to monitor. The app can be on
13Google Cloud Platform, on-premise, or another cloud platform.
14
15In order to be able to push your stats to [Stackdriver Monitoring][stackdriver-monitoring], you must:
16
171. [Create a Cloud project](https://support.google.com/cloud/answer/6251787?hl=en).
182. [Enable billing](https://support.google.com/cloud/answer/6288653#new-billing).
193. [Enable the Stackdriver Monitoring API](https://console.cloud.google.com/apis/dashboard).
20
21These steps enable the API but don't require that your app is hosted on Google Cloud Platform.
22
23### Hello "Stackdriver Stats"
24
25#### Add the dependencies to your project
26
27For Maven add to your `pom.xml`:
28```xml
29<dependencies>
30  <dependency>
31    <groupId>io.opencensus</groupId>
32    <artifactId>opencensus-api</artifactId>
33    <version>0.16.1</version>
34  </dependency>
35  <dependency>
36    <groupId>io.opencensus</groupId>
37    <artifactId>opencensus-exporter-stats-stackdriver</artifactId>
38    <version>0.16.1</version>
39  </dependency>
40  <dependency>
41    <groupId>io.opencensus</groupId>
42    <artifactId>opencensus-impl</artifactId>
43    <version>0.16.1</version>
44    <scope>runtime</scope>
45  </dependency>
46</dependencies>
47```
48
49For Gradle add to your dependencies:
50```groovy
51compile 'io.opencensus:opencensus-api:0.16.1'
52compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.16.1'
53runtime 'io.opencensus:opencensus-impl:0.16.1'
54```
55
56#### Register the exporter
57
58This uses the default configuration for authentication and a given project ID.
59
60```java
61public class MyMainClass {
62  public static void main(String[] args) {
63    StackdriverStatsExporter.createAndRegister(
64        StackdriverStatsConfiguration.builder().build());
65  }
66}
67```
68
69#### Set Monitored Resource for exporter
70
71By default, Stackdriver Stats Exporter will try to automatically detect the environment if your
72application is running on GCE, GKE or AWS EC2, and generate a corresponding Stackdriver GCE/GKE/EC2
73monitored resource. For GKE particularly, you may want to set up some environment variables so that
74Exporter can correctly identify your pod, cluster and container. Follow the Kubernetes instruction
75[here](https://cloud.google.com/kubernetes-engine/docs/tutorials/custom-metrics-autoscaling#exporting_metrics_from_the_application)
76and [here](https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/).
77
78Otherwise, Exporter will use [a global Stackdriver monitored resource with a project_id label](https://cloud.google.com/monitoring/api/resources#tag_global),
79and it works fine when you have only one exporter running.
80
81If you want to have multiple processes exporting stats for the same metric concurrently, and your
82application is running on some different environment than GCE, GKE or AWS EC2 (for example DataFlow),
83please associate a unique monitored resource with each exporter if possible.
84Please note that there is also an "opencensus_task" metric label that uniquely identifies the
85uploaded stats.
86
87To set a custom MonitoredResource:
88
89```java
90public class MyMainClass {
91  public static void main(String[] args) {
92    // A sample DataFlow monitored resource.
93    MonitoredResource myResource = MonitoredResource.newBuilder()
94                                               .setType("dataflow_job")
95                                               .putLabels("project_id", "my_project")
96                                               .putLabels("job_name", "my_job")
97                                               .putLabels("region", "us-east1")
98                                               .build();
99
100    // Set a custom MonitoredResource. Please make sure each Stackdriver Stats Exporter has a
101    // unique MonitoredResource.
102    StackdriverStatsExporter.createAndRegister(
103        StackdriverStatsConfiguration.builder().setMonitoredResource(myResource).build());
104  }
105}
106```
107
108For a complete list of valid Stackdriver monitored resources, please refer to [Stackdriver
109Documentation](https://cloud.google.com/monitoring/custom-metrics/creating-metrics#which-resource).
110Please also note that although there are a lot of monitored resources available on [Stackdriver](https://cloud.google.com/monitoring/api/resources),
111only [a small subset of them](https://cloud.google.com/monitoring/custom-metrics/creating-metrics#which-resource)
112are compatible with the Opencensus Stackdriver Stats Exporter.
113
114#### Authentication
115
116This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java),
117for details about how to configure the authentication see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#authentication).
118
119If you prefer to manually set the credentials use:
120```
121StackdriverStatsExporter.createAndRegister(
122    StackdriverStatsConfiguration.builder()
123        .setCredentials(new GoogleCredentials(new AccessToken(accessToken, expirationTime)))
124        .setProjectId("MyStackdriverProjectId")
125        .setExportInterval(Duration.create(10, 0))
126        .build());
127```
128
129#### Specifying a Project ID
130
131This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java),
132for details about how to configure the project ID see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#specifying-a-project-id).
133
134If you prefer to manually set the project ID use:
135```
136StackdriverStatsExporter.createAndRegister(
137    StackdriverStatsConfiguration.builder().setProjectId("MyStackdriverProjectId").build());
138```
139
140#### Java Versions
141
142Java 7 or above is required for using this exporter.
143
144## FAQ
145### Why did I get a PERMISSION_DENIED error from Stackdriver when using this exporter?
146To use our Stackdriver Stats exporter, you need to set up billing for your cloud project, since
147creating and uploading custom metrics to Stackdriver Monitoring is
148[not free](https://cloud.google.com/stackdriver/pricing_v2#monitoring-costs).
149
150To enable billing, follow the instructions [here](https://support.google.com/cloud/answer/6288653#new-billing).
151
152### What is "opencensus_task" metric label ?
153Stackdriver requires that each Timeseries to be updated only by one task at a time. A
154`Timeseries` is uniquely identified by the `MonitoredResource` and the `Metric`'s labels.
155Stackdriver exporter adds a new `Metric` label for each custom `Metric` to ensure the uniqueness
156of the `Timeseries`. The format of the label is: `{LANGUAGE}-{PID}@{HOSTNAME}`, if `{PID}` is not
157available a random number will be used.
158
159### Why did I get an error "java.lang.NoSuchMethodError: com.google.common...", like "java.lang.NoSuchMethodError:com.google.common.base.Throwables.throwIfInstanceOf"?
160This is probably because there is a version conflict on Guava in the dependency tree.
161
162For example, `com.google.common.base.Throwables.throwIfInstanceOf` is introduced to Guava 20.0.
163If your application has a dependency that bundles a Guava with version 19.0 or below
164(for example, gRPC 1.10.0), it might cause a `NoSuchMethodError` since
165`com.google.common.base.Throwables.throwIfInstanceOf` doesn't exist before Guava 20.0.
166
167In this case, please either add an explicit dependency on a newer version of Guava that has the
168new method (20.0 in the previous example), or if possible, upgrade the dependency that depends on
169Guava to a newer version that depends on the newer Guava (for example, upgrade to gRPC 1.12.0).
170
171[stackdriver-monitoring]: https://cloud.google.com/monitoring/
172