From 47aef30f7304619ad4c65b07c396a24e91124662 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 29 Oct 2020 09:23:13 -0700 Subject: [PATCH] Update README and documentation to better communicate pre-GA state (#1281) * Update README Move project status to top of project documentation and add explicit warnings that this project may introduce breaking changes. * Add disclaimer to public packages docs * Use explicit warning in README --- README.md | 28 ++++++++++++++++------------ codes/codes.go | 4 ++++ doc.go | 4 ++++ exporters/otlp/doc.go | 4 ++++ exporters/stdout/doc.go | 4 ++++ exporters/trace/jaeger/doc.go | 4 ++++ exporters/trace/zipkin/doc.go | 4 ++++ global/doc.go | 4 ++++ label/doc.go | 4 ++++ oteltest/doc.go | 4 ++++ propagators/doc.go | 4 ++++ sdk/instrumentation/library.go | 4 ++++ sdk/metric/doc.go | 21 +++++++++++++-------- sdk/metric/processor/reducer/doc.go | 16 +++++++++++----- sdk/opentelemetry.go | 4 ++++ sdk/resource/doc.go | 4 ++++ sdk/trace/doc.go | 4 ++++ semconv/doc.go | 4 ++++ unit/doc.go | 4 ++++ 19 files changed, 104 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 14207e94fd8..c448d300dcf 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,22 @@ The Go [OpenTelemetry](https://opentelemetry.io/) implementation. +## Project Status + +**Warning**: this project is currently in a pre-GA phase. Backwards +incompatible changes may be introduced in subsequent minor version releases as +we work to track the evolving OpenTelemetry specification and user feedback. + +Our progress towards a GA release candidate is tracked in [this project +board](https://github.com/orgs/open-telemetry/projects/5). This release +candidate will follow semantic versioning and will be released with a major +version greater than zero. + +Progress and status specific to this repository is tracked in our local +[project boards](https://github.com/open-telemetry/opentelemetry-go/projects) +and +[milestones](https://github.com/open-telemetry/opentelemetry-go/milestones). + ## Getting Started OpenTelemetry's goal is to provide a single set of APIs to capture distributed @@ -45,18 +61,6 @@ and [metric](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/export/metric?tab=importedby) support. -## Project Status - -This project is currently in a pre-GA phase. Our progress towards a GA release -candidate is tracked in [this project -board](https://github.com/orgs/open-telemetry/projects/5). - -Progress and status specific to this repository is tracked in our local -[project boards](https://github.com/open-telemetry/opentelemetry-go/projects) -and [milestones](https://github.com/open-telemetry/opentelemetry-go/milestones) -can be found at the respective links. We try to keep these accurate and should -be the best place to go for answers on project status. - ## Contributing See the [contributing documentation](CONTRIBUTING.md). diff --git a/codes/codes.go b/codes/codes.go index ec863e5345d..7440e79aff0 100644 --- a/codes/codes.go +++ b/codes/codes.go @@ -14,6 +14,10 @@ // Package codes defines the canonical error codes used by OpenTelemetry. // +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. +// // It conforms to [the OpenTelemetry // specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode). package codes // import "go.opentelemetry.io/otel/codes" diff --git a/doc.go b/doc.go index 6f8bb8dff60..9a4e206297c 100644 --- a/doc.go +++ b/doc.go @@ -15,6 +15,10 @@ /* Package otel provides an implementation of the OpenTelemetry API. +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + The provided API is used to instrument code and measure data about that code's performance and operation. The measured data, by default, is not processed or transmitted anywhere. An implementation of the OpenTelemetry SDK, like the diff --git a/exporters/otlp/doc.go b/exporters/otlp/doc.go index e713481e282..d0897bc8cf2 100644 --- a/exporters/otlp/doc.go +++ b/exporters/otlp/doc.go @@ -13,4 +13,8 @@ // limitations under the License. // Package otlp contains an exporter for the OpenTelemetry protocol buffers. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package otlp // import "go.opentelemetry.io/otel/exporters/otlp" diff --git a/exporters/stdout/doc.go b/exporters/stdout/doc.go index 9f577c2e85b..0f6c96c5f57 100644 --- a/exporters/stdout/doc.go +++ b/exporters/stdout/doc.go @@ -14,4 +14,8 @@ // Package stdout contains an OpenTelemetry exporter for both tracing and // metric telemetry to be written to an output destination as JSON. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package stdout // import "go.opentelemetry.io/otel/exporters/stdout" diff --git a/exporters/trace/jaeger/doc.go b/exporters/trace/jaeger/doc.go index 99bbcf5e74c..57bb0dac8eb 100644 --- a/exporters/trace/jaeger/doc.go +++ b/exporters/trace/jaeger/doc.go @@ -13,4 +13,8 @@ // limitations under the License. // Package jaeger contains an OpenTelemetry tracing exporter for Jaeger. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package jaeger // import "go.opentelemetry.io/otel/exporters/trace/jaeger" diff --git a/exporters/trace/zipkin/doc.go b/exporters/trace/zipkin/doc.go index fb6d363d6be..83a7b7631db 100644 --- a/exporters/trace/zipkin/doc.go +++ b/exporters/trace/zipkin/doc.go @@ -13,4 +13,8 @@ // limitations under the License. // Package zipkin contains an OpenTelemetry tracing exporter for Zipkin. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package zipkin // import "go.opentelemetry.io/otel/exporters/trace/zipkin" diff --git a/global/doc.go b/global/doc.go index ccf409fc900..b0c0f248dfc 100644 --- a/global/doc.go +++ b/global/doc.go @@ -13,4 +13,8 @@ // limitations under the License. // Package global provides global providers, propagators and more. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package global // import "go.opentelemetry.io/otel/global" diff --git a/label/doc.go b/label/doc.go index d631d23871e..abdffdb46f5 100644 --- a/label/doc.go +++ b/label/doc.go @@ -13,4 +13,8 @@ // limitations under the License. // Package label provides key and value labels. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package label // import "go.opentelemetry.io/otel/label" diff --git a/oteltest/doc.go b/oteltest/doc.go index 1cdabd4c732..48ed724a581 100644 --- a/oteltest/doc.go +++ b/oteltest/doc.go @@ -15,6 +15,10 @@ /* Package oteltest provides testing utilities for the otel package. +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + API Validation The Harness can be used to validate an implementation of the OpenTelemetry API diff --git a/propagators/doc.go b/propagators/doc.go index a9595634e21..48ff026d60a 100644 --- a/propagators/doc.go +++ b/propagators/doc.go @@ -15,6 +15,10 @@ /* Package propagators contains OpenTelemetry context propagators. +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + OpenTelemetry propagators are used to extract and inject context data from and into messages exchanged by applications. The propagator supported by this package is the W3C Trace Context encoding diff --git a/sdk/instrumentation/library.go b/sdk/instrumentation/library.go index 09e1d2a1936..9534b336851 100644 --- a/sdk/instrumentation/library.go +++ b/sdk/instrumentation/library.go @@ -16,6 +16,10 @@ Package instrumentation provides an instrumentation library structure to be passed to both the OpenTelemetry Tracer and Meter components. +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + For more information see [this](https://github.com/open-telemetry/oteps/blob/master/text/0083-component.md). */ diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index cdf4ac1a694..c6ac21c497a 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -13,14 +13,19 @@ // limitations under the License. /* -Package metric implements the OpenTelemetry metric.MeterImpl -interface. The Accumulator type supports configurable metrics export -behavior through a collection of export interfaces that support -various export strategies, described below. - -The metric.MeterImpl API consists of methods for constructing -synchronous and asynchronous instruments. There are two constructors -per instrument for the two kinds of number (int64, float64). +Package metric implements the OpenTelemetry metric API. + +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + +The Accumulator type supports configurable metrics export behavior through a +collection of export interfaces that support various export strategies, +described below. + +The OpenTelemetry metric API consists of methods for constructing synchronous +and asynchronous instruments. There are two constructors per instrument for +the two kinds of number (int64, float64). Synchronous instruments are managed by a sync.Map containing a *record with the current state for each synchronous instrument. A bound diff --git a/sdk/metric/processor/reducer/doc.go b/sdk/metric/processor/reducer/doc.go index e7e36b196cf..d8028f97d07 100644 --- a/sdk/metric/processor/reducer/doc.go +++ b/sdk/metric/processor/reducer/doc.go @@ -13,11 +13,17 @@ // limitations under the License. /* -Package reducer implements a metrics Processor component that applies -a `label.Filter` to each processed `export.Accumulation` to remove -labels before passing the result to another Processor. This Processor -can be used to reduce inherent dimensionality in the data, as a way to -control the cost of collecting high cardinality metric data. +Package reducer implements a metrics Processor component to reduce labels. + +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + +The metrics Processor component this package implements applies a +`label.Filter` to each processed `export.Accumulation` to remove labels before +passing the result to another Processor. This Processor can be used to reduce +inherent dimensionality in the data, as a way to control the cost of +collecting high cardinality metric data. For example, to compose a push controller with a reducer and a basic metric processor: diff --git a/sdk/opentelemetry.go b/sdk/opentelemetry.go index db70483ed04..cd686bdf969 100644 --- a/sdk/opentelemetry.go +++ b/sdk/opentelemetry.go @@ -13,6 +13,10 @@ // limitations under the License. // Package opentelemetry contains Go support for OpenTelemetry. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package opentelemetry // import "go.opentelemetry.io/otel/sdk" // Version is the current release version of OpenTelemetry in use. diff --git a/sdk/resource/doc.go b/sdk/resource/doc.go index e35839b75de..d9eccd35405 100644 --- a/sdk/resource/doc.go +++ b/sdk/resource/doc.go @@ -14,6 +14,10 @@ // Package resource provides detecting and representing resources. // +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. +// // The fundamental struct is a Resource which holds identifying information // about the entities for which telemetry is exported. // diff --git a/sdk/trace/doc.go b/sdk/trace/doc.go index 0285e99be07..fd6ead86457 100644 --- a/sdk/trace/doc.go +++ b/sdk/trace/doc.go @@ -15,6 +15,10 @@ /* Package trace contains support for OpenTelemetry distributed tracing. +This package is currently in a pre-GA phase. Backwards incompatible changes +may be introduced in subsequent minor version releases as we work to track the +evolving OpenTelemetry specification and user feedback. + The following assumes a basic familiarity with OpenTelemetry concepts. See https://opentelemetry.io. */ diff --git a/semconv/doc.go b/semconv/doc.go index ec562543a8e..9a729fdecb1 100644 --- a/semconv/doc.go +++ b/semconv/doc.go @@ -14,6 +14,10 @@ // Package semconv implements OpenTelemetry semantic conventions. // +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. +// // OpenTelemetry semantic conventions are agreed standardized naming // patterns for OpenTelemetry things. This package aims to be the // centralized place to interact with these conventions. diff --git a/unit/doc.go b/unit/doc.go index 310a7b277b8..0d77a750cc3 100644 --- a/unit/doc.go +++ b/unit/doc.go @@ -13,4 +13,8 @@ // limitations under the License. // Package unit provides units. +// +// This package is currently in a pre-GA phase. Backwards incompatible changes +// may be introduced in subsequent minor version releases as we work to track +// the evolving OpenTelemetry specification and user feedback. package unit // import "go.opentelemetry.io/otel/unit"