diff --git a/README.md b/README.md index 595fd7ecc..835e8dde8 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,105 @@ The Go [OpenTelemetry](https://opentelemetry.io/) client. +## Installation + +This repository includes multiple packages. The `api` +package contains core data types, interfaces and no-op implementations that comprise the OpenTelemetry API following +[the +specification](https://github.com/open-telemetry/opentelemetry-specification). +The `sdk` package is the reference implementation of the API. + +Libraries that produce telemetry data should only depend on `api`, +and defer the choice of the SDK to the application developer. Applications may +depend on `sdk` or another package that implements the API. + +To install the API and SDK packages, + +``` +$ go get -u go.opentelemetry.io +``` + +## Quick Start + +```go +package main + +import ( + "context" + "log" + + apitrace "go.opentelemetry.io/api/trace" + "go.opentelemetry.io/exporter/trace/stdout" + sdktrace "go.opentelemetry.io/sdk/trace" +) + +func initTracer() { + sdktrace.Register() + + exporter, err := stdout.NewExporter(stdout.Options{PrettyPrint: true}) + if err != nil { + log.Fatal(err) + } + + ssp := sdktrace.NewSimpleSpanProcessor(exporter) + sdktrace.RegisterSpanProcessor(ssp) + + // For the demonstration, use sdktrace.AlwaysSample sampler to sample all traces. + // In a production application, use sdktrace.ProbabilitySampler with a desired probability. + sdktrace.ApplyConfig(sdktrace.Config{DefaultSampler: sdktrace.AlwaysSample()}) +} + +func main() { + initTracer() + + apitrace.GlobalTracer().WithSpan(context.Background(), "foo", + func(ctx context.Context) error { + apitrace.GlobalTracer().WithSpan(ctx, "bar", + func(ctx context.Context) error { + apitrace.GlobalTracer().WithSpan(ctx, "baz", + func(ctx context.Context) error { + return nil + }, + ) + return nil + }, + ) + return nil + }, + ) +} + +``` + +See the [API +documentation](https://go.opentelemetry.io/) for more +detail, and the +[opentelemetry-example-app](./example/README.md) +for a complete example. + ## Contributing See the [contributing file](CONTRIBUTING.md). -## TODO +## Release Schedule -TODO +OpenTelemetry Go is under active development. Below is the release schedule +for the Go library. The first version of release isn't guaranteed to conform +to a specific version of the specification, and future releases will not +attempt to maintain backwards compatibility with the alpha release. + +| Component | Version | Target Date | +| --------------------------- | ------- | --------------- | +| Tracing API | Alpha | October 4 2019 | +| Tracing SDK | Alpha | October 4 2019 | +| Metrics API | Alpha | October 14 2019 | +| Metrics SDK | Alpha | October 14 2019 | +| Zipkin Trace Exporter | Alpha | Unknown | +| Jaeger Trace Exporter | Alpha | October 4 2019 | +| Prometheus Metrics Exporter | Alpha | October 14 2019 | +| Trace Context Propagation | Alpha | Unknown | +| OpenTracing Bridge | Alpha | October | +| OpenCensus Bridge | Alpha | Unknown | ## Experimental streaming SDK