commit	ff7a9912401795e247b804174b1bec55ccd292b1	[log] [tgz]
author	Bogdan Drutu <bdrutu@google.com>	Mon Jun 04 12:02:19 2018 -0700
committer	GitHub <noreply@github.com>	Mon Jun 04 12:02:19 2018 -0700
tree	cc9beeb8e9df6544b7b36c67887430f8db32fd8d
parent	69d4053ca342d8e480d6342aa4579c416f45eaf9 [diff]

tree: cc9beeb8e9df6544b7b36c67887430f8db32fd8d

README.md

OpenCensus - A stats collection and distributed tracing framework

OpenCensus is a toolkit for collecting application performance and behavior data. It currently includes 3 apis: stats, tracing and tags.

The library is in alpha stage and the API is subject to change.

Please join gitter for help or feedback on this project.

OpenCensus Quickstart

Integrating OpenCensus with a new library means recording stats or traces and propagating context.

The full quick start example can also be found on the OpenCensus website.

Add the dependencies to your project

For Maven add to your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-api</artifactId>
    <version>0.13.2</version>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

compile 'io.opencensus:opencensus-api:0.13.2'

Hello "OpenCensus" trace events

Here's an example of creating a Span and record some trace annotations. Notice that recording the annotations is possible because we propagate scope. 3rd parties libraries like SLF4J can integrate the same way.

public final class MyClassWithTracing {
  private static final Tracer tracer = Tracing.getTracer();

  public static void doWork() {
    // Create a child Span of the current Span. Always record events for this span and force it to 
    // be sampled. This makes it easier to try out the example, but unless you have a clear use 
    // case, you don't need to explicitly set record events or sampler.
    try (Scope ss = 
         tracer.spanBuilder("MyChildWorkSpan")
           .setRecordEvents(true)
           .setSampler(Samplers.alwaysSample())
           .startScopedSpan()) {
      doInitialWork();
      tracer.getCurrentSpan().addAnnotation("Finished initial work");
      doFinalWork();
    }
  }

  private static void doInitialWork() {
    // ...
    tracer.getCurrentSpan().addAnnotation("Important.");
    // ...
  }

  private static void doFinalWork() {
    // ...
    tracer.getCurrentSpan().addAnnotation("More important.");
    // ...
  }
}

Hello "OpenCensus" stats events

Here's an example on

defining TagKey, Measure and View,
registering a view,
putting TagKey and TagValue into a scoped TagContext,
recording stats against current TagContext,
getting ViewData.

For the complete example, see here.

public final class QuickStart {
  private static final Tagger tagger = Tags.getTagger();
  private static final ViewManager viewManager = Stats.getViewManager();
  private static final StatsRecorder statsRecorder = Stats.getStatsRecorder();

  // frontendKey allows us to break down the recorded data
  private static final TagKey FRONTEND_KEY = TagKey.create("myorg_keys_frontend");

  // videoSize will measure the size of processed videos.
  private static final MeasureLong VIDEO_SIZE = MeasureLong.create(
      "my.org/measure/video_size", "size of processed videos", "By");

  // Create view to see the processed video size distribution broken down by frontend.
  // The view has bucket boundaries (0, 256, 65536) that will group measure values into
  // histogram buckets.
  private static final View.Name VIDEO_SIZE_VIEW_NAME = View.Name.create("my.org/views/video_size");
  private static final View VIDEO_SIZE_VIEW = View.create(
      VIDEO_SIZE_VIEW_NAME,
      "processed video size over time",
      VIDEO_SIZE,
      Aggregation.Distribution.create(BucketBoundaries.create(Arrays.asList(0.0, 256.0, 65536.0))),
      Collections.singletonList(FRONTEND_KEY),
      Cumulative.create());

  private static void initialize() {
    // ...
    viewManager.registerView(VIDEO_SIZE_VIEW);
  }

  private static void processVideo() {
    try (Scope scopedTags =
           tagger
             .currentBuilder()
             .put(FRONTEND_KEY, TagValue.create("mobile-ios9.3.5"))
             .buildScoped()) {
      // Processing video.
      // ...

      // Record the processed video size.
      statsRecorder.newMeasureMap().put(VIDEO_SIZE, 25648).record();
    }
  }

  private static void printStats() {
    ViewData viewData = viewManager.getView(VIDEO_SIZE_VIEW_NAME);
    System.out.println(
      String.format("Recorded stats for %s:\n %s", VIDEO_SIZE_VIEW_NAME.asString(), viewData));
  }
}

Quickstart for Applications

Besides recording tracing/stats events the application also need to link the implementation, setup exporters, and debugging Z-Pages.

Add the dependencies to your project

For Maven add to your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-api</artifactId>
    <version>0.13.2</version>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-impl</artifactId>
    <version>0.13.2</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

compile 'io.opencensus:opencensus-api:0.13.2'
runtime 'io.opencensus:opencensus-impl:0.13.2'

How to setup exporters?

Trace exporters

Stats exporters

How to setup debugging Z-Pages?

If the application owner wants to export in-process tracing and stats data via HTML debugging pages see this link.