Merge branch 'main' into resource-new

.github/workflows/markdown.yml

@@ -0,0 +1,33 @@
+name: markdown
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  changedfiles:
+    name: changed files
+    runs-on: ubuntu-latest
+    outputs:
+      md: ${{ steps.changes.outputs.md }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Get changed files
+        id: changes
+        run: |
+          echo "::set-output name=md::$(git diff --name-only --diff-filter=ACMRTUXB origin/${{ github.event.pull_request.base.ref }} ${{ github.event.pull_request.head.sha }} | grep .md$ | xargs)"
+  lint:
+    name: lint markdown files
+    runs-on: ubuntu-latest
+    needs: changedfiles
+    if: ${{needs.changedfiles.outputs.md}}
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v2
+    - name: Run linter
+      uses: docker://avtodev/markdown-lint:v1
+      with:
+        args: ${{needs.changedfiles.outputs.md}}

CHANGELOG.md

@@ -10,11 +10,25 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- Adds `otlpgrpc.WithRetry`option for configuring the retry policy for transient errors on the otlp/gRPC exporter. (#1832)
+  - The following status codes are defined as transient errors:
+      | gRPC Status Code | Description |
+      | ---------------- | ----------- |
+      | 1  | Cancelled |
+      | 4  | Deadline Exceeded |
+      | 8  | Resource Exhausted |
+      | 10 | Aborted |
+      | 10 | Out of Range |
+      | 14 | Unavailable |
+      | 15 | Data Loss |
+
 ### Changed
 
 - Make `NewSplitDriver` from `go.opentelemetry.io/otel/exporters/otlp` take variadic arguments instead of a `SplitConfig` item.
-  `NewSplitDriver` now automically implements an internal `noopDriver` for `SplitConfig` fields that are not initialized. (#1798)
+  `NewSplitDriver` now automatically implements an internal `noopDriver` for `SplitConfig` fields that are not initialized. (#1798)
 - `resource.New()` now creates a Resource without builtin detectors. Previous behavior is now achieved by using `WithBuiltinDetectors` Option. (#1810)
+- Move the `Event` type from the `go.opentelemetry.io/otel` package to the `go.opentelemetry.io/otel/sdk/trace` package. (#1846)
+- BatchSpanProcessor now report export failures when calling `ForceFlush()` method. (#1860)
 
 ### Deprecated
 
@@ -25,6 +39,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Fixed
 
+- Only report errors from the `"go.opentelemetry.io/otel/sdk/resource".Environment` function when they are not `nil`. (#1850, #1851)
+- The `Shutdown` method of the simple `SpanProcessor` in the `go.opentelemetry.io/otel/sdk/trace` package now honors the context deadline or cancellation. (#1616, #1856)
+- BatchSpanProcessor now drops span batches that failed to be exported. (#1860)
+
 ### Security
 
 ## [0.20.0] - 2021-04-23

CONTRIBUTING.md

@@ -15,7 +15,7 @@ join the meeting or get in touch on
 
 You can view and edit the source code by cloning this repository:
 
-```bash
+```sh
 git clone https://github.com/open-telemetry/opentelemetry-go.git
 ```
 
@@ -166,25 +166,25 @@ to the reasons why.
 
 ### Configuration
 
-When creating an instantiation function for a complex `struct` it is useful
-to allow variable number of options to be applied. However, the strong type
-system of Go restricts the function design options. There are a few ways to
-solve this problem, but we have landed on the following design.
+When creating an instantiation function for a complex `type T struct`, it is
+useful to allow variable number of options to be applied. However, the strong
+type system of Go restricts the function design options. There are a few ways
+to solve this problem, but we have landed on the following design.
 
 #### `config`
 
 Configuration should be held in a `struct` named `config`, or prefixed with
 specific type name this Configuration applies to if there are multiple
-`config` in the package. This `struct` must contain configuration options.
+`config` in the package. This type must contain configuration options.
 
 ```go
 // config contains configuration options for a thing.
 type config struct {
-    // options ...
+	// options ...
 }
 ```
 
-In general the `config` `struct` will not need to be used externally to the
+In general the `config` type will not need to be used externally to the
 package and should be unexported. If, however, it is expected that the user
 will likely want to build custom options for the configuration, the `config`
 should be exported. Please, include in the documentation for the `config`
@@ -200,13 +200,13 @@ all options to create a configured `config`.
 ```go
 // newConfig returns an appropriately configured config.
 func newConfig([]Option) config {
-    // Set default values for config.
-    config := config{/* […] */}
-    for _, option := range options {
-        option.Apply(&config)
-    }
-    // Preform any validation here.
-    return config
+	// Set default values for config.
+	config := config{/* […] */}
+	for _, option := range options {
+		option.apply(&config)
+	}
+	// Preform any validation here.
+	return config
 }
 ```
 
@@ -224,10 +224,14 @@ To set the value of the options a `config` contains, a corresponding
 
 ```go
 type Option interface {
-  Apply(*config)
+	apply(*config)
 }
 ```
 
+Having `apply` unexported makes sure that it will not be used externally.
+Moreover, the interface becomes sealed so the user cannot easily implement
+the interface on its own.
+
 The name of the interface should be prefixed in the same way the
 corresponding `config` is (if at all).
 
@@ -250,53 +254,53 @@ func With*(…) Option { … }
 ```go
 type defaultFalseOption bool
 
-func (o defaultFalseOption) Apply(c *config) {
-    c.Bool = bool(o)
+func (o defaultFalseOption) apply(c *config) {
+	c.Bool = bool(o)
 }
 
-// WithOption sets a T* to have an option included.
+// WithOption sets a T to have an option included.
 func WithOption() Option {
-    return defaultFalseOption(true)
+	return defaultFalseOption(true)
 }
 ```
 
 ```go
 type defaultTrueOption bool
 
-func (o defaultTrueOption) Apply(c *config) {
-    c.Bool = bool(o)
+func (o defaultTrueOption) apply(c *config) {
+	c.Bool = bool(o)
 }
 
-// WithoutOption sets a T* to have Bool option excluded.
+// WithoutOption sets a T to have Bool option excluded.
 func WithoutOption() Option {
-    return defaultTrueOption(false)
+	return defaultTrueOption(false)
 }
-````
+```
 
 ##### Declared Type Options
 
 ```go
 type myTypeOption struct {
-    MyType MyType
+	MyType MyType
 }
 
-func (o myTypeOption) Apply(c *config) {
-    c.MyType = o.MyType
+func (o myTypeOption) apply(c *config) {
+	c.MyType = o.MyType
 }
 
-// WithMyType sets T* to have include MyType.
+// WithMyType sets T to have include MyType.
 func WithMyType(t MyType) Option {
-    return myTypeOption{t}
+	return myTypeOption{t}
 }
 ```
 
 #### Instantiation
 
-Using this configuration pattern to configure instantiation with a `New*`
+Using this configuration pattern to configure instantiation with a `NewT`
 function.
 
 ```go
-func NewT*(options ...Option) T* {…}
+func NewT(options ...Option) T {…}
 ```
 
 Any required parameters can be declared before the variadic `options`.
@@ -320,12 +324,12 @@ type config struct {
 
 // DogOption apply Dog specific options.
 type DogOption interface {
-	ApplyDog(*config)
+	applyDog(*config)
 }
 
 // BirdOption apply Bird specific options.
 type BirdOption interface {
-	ApplyBird(*config)
+	applyBird(*config)
 }
 
 // Option apply options for all animals.
@@ -335,16 +339,16 @@ type Option interface {
 }
 
 type weightOption float64
-func (o weightOption) ApplyDog(c *config)  { c.Weight = float64(o) }
-func (o weightOption) ApplyBird(c *config) { c.Weight = float64(o) }
+func (o weightOption) applyDog(c *config)  { c.Weight = float64(o) }
+func (o weightOption) applyBird(c *config) { c.Weight = float64(o) }
 func WithWeight(w float64) Option          { return weightOption(w) }
 
 type furColorOption string
-func (o furColorOption) ApplyDog(c *config) { c.Color = string(o) }
+func (o furColorOption) applyDog(c *config) { c.Color = string(o) }
 func WithFurColor(c string) DogOption       { return furColorOption(c) }
 
 type maxAltitudeOption float64
-func (o maxAltitudeOption) ApplyBird(c *config) { c.MaxAltitude = float64(o) }
+func (o maxAltitudeOption) applyBird(c *config) { c.MaxAltitude = float64(o) }
 func WithMaxAltitude(a float64) BirdOption      { return maxAltitudeOption(a) }
 
 func NewDog(name string, o ...DogOption) Dog    {…}

RELEASING.md

@@ -75,6 +75,13 @@ After releasing verify that examples build outside of the repository.
 The script copies examples into a different directory removes any `replace` declarations in `go.mod` and builds them.
 This ensures they build with the published release, not the local copy.
 
-## Contrib Repository
+## Post-Release
+
+### Contrib Repository
 
 Once verified be sure to [make a release for the `contrib` repository](https://github.com/open-telemetry/opentelemetry-go-contrib/blob/main/RELEASING.md) that uses this release.
+
+### Website Documentation
+
+Update [the documentation](./website_docs) for [the OpenTelemetry website](https://opentelemetry.io/docs/go/).
+Importantly, bump any package versions referenced to be the latest one you just released and ensure all code examples still compile and are accurate.

bridge/opencensus/README.md

@@ -10,7 +10,7 @@ In a perfect world, one would simply migrate their entire go application --inclu
 
 However, if you create the following spans in a go application:
 
-```golang
+```go
 ctx, ocSpan := opencensus.StartSpan(context.Background(), "OuterSpan")
 defer ocSpan.End()
 ctx, otSpan := opentelemetryTracer.Start(ctx, "MiddleSpan")
@@ -54,11 +54,11 @@ Starting from an application using entirely OpenCensus APIs:
 4. Remove OpenCensus exporters and configuration
 
 To override OpenCensus' DefaultTracer with the bridge:
-```golang
+```go
 import (
-    octrace "go.opencensus.io/trace"
-    "go.opentelemetry.io/otel/bridge/opencensus"
-    "go.opentelemetry.io/otel"
+	octrace "go.opencensus.io/trace"
+	"go.opentelemetry.io/otel/bridge/opencensus"
+	"go.opentelemetry.io/otel"
 )
 
 tracer := otel.GetTracerProvider().Tracer("bridge")
@@ -102,12 +102,12 @@ Starting from an application using entirely OpenCensus APIs:
 4. Remove OpenCensus Exporters and configuration.
 
 For example, to swap out the OpenCensus logging exporter for the OpenTelemetry stdout exporter:
-```golang
+```go
 import (
 	"go.opencensus.io/metric/metricexport"
-    "go.opentelemetry.io/otel/bridge/opencensus"
+	"go.opentelemetry.io/otel/bridge/opencensus"
 	"go.opentelemetry.io/otel/exporters/stdout" 
-    "go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel"
 )
 // With OpenCensus, you could have previously configured the logging exporter like this:
 //       import logexporter "go.opencensus.io/examples/exporter"

example/otel-collector/go.sum

@@ -4,6 +4,8 @@ github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03
 github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY=
 github.com/benbjohnson/clock v1.0.3 h1:vkLuvpK4fmtSCuo60+yC63p7y0BmQ8gm5ZXGuBCJyXg=
 github.com/benbjohnson/clock v1.0.3/go.mod h1:bGMdMPoPVvcYyt1gHDf4J2KE153Yf9BuiUKYMaxlTDM=
+github.com/cenkalti/backoff/v4 v4.1.0 h1:c8LkOFQTzuO0WBM/ae5HdGQuZPfPxp7lqBRwQRm4fSc=
+github.com/cenkalti/backoff/v4 v4.1.0/go.mod h1:scbssz8iZGpm3xbr14ovlUdkxfGXNInqkPWOWmG2CLw=
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=

example/prom-collector/go.sum

@@ -29,7 +29,10 @@ github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
 github.com/bgentry/speakeasy v0.1.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs=
 github.com/casbin/casbin/v2 v2.1.2/go.mod h1:YcPU1XXisHhLzuxH9coDNf2FbKpjGlbCg3n9yuLkIJQ=
+github.com/cenkalti/backoff v2.2.1+incompatible h1:tNowT99t7UNflLxfYYSlKYsBpXdEet03Pg2g16Swow4=
 github.com/cenkalti/backoff v2.2.1+incompatible/go.mod h1:90ReRw6GdpyfrHakVjL/QHaoyV4aDUVVkXQJJJ3NXXM=
+github.com/cenkalti/backoff/v4 v4.1.0 h1:c8LkOFQTzuO0WBM/ae5HdGQuZPfPxp7lqBRwQRm4fSc=
+github.com/cenkalti/backoff/v4 v4.1.0/go.mod h1:scbssz8iZGpm3xbr14ovlUdkxfGXNInqkPWOWmG2CLw=
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/cespare/xxhash/v2 v2.1.1 h1:6MnRN8NT7+YBpUIWxHtefFZOKTAPgGjpQSxqLNn0+qY=
 github.com/cespare/xxhash/v2 v2.1.1/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=

exporters/otlp/README.md

@@ -4,28 +4,12 @@
 
 This exporter exports OpenTelemetry spans and metrics to the OpenTelemetry Collector.
 
-
 ## Installation and Setup
 
 The exporter can be installed using standard `go` functionality.
 
 ```bash
-$ go get -u go.opentelemetry.io/otel/exporters/otlp
+go get -u go.opentelemetry.io/otel/exporters/otlp
 ```
 
 A new exporter can be created using the `NewExporter` function.
-
-## Retries
-
-The exporter will not, by default, retry failed requests to the collector.
-However, it is configured in a way that it can be easily enabled.
-
-To enable retries, the `GRPC_GO_RETRY` environment variable needs to be set to `on`. For example,
-
-```
-GRPC_GO_RETRY=on go run .
-```
-
-The [default service config](https://github.com/grpc/proposal/blob/master/A6-client-retries.md) used by default is defined to retry failed requests with exponential backoff (`0.3seconds * (2)^retry`) with [a max of `5` retries](https://github.com/open-telemetry/oteps/blob/be2a3fcbaa417ebbf5845cd485d34fdf0ab4a2a4/text/0035-opentelemetry-protocol.md#export-response)).
-
-These retries are only attempted for reponses that are [deemed "retry-able" by the collector](https://github.com/grpc/proposal/blob/master/A6-client-retries.md#validation-of-retrypolicy).

exporters/otlp/go.mod

@@ -8,6 +8,7 @@ replace (
 )
 
 require (
+	github.com/cenkalti/backoff/v4 v4.1.0
 	github.com/google/go-cmp v0.5.5
 	github.com/stretchr/testify v1.7.0
 	go.opentelemetry.io/otel v0.20.0
@@ -17,6 +18,7 @@ require (
 	go.opentelemetry.io/otel/sdk/metric v0.20.0
 	go.opentelemetry.io/otel/trace v0.20.0
 	go.opentelemetry.io/proto/otlp v0.7.0
+	google.golang.org/genproto v0.0.0-20200526211855-cb27e3aa2013
 	google.golang.org/grpc v1.37.0
 	google.golang.org/protobuf v1.26.0
 )

exporters/otlp/go.sum

@@ -4,6 +4,8 @@ github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03
 github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY=
 github.com/benbjohnson/clock v1.0.3 h1:vkLuvpK4fmtSCuo60+yC63p7y0BmQ8gm5ZXGuBCJyXg=
 github.com/benbjohnson/clock v1.0.3/go.mod h1:bGMdMPoPVvcYyt1gHDf4J2KE153Yf9BuiUKYMaxlTDM=
+github.com/cenkalti/backoff/v4 v4.1.0 h1:c8LkOFQTzuO0WBM/ae5HdGQuZPfPxp7lqBRwQRm4fSc=
+github.com/cenkalti/backoff/v4 v4.1.0/go.mod h1:scbssz8iZGpm3xbr14ovlUdkxfGXNInqkPWOWmG2CLw=
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=