1 # OpenCensus - A stats collection and distributed tracing framework 2 [![Gitter chat][gitter-image]][gitter-url] 3 [![Maven Central][maven-image]][maven-url] 4 [![Javadocs][javadoc-image]][javadoc-url] 5 [![Build Status][travis-image]][travis-url] 6 [![Windows Build Status][appveyor-image]][appveyor-url] 7 [![Coverage Status][codecov-image]][codecov-url] 8 9 10 OpenCensus is a toolkit for collecting application performance and behavior data. It currently 11 includes 3 apis: stats, tracing and tags. 12 13 The library is in [Beta](#versioning) stage and APIs are expected to be mostly stable. The 14 library is expected to move to [GA](#versioning) stage after v1.0.0 major release. 15 16 Please join [gitter](https://gitter.im/census-instrumentation/Lobby) for help or feedback on this 17 project. 18 19 ## OpenCensus Quickstart for Libraries 20 21 Integrating OpenCensus with a new library means recording stats or traces and propagating context. 22 For application integration please see [Quickstart for Applications](https://github.com/census-instrumentation/opencensus-java#quickstart-for-applications). 23 24 The full quick start example can also be found on the [OpenCensus website](https://opencensus.io/java/index.html). 25 26 ### Add the dependencies to your project 27 28 For Maven add to your `pom.xml`: 29 ```xml 30 <dependencies> 31 <dependency> 32 <groupId>io.opencensus</groupId> 33 <artifactId>opencensus-api</artifactId> 34 <version>0.16.1</version> 35 </dependency> 36 </dependencies> 37 ``` 38 39 For Gradle add to your dependencies: 40 ```gradle 41 compile 'io.opencensus:opencensus-api:0.16.1' 42 ``` 43 44 For Bazel add the following lines to the WORKSPACE file: 45 ``` 46 maven_jar( 47 name = "io_opencensus_opencensus_api", 48 artifact = "io.opencensus:opencensus-api:0.15.0", 49 sha1 = "9a098392b287d7924660837f4eba0ce252013683", 50 ) 51 ``` 52 Then targets can specify `@io_opencensus_opencensus_api//jar` as a dependency to depend on this jar: 53 ```bazel 54 deps = [ 55 "@io_opencensus_opencensus_api//jar", 56 ] 57 ``` 58 You may also need to import the transitive dependencies. See [generate external dependencies from 59 Maven projects](https://docs.bazel.build/versions/master/generate-workspace.html). 60 61 ### Hello "OpenCensus" trace events 62 63 Here's an example of creating a Span and record some trace annotations. Notice that recording the 64 annotations is possible because we propagate scope. 3rd parties libraries like SLF4J can integrate 65 the same way. 66 67 ```java 68 import io.opencensus.common.Scope; 69 import io.opencensus.trace.Tracer; 70 import io.opencensus.trace.Tracing; 71 import io.opencensus.trace.samplers.Samplers; 72 73 public final class MyClassWithTracing { 74 private static final Tracer tracer = Tracing.getTracer(); 75 76 public static void doWork() { 77 // Create a child Span of the current Span. Always record events for this span and force it to 78 // be sampled. This makes it easier to try out the example, but unless you have a clear use 79 // case, you don't need to explicitly set record events or sampler. 80 try (Scope ss = 81 tracer 82 .spanBuilder("MyChildWorkSpan") 83 .setRecordEvents(true) 84 .setSampler(Samplers.alwaysSample()) 85 .startScopedSpan()) { 86 doInitialWork(); 87 tracer.getCurrentSpan().addAnnotation("Finished initial work"); 88 doFinalWork(); 89 } 90 } 91 92 private static void doInitialWork() { 93 // ... 94 tracer.getCurrentSpan().addAnnotation("Important."); 95 // ... 96 } 97 98 private static void doFinalWork() { 99 // ... 100 tracer.getCurrentSpan().addAnnotation("More important."); 101 // ... 102 } 103 } 104 ``` 105 106 ### Hello "OpenCensus" stats events 107 108 Here's an example on 109 * defining TagKey, Measure and View, 110 * registering a view, 111 * putting TagKey and TagValue into a scoped TagContext, 112 * recording stats against current TagContext, 113 * getting ViewData. 114 115 116 For the complete example, see 117 [here](https://github.com/census-instrumentation/opencensus-java/blob/master/examples/src/main/java/io/opencensus/examples/helloworld/QuickStart.java). 118 119 ```java 120 import io.opencensus.common.Scope; 121 import io.opencensus.stats.Aggregation; 122 import io.opencensus.stats.BucketBoundaries; 123 import io.opencensus.stats.Measure.MeasureLong; 124 import io.opencensus.stats.Stats; 125 import io.opencensus.stats.StatsRecorder; 126 import io.opencensus.stats.View; 127 import io.opencensus.stats.ViewData; 128 import io.opencensus.stats.ViewManager; 129 import io.opencensus.tags.TagKey; 130 import io.opencensus.tags.TagValue; 131 import io.opencensus.tags.Tagger; 132 import io.opencensus.tags.Tags; 133 import java.util.Arrays; 134 import java.util.Collections; 135 136 public final class MyClassWithStats { 137 private static final Tagger tagger = Tags.getTagger(); 138 private static final ViewManager viewManager = Stats.getViewManager(); 139 private static final StatsRecorder statsRecorder = Stats.getStatsRecorder(); 140 141 // frontendKey allows us to break down the recorded data 142 private static final TagKey FRONTEND_KEY = TagKey.create("myorg_keys_frontend"); 143 144 // videoSize will measure the size of processed videos. 145 private static final MeasureLong VIDEO_SIZE = 146 MeasureLong.create("my.org/measure/video_size", "size of processed videos", "By"); 147 148 // Create view to see the processed video size distribution broken down by frontend. 149 // The view has bucket boundaries (0, 256, 65536) that will group measure values into 150 // histogram buckets. 151 private static final View.Name VIDEO_SIZE_VIEW_NAME = View.Name.create("my.org/views/video_size"); 152 private static final View VIDEO_SIZE_VIEW = 153 View.create( 154 VIDEO_SIZE_VIEW_NAME, 155 "processed video size over time", 156 VIDEO_SIZE, 157 Aggregation.Distribution.create( 158 BucketBoundaries.create(Arrays.asList(0.0, 256.0, 65536.0))), 159 Collections.singletonList(FRONTEND_KEY)); 160 161 public static void initialize() { 162 // ... 163 viewManager.registerView(VIDEO_SIZE_VIEW); 164 } 165 166 public static void processVideo() { 167 try (Scope scopedTags = 168 tagger 169 .currentBuilder() 170 .put(FRONTEND_KEY, TagValue.create("mobile-ios9.3.5")) 171 .buildScoped()) { 172 // Processing video. 173 // ... 174 175 // Record the processed video size. 176 statsRecorder.newMeasureMap().put(VIDEO_SIZE, 25648).record(); 177 } 178 } 179 180 public static void printStats() { 181 ViewData viewData = viewManager.getView(VIDEO_SIZE_VIEW_NAME); 182 System.out.println( 183 String.format("Recorded stats for %s:\n %s", VIDEO_SIZE_VIEW_NAME.asString(), viewData)); 184 } 185 } 186 ``` 187 188 ## OpenCensus Quickstart for Applications 189 190 Besides recording tracing/stats events the application also need to link the implementation, 191 setup exporters, and debugging [Z-Pages](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/zpages). 192 193 ### Add the dependencies to your project 194 195 For Maven add to your `pom.xml`: 196 ```xml 197 <dependencies> 198 <dependency> 199 <groupId>io.opencensus</groupId> 200 <artifactId>opencensus-api</artifactId> 201 <version>0.16.1</version> 202 </dependency> 203 <dependency> 204 <groupId>io.opencensus</groupId> 205 <artifactId>opencensus-impl</artifactId> 206 <version>0.16.1</version> 207 <scope>runtime</scope> 208 </dependency> 209 </dependencies> 210 ``` 211 212 For Gradle add to your dependencies: 213 ```gradle 214 compile 'io.opencensus:opencensus-api:0.16.1' 215 runtime 'io.opencensus:opencensus-impl:0.16.1' 216 ``` 217 218 For Bazel add the following lines to the WORKSPACE file: 219 ``` 220 maven_jar( 221 name = "io_opencensus_opencensus_api", 222 artifact = "io.opencensus:opencensus-api:0.15.0", 223 sha1 = "9a098392b287d7924660837f4eba0ce252013683", 224 ) 225 226 maven_jar( 227 name = "io_opencensus_opencensus_impl_core", 228 artifact = "io.opencensus:opencensus-impl-core:0.15.0", 229 sha1 = "36c775926ba1e54af7c37d0503cfb99d986f6229", 230 ) 231 232 maven_jar( 233 name = "io_opencensus_opencensus_impl", 234 artifact = "io.opencensus:opencensus-impl:0.15.0", 235 sha1 = "d7bf0d7ee5a0594f840271c11c9f8d6f754f35d6", 236 ) 237 ``` 238 Then add the following lines to BUILD.bazel file: 239 ```bazel 240 deps = [ 241 "@io_opencensus_opencensus_api//jar", 242 ] 243 runtime_deps = [ 244 "@io_opencensus_opencensus_impl_core//jar", 245 "@io_opencensus_opencensus_impl//jar", 246 ] 247 ``` 248 Again you may need to import the transitive dependencies. See [generate external dependencies from 249 Maven projects](https://docs.bazel.build/versions/master/generate-workspace.html). 250 251 ### How to setup exporters? 252 253 #### Trace exporters 254 * [Instana][TraceExporterInstana] 255 * [Jaeger][TraceExporterJaeger] 256 * [Logging][TraceExporterLogging] 257 * [Stackdriver][TraceExporterStackdriver] 258 * [Zipkin][TraceExporterZipkin] 259 260 #### Stats exporters 261 * [Stackdriver][StatsExporterStackdriver] 262 * [SignalFx][StatsExporterSignalFx] 263 * [Prometheus][StatsExporterPrometheus] 264 265 ### How to setup debugging Z-Pages? 266 267 If the application owner wants to export in-process tracing and stats data via HTML debugging pages 268 see this [link](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/zpages#quickstart). 269 270 ## Versioning 271 272 This library follows [Semantic Versioning][semver]. 273 274 **GA**: Libraries defined at a GA quality level are stable, and will not introduce 275 backwards-incompatible changes in any minor or patch releases. We will address issues and requests 276 with the highest priority. If we were to make a backwards-incompatible changes on an API, we will 277 first mark the existing API as deprecated and keep it for 18 months before removing it. 278 279 **Beta**: Libraries defined at a Beta quality level are expected to be mostly stable and we're 280 working towards their release candidate. We will address issues and requests with a higher priority. 281 There may be backwards incompatible changes in a minor version release, though not in a patch 282 release. If an element is part of an API that is only meant to be used by exporters or other 283 opencensus libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18 284 months before removing it, if possible. 285 286 [travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master 287 [travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java 288 [appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true 289 [appveyor-url]: https://ci.appveyor.com/project/opencensusjavateam/opencensus-java/branch/master 290 [javadoc-image]: https://www.javadoc.io/badge/io.opencensus/opencensus-api.svg 291 [javadoc-url]: https://www.javadoc.io/doc/io.opencensus/opencensus-api 292 [maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-api/badge.svg 293 [maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-api 294 [gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg 295 [gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge 296 [codecov-image]: https://codecov.io/gh/census-instrumentation/opencensus-java/branch/master/graph/badge.svg 297 [codecov-url]: https://codecov.io/gh/census-instrumentation/opencensus-java/branch/master/ 298 [semver]: http://semver.org/ 299 [TraceExporterInstana]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/instana#quickstart 300 [TraceExporterJaeger]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/jaeger#quickstart 301 [TraceExporterLogging]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/logging#quickstart 302 [TraceExporterStackdriver]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/stackdriver#quickstart 303 [TraceExporterZipkin]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/zipkin#quickstart 304 [StatsExporterStackdriver]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/stackdriver#quickstart 305 [StatsExporterSignalFx]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/signalfx#quickstart 306 [StatsExporterPrometheus]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/prometheus#quickstart 307
