Upstream

.gitignore

@@ -11,10 +11,6 @@ coverage.*
 gen/
 
 /example/basic/basic
-/example/grpc/client/client
-/example/grpc/server/server
-/example/http/client/client
-/example/http/server/server
 /example/jaeger/jaeger
 /example/namedtracer/namedtracer
 /example/opencensus/opencensus

CHANGELOG.md

@@ -12,6 +12,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Add the `ReadOnlySpan` and `ReadWriteSpan` interfaces to provide better control for accessing span data. (#1360)
 - `NewGRPCDriver` function returns a `ProtocolDriver` that maintains a single gRPC connection to the collector. (#1369)
+- Documentation about the project's versioning policy. (#1388)
 - `NewSplitDriver` for OTLP exporter that allows sending traces and metrics to different endpoints. (#1418)
 
 ### Changed
@@ -23,6 +24,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Remove duplicate checkout from GitHub Actions workflow (#1407)
 - `NewExporter` from `exporters/otlp` now takes a `ProtocolDriver` as a parameter. (#1369)
 - Many OTLP Exporter options became gRPC ProtocolDriver options. (#1369)
+- Unify endpoint API that related to OTel exporter. (#1401)
 - Metric aggregator Count() and histogram Bucket.Counts are consistently `uint64`. (1430)
 
 ### Removed

README.md

@@ -23,6 +23,9 @@ Progress and status specific to this repository is tracked in our local
 and
 [milestones](https://github.com/open-telemetry/opentelemetry-go/milestones).
 
+Project versioning information and stability guarantees can be found in the
+[versioning documentation](./VERSIONING.md).
+
 ## Getting Started
 
 You can find a getting started guide on [opentelemetry.io](https://opentelemetry.io/docs/go/getting-started/).

VERSIONING.md

@@ -0,0 +1,217 @@
+# Versioning
+
+This document describes the versioning policy for this repository. This policy
+is designed so the following goals can be achieved.
+
+**Users are provided a codebase of value that is stable and secure.**
+
+## Policy
+
+* Versioning of this project will be idiomatic of a Go project using [Go
+  modules](https://github.com/golang/go/wiki/Modules).
+  * [Semantic import
+    versioning](https://github.com/golang/go/wiki/Modules#semantic-import-versioning)
+    will be used.
+    * Versions will comply with [semver 2.0](https://semver.org/spec/v2.0.0.html).
+    * If a module is version `v2` or higher, the major version of the module
+      must be included as a `/vN` at the end of the module paths used in
+      `go.mod` files (e.g., `module go.opentelemetry.io/otel/v2`, `require
+      go.opentelemetry.io/otel/v2 v2.0.1`) and in the package import path
+      (e.g., `import "go.opentelemetry.io/otel/v2/trace"`). This includes the
+      paths used in `go get` commands (e.g., `go get
+      go.opentelemetry.io/otel/[email protected]`.  Note there is both a `/v2` and a
+      `@v2.0.1` in that example. One way to think about it is that the module
+      name now includes the `/v2`, so include `/v2` whenever you are using the
+      module name).
+    * If a module is version `v0` or `v1`, do not include the major version in
+      either the module path or the import path.
+  * Modules will be used to encapsulate signals and components.
+    * Experimental modules still under active development will be versioned at
+      `v0` to imply the stability guarantee defined by
+      [semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
+
+      > Major version zero (0.y.z) is for initial development. Anything MAY
+      > change at any time. The public API SHOULD NOT be considered stable.
+
+    * Mature modules for which we guarantee a stable public API will be versioned
+      with a major version greater than `v0`.
+      * The decision to make a module stable will be made on a case-by-case
+        basis by the maintainers of this project.
+    * Experimental modules will start their versioning at `v0.0.0` and will
+      increment their minor version when backwards incompatible changes are
+      released and increment their patch version when backwards compatible
+      changes are released.
+    * All stable modules that use the same major version number will use the
+      same entire version number.
+      * Stable modules may be released with an incremented minor or patch
+        version even though that module has not been changed, but rather so
+        that it will remain at the same version as other stable modules that
+        did undergo change.
+      * When an experimental module becomes stable a new stable module version
+        will be released and will include this now stable module. The new
+        stable module version will be an increment of the minor version number
+        and will be applied to all existing stable modules as well as the newly
+        stable module being released.
+* Versioning of the associated [contrib
+  repository](https://github.com/open-telemetry/opentelemetry-go-contrib) of
+  this project will be idiomatic of a Go project using [Go
+  modules](https://github.com/golang/go/wiki/Modules).
+  * [Semantic import
+    versioning](https://github.com/golang/go/wiki/Modules#semantic-import-versioning)
+    will be used.
+    * Versions will comply with [semver 2.0](https://semver.org/spec/v2.0.0.html).
+    * If a module is version `v2` or higher, the
+      major version of the module must be included as a `/vN` at the end of the
+      module paths used in `go.mod` files (e.g., `module
+      go.opentelemetry.io/contrib/instrumentation/host/v2`, `require
+      go.opentelemetry.io/contrib/instrumentation/host/v2 v2.0.1`) and in the
+      package import path (e.g., `import
+      "go.opentelemetry.io/contrib/instrumentation/host/v2"`). This includes
+      the paths used in `go get` commands (e.g., `go get
+      go.opentelemetry.io/contrib/instrumentation/host/[email protected]`.  Note there
+      is both a `/v2` and a `@v2.0.1` in that example. One way to think about
+      it is that the module name now includes the `/v2`, so include `/v2`
+      whenever you are using the module name).
+    * If a module is version `v0` or `v1`, do not include the major version
+      in either the module path or the import path.
+  * In addition to public APIs, telemetry produced by stable instrumentation
+    will remain stable and backwards compatible. This is to avoid breaking
+    alerts and dashboard.
+  * Modules will be used to encapsulate instrumentation, detectors, exporters,
+    propagators, and any other independent sets of related components.
+    * Experimental modules still under active development will be versioned at
+      `v0` to imply the stability guarantee defined by
+      [semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
+
+      > Major version zero (0.y.z) is for initial development. Anything MAY
+      > change at any time. The public API SHOULD NOT be considered stable.
+
+    * Mature modules for which we guarantee a stable public API and telemetry will
+      be versioned with a major version greater than `v0`.
+    * Experimental modules will start their versioning at `v0.0.0` and will
+      increment their minor version when backwards incompatible changes are
+      released and increment their patch version when backwards compatible
+      changes are released.
+    * Stable contrib modules cannot depend on experimental modules from this
+      project.
+    * All stable contrib modules of the same major version with this project
+      will use the same entire version as this project.
+      * Stable modules may be released with an incremented minor or patch
+        version even though that module's code has not been changed. Instead
+        the only change that will have been included is to have updated that
+        modules dependency on this project's stable APIs.
+      * When an experimental module in contrib becomes stable a new stable
+        module version will be released and will include this now stable
+        module. The new stable module version will be an increment of the minor
+        version number and will be applied to all existing stable contrib
+        modules, this project's modules, and the newly stable module being
+        released.
+  * Contrib modules will be kept up to date with this project's releases.
+    * Due to the dependency contrib modules will implicitly have on this
+      project's modules the release of stable contrib modules to match the
+      released version number will be staggered after this project's release.
+      There is no explicit time guarantee for how long after this projects
+      release the contrib release will be. Effort should be made to keep them
+      as close in time as possible.
+    * No additional stable release in this project can be made until the
+      contrib repository has a matching stable release.
+    * No release can be made in the contrib repository after this project's
+      stable release except for a stable release of the contrib repository.
+* GitHub releases will be made for all releases.
+* Go modules will be made available at Go package mirrors.
+
+## Example Versioning Lifecycle
+
+To better understand the implementation of the above policy the following
+example is provided. This project is simplified to include only the following
+modules and their versions:
+
+* `otel`: `v0.14.0`
+* `otel/trace`: `v0.14.0`
+* `otel/metric`: `v0.14.0`
+* `otel/baggage`: `v0.14.0`
+* `otel/sdk/trace`: `v0.14.0`
+* `otel/sdk/metric`: `v0.14.0`
+
+These modules have been developed to a point where the `otel/trace`,
+`otel/baggage`, and `otel/sdk/trace` modules have reached a point that they
+should be considered for a stable release. The `otel/metric` and
+`otel/sdk/metric` are still under active development and the `otel` module
+depends on both `otel/trace` and `otel/metric`.
+
+The `otel` package is refactored to remove its dependencies on `otel/metric` so
+it can be released as stable as well. With that done the following release
+candidates are made:
+
+* `otel`: `v1.0.0-rc.1`
+* `otel/trace`: `v1.0.0-rc.1`
+* `otel/baggage`: `v1.0.0-rc.1`
+* `otel/sdk/trace`: `v1.0.0-rc.1`
+
+The `otel/metric` and `otel/sdk/metric` modules remain at `v0.14.0`.
+
+A few minor issues are discovered in the `otel/trace` package. These issues are
+resolved with some minor, but backwards incompatible, changes and are released
+as a second release candidate:
+
+* `otel`: `v1.0.0-rc.2`
+* `otel/trace`: `v1.0.0-rc.2`
+* `otel/baggage`: `v1.0.0-rc.2`
+* `otel/sdk/trace`: `v1.0.0-rc.2`
+
+Notice that all module version numbers are incremented to adhere to our
+versioning policy.
+
+After these release candidates have been evaluated to satisfaction, they are
+released as version `v1.0.0`.
+
+* `otel`: `v1.0.0`
+* `otel/trace`: `v1.0.0`
+* `otel/baggage`: `v1.0.0`
+* `otel/sdk/trace`: `v1.0.0`
+
+Since both the `go` utility and the Go module system support [the semantic
+versioning definition of
+precedence](https://semver.org/spec/v2.0.0.html#spec-item-11), this release
+will correctly be interpreted as the successor to the previous release
+candidates.
+
+Active development of this project continues. The `otel/metric` module now has
+backwards incompatible changes to its API that need to be released and the
+`otel/baggage` module has a minor bug fix that needs to be released. The
+following release is made:
+
+* `otel`: `v1.0.1`
+* `otel/trace`: `v1.0.1`
+* `otel/metric`: `v0.15.0`
+* `otel/baggage`: `v1.0.1`
+* `otel/sdk/trace`: `v1.0.1`
+* `otel/sdk/metric`: `v0.15.0`
+
+Notice that, again, all stable module versions are incremented in unison and
+the `otel/sdk/metric` package, which depends on the `otel/metric` package, also
+bumped its version. This bump of the `otel/sdk/metric` package makes sense
+given their coupling, though it is not explicitly required by our versioning
+policy.
+
+As we progress, the `otel/metric` and `otel/sdk/metric` packages have reached a
+point where they should be evaluated for stability. The `otel` module is
+reintegrated with the `otel/metric` package and the following release is made:
+
+* `otel`: `v1.1.0-rc.1`
+* `otel/trace`: `v1.1.0-rc.1`
+* `otel/metric`: `v1.1.0-rc.1`
+* `otel/baggage`: `v1.1.0-rc.1`
+* `otel/sdk/trace`: `v1.1.0-rc.1`
+* `otel/sdk/metric`: `v1.1.0-rc.1`
+
+All the modules are evaluated and determined to a viable stable release. They
+are then released as version `v1.1.0` (the minor version is incremented to
+indicate the addition of new signal).
+
+* `otel`: `v1.1.0`
+* `otel/trace`: `v1.1.0`
+* `otel/metric`: `v1.1.0`
+* `otel/baggage`: `v1.1.0`
+* `otel/sdk/trace`: `v1.1.0`
+* `otel/sdk/metric`: `v1.1.0`

example/otel-collector/main.go

@@ -46,12 +46,12 @@ func initProvider() func() {
 
 	// If the OpenTelemetry Collector is running on a local cluster (minikube or
 	// microk8s), it should be accessible through the NodePort service at the
-	// `localhost:30080` address. Otherwise, replace `localhost` with the
-	// address of your cluster. If you run the app inside k8s, then you can
+	// `localhost:30080` endpoint. Otherwise, replace `localhost` with the
+	// endpoint of your cluster. If you run the app inside k8s, then you can
 	// probably connect directly to the service through dns
 	driver := otlp.NewGRPCDriver(
 		otlp.WithInsecure(),
-		otlp.WithAddress("localhost:30080"),
+		otlp.WithEndpoint("localhost:30080"),
 		otlp.WithGRPCDialOption(grpc.WithBlock()), // useful for testing
 	)
 	exp, err := otlp.NewExporter(ctx, driver)

exporters/otlp/example_test.go

@@ -135,11 +135,11 @@ func Example_withDifferentSignalCollectors() {
 	// Set different endpoints for the metrics and traces collectors
 	metricsDriver := otlp.NewGRPCDriver(
 		otlp.WithInsecure(),
-		otlp.WithAddress("localhost:30080"),
+		otlp.WithEndpoint("localhost:30080"),
 	)
 	tracesDriver := otlp.NewGRPCDriver(
 		otlp.WithInsecure(),
-		otlp.WithAddress("localhost:30082"),
+		otlp.WithEndpoint("localhost:30082"),
 	)
 	splitCfg := otlp.SplitConfig{
 		ForMetrics: metricsDriver,

exporters/otlp/grpcconnection.go

@@ -202,7 +202,7 @@ func (oc *grpcConnection) setConnection(cc *grpc.ClientConn) bool {
 }
 
 func (oc *grpcConnection) dialToCollector(ctx context.Context) (*grpc.ClientConn, error) {
-	addr := oc.c.collectorAddr
+	endpoint := oc.c.collectorEndpoint
 
 	dialOpts := []grpc.DialOption{}
 	if oc.c.grpcServiceConfig != "" {
@@ -223,7 +223,7 @@ func (oc *grpcConnection) dialToCollector(ctx context.Context) (*grpc.ClientConn
 	ctx, cancel := oc.contextWithStop(ctx)
 	defer cancel()
 	ctx = oc.contextWithMetadata(ctx)
-	return grpc.DialContext(ctx, addr, dialOpts...)
+	return grpc.DialContext(ctx, endpoint, dialOpts...)
 }
 
 func (oc *grpcConnection) contextWithMetadata(ctx context.Context) context.Context {

exporters/otlp/grpcdriver.go

@@ -40,7 +40,7 @@ type grpcDriver struct {
 
 func NewGRPCDriver(opts ...GRPCConnectionOption) ProtocolDriver {
 	cfg := grpcConnectionConfig{
-		collectorAddr:     fmt.Sprintf("%s:%d", DefaultCollectorHost, DefaultCollectorPort),
+		collectorEndpoint: fmt.Sprintf("%s:%d", DefaultCollectorHost, DefaultCollectorPort),
 		grpcServiceConfig: DefaultGRPCServiceConfig,
 	}
 	for _, opt := range opts {

exporters/otlp/grpcoptions.go

@@ -62,7 +62,7 @@ const (
 
 type grpcConnectionConfig struct {
 	canDialInsecure    bool
-	collectorAddr      string
+	collectorEndpoint  string
 	compressor         string
 	reconnectionPeriod time.Duration
 	grpcServiceConfig  string
@@ -82,12 +82,12 @@ func WithInsecure() GRPCConnectionOption {
 	}
 }
 
-// WithAddress allows one to set the address that the exporter will
+// WithEndpoint allows one to set the endpoint that the exporter will
 // connect to the collector on. If unset, it will instead try to use
 // connect to DefaultCollectorHost:DefaultCollectorPort.
-func WithAddress(addr string) GRPCConnectionOption {
+func WithEndpoint(endpoint string) GRPCConnectionOption {
 	return func(cfg *grpcConnectionConfig) {
-		cfg.collectorAddr = addr
+		cfg.collectorEndpoint = endpoint
 	}
 }