1 # OpenCensus Stackdriver Stats Exporter 2 3 The *OpenCensus Stackdriver Stats Exporter* is a stats exporter that exports data to 4 Stackdriver Monitoring. [Stackdriver Monitoring][stackdriver-monitoring] provides visibility into 5 the performance, uptime, and overall health of cloud-powered applications. Stackdriver ingests that 6 data and generates insights via dashboards, charts, and alerts. 7 8 ## Quickstart 9 10 ### Prerequisites 11 12 To use this exporter, you must have an application that you'd like to monitor. The app can be on 13 Google Cloud Platform, on-premise, or another cloud platform. 14 15 In order to be able to push your stats to [Stackdriver Monitoring][stackdriver-monitoring], you must: 16 17 1. [Create a Cloud project](https://support.google.com/cloud/answer/6251787?hl=en). 18 2. [Enable billing](https://support.google.com/cloud/answer/6288653#new-billing). 19 3. [Enable the Stackdriver Monitoring API](https://console.cloud.google.com/apis/dashboard). 20 21 These 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 27 For 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 49 For Gradle add to your dependencies: 50 ```groovy 51 compile 'io.opencensus:opencensus-api:0.16.1' 52 compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.16.1' 53 runtime 'io.opencensus:opencensus-impl:0.16.1' 54 ``` 55 56 #### Register the exporter 57 58 This uses the default configuration for authentication and a given project ID. 59 60 ```java 61 public 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 71 By default, Stackdriver Stats Exporter will try to automatically detect the environment if your 72 application is running on GCE, GKE or AWS EC2, and generate a corresponding Stackdriver GCE/GKE/EC2 73 monitored resource. For GKE particularly, you may want to set up some environment variables so that 74 Exporter 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) 76 and [here](https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/). 77 78 Otherwise, Exporter will use [a global Stackdriver monitored resource with a project_id label](https://cloud.google.com/monitoring/api/resources#tag_global), 79 and it works fine when you have only one exporter running. 80 81 If you want to have multiple processes exporting stats for the same metric concurrently, and your 82 application is running on some different environment than GCE, GKE or AWS EC2 (for example DataFlow), 83 please associate a unique monitored resource with each exporter if possible. 84 Please note that there is also an "opencensus_task" metric label that uniquely identifies the 85 uploaded stats. 86 87 To set a custom MonitoredResource: 88 89 ```java 90 public 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 108 For a complete list of valid Stackdriver monitored resources, please refer to [Stackdriver 109 Documentation](https://cloud.google.com/monitoring/custom-metrics/creating-metrics#which-resource). 110 Please also note that although there are a lot of monitored resources available on [Stackdriver](https://cloud.google.com/monitoring/api/resources), 111 only [a small subset of them](https://cloud.google.com/monitoring/custom-metrics/creating-metrics#which-resource) 112 are compatible with the Opencensus Stackdriver Stats Exporter. 113 114 #### Authentication 115 116 This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java), 117 for details about how to configure the authentication see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#authentication). 118 119 If you prefer to manually set the credentials use: 120 ``` 121 StackdriverStatsExporter.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 131 This exporter uses [google-cloud-java](https://github.com/GoogleCloudPlatform/google-cloud-java), 132 for details about how to configure the project ID see [here](https://github.com/GoogleCloudPlatform/google-cloud-java#specifying-a-project-id). 133 134 If you prefer to manually set the project ID use: 135 ``` 136 StackdriverStatsExporter.createAndRegister( 137 StackdriverStatsConfiguration.builder().setProjectId("MyStackdriverProjectId").build()); 138 ``` 139 140 #### Java Versions 141 142 Java 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? 146 To use our Stackdriver Stats exporter, you need to set up billing for your cloud project, since 147 creating and uploading custom metrics to Stackdriver Monitoring is 148 [not free](https://cloud.google.com/stackdriver/pricing_v2#monitoring-costs). 149 150 To enable billing, follow the instructions [here](https://support.google.com/cloud/answer/6288653#new-billing). 151 152 ### What is "opencensus_task" metric label ? 153 Stackdriver 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. 155 Stackdriver exporter adds a new `Metric` label for each custom `Metric` to ensure the uniqueness 156 of the `Timeseries`. The format of the label is: `{LANGUAGE}-{PID}@{HOSTNAME}`, if `{PID}` is not 157 available 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"? 160 This is probably because there is a version conflict on Guava in the dependency tree. 161 162 For example, `com.google.common.base.Throwables.throwIfInstanceOf` is introduced to Guava 20.0. 163 If 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 167 In this case, please either add an explicit dependency on a newer version of Guava that has the 168 new method (20.0 in the previous example), or if possible, upgrade the dependency that depends on 169 Guava 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
