diff options
| -rw-r--r-- | README.md | 114 | ||||
| -rw-r--r-- | contrib/zpages/README.md | 2 | ||||
| -rw-r--r-- | exporters/trace_logging/README.md | 25 | ||||
| -rw-r--r-- | exporters/trace_stackdriver/README.md | 2 |
4 files changed, 129 insertions, 14 deletions
@@ -1,10 +1,114 @@ -OpenCensus - A stats collection and distributed tracing framework -================================================================= +# OpenCensus - A stats collection and distributed tracing framework [![Build Status][travis-image]][travis-url] [![Build status][appveyor-image]][appveyor-url] [![Maven Central][maven-image]][maven-url] -OpenCensus provides a framework to define and collect stats against metrics and to -break those stats down across user-defined dimensions. The library is in alpha -stage and the API is subject to change. +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](https://gitter.im/census-instrumentation/Lobby) 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`: +```xml +<dependencies> + <dependency> + <groupId>io.opencensus</groupId> + <artifactId>opencensus-api</artifactId> + <version>0.6.0</version> + </dependency> +</dependencies> +``` + +For Gradle add to your dependencies: +```gradle +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. + +```java +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](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/zpages). + +### Add the dependencies to your project + +For Maven add to your `pom.xml`: +```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: +```gradle +compile 'io.opencensus:opencensus-api:0.6.0' +runtime 'io.opencensus:opencensus-impl:0.6.0' +``` + +### How to setup exporters? + +#### Trace exporters +* [Logging](https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace_logging#quickstart) +* [Stackdriver Trace](https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace_stackdriver#quickstart) + +#### 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](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/zpages#quickstart). [travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master [travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java diff --git a/contrib/zpages/README.md b/contrib/zpages/README.md index 00f52341..eec214a9 100644 --- a/contrib/zpages/README.md +++ b/contrib/zpages/README.md @@ -4,7 +4,7 @@ The *OpenCensus Z-Pages for Java* is a collection of HTML pages to display stats and trace data and allows library configuration control. -## Hello "Z-Pages" +## Quickstart ### Add the dependencies to your project diff --git a/exporters/trace_logging/README.md b/exporters/trace_logging/README.md index 5e86553a..3d0d7025 100644 --- a/exporters/trace_logging/README.md +++ b/exporters/trace_logging/README.md @@ -3,23 +3,34 @@ The *OpenCensus Logging trace exporter* is a trace exporter that logs all data to the system log. -## Download +## Quickstart + +### Add the dependencies to your project For Maven add to your `pom.xml`: ```xml -<dependency> - <groupId>io.opencensus</groupId> - <artifactId>opencensus-exporter-trace-logging</artifactId> - <version>0.6.0</version> -</dependency> +<dependencies> + <dependency> + <groupId>io.opencensus</groupId> + <artifactId>opencensus-exporter-trace-logging</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: ```gradle compile 'io.opencensus:opencensus-exporter-trace-logging:0.6.0' +runtime 'io.opencensus:opencensus-impl:0.6.0' ``` -## How to register the exporter? +### Register the exporter ```java public class MyMainClass { diff --git a/exporters/trace_stackdriver/README.md b/exporters/trace_stackdriver/README.md index 4789940e..ad2676ae 100644 --- a/exporters/trace_stackdriver/README.md +++ b/exporters/trace_stackdriver/README.md @@ -33,7 +33,7 @@ Java 7 or above is required for using this exporter. ### Hello "Stackdriver Trace" -#### Add the dependencies to your project. +#### Add the dependencies to your project For Maven add to your `pom.xml`: ```xml |