commit	8af5347dab5e0ded1997e67633efa7f8328176fa	[log] [tgz]
author	Bogdan Drutu <bdrutu@google.com>	Fri Sep 01 14:15:54 2017 -0700
committer	GitHub <noreply@github.com>	Fri Sep 01 14:15:54 2017 -0700
tree	91d8f257e99a1ca06a7ec890f14bf0e81d304639
parent	0890ab4987c6190f2ab90c1d7357da0a3f6da8eb [diff]

tree: 91d8f257e99a1ca06a7ec890f14bf0e81d304639

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.

Instrumentation Quickstart

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

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.6.0</version>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

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

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 {
  public static void doWork() {
    // Create a child Span of the current Span.
    try (Scope ss = tracer.spanBuilder("MyChildWorkSpan").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

TODO

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.6.0</version>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-impl</artifactId>
    <version>0.6.0</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

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

How to setup exporters?

Trace exporters

Stats exporters

TODO

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.