Home | History | Annotate | only in /external/opencensus-java
Up to higher level directory
NameDateSize
.github/22-Oct-2020
.gitmodules22-Oct-20200
.travis.yml22-Oct-20202K
all/22-Oct-2020
api/22-Oct-2020
appveyor.yml22-Oct-2020588
AUTHORS22-Oct-202011
benchmarks/22-Oct-2020
build.gradle22-Oct-202020.7K
buildscripts/22-Oct-2020
CHANGELOG.md22-Oct-20207K
checker-framework/22-Oct-2020
contrib/22-Oct-2020
CONTRIBUTING.md22-Oct-20205.7K
examples/22-Oct-2020
exporters/22-Oct-2020
findbugs-exclude.xml22-Oct-20203.7K
gradle/22-Oct-2020
gradlew22-Oct-20205.2K
gradlew.bat22-Oct-20202.2K
impl/22-Oct-2020
impl_core/22-Oct-2020
impl_lite/22-Oct-2020
LICENSE22-Oct-202011.1K
OWNERS22-Oct-2020408
README.md22-Oct-202011.8K
RELEASING.md22-Oct-202011.3K
scripts/22-Oct-2020
settings.gradle22-Oct-20204.1K
testing/22-Oct-2020

README.md

      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