Merge remote-tracking branch 'upstream/main' into issue1677

.github/workflows/markdown.yml

@@ -0,0 +1,50 @@
+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}}
+
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          base-branch: 'main'
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'
+          config-file: '.markdown-link.json'
+          check-modified-files-only: 'yes'
+          folder-path: ''

.markdown-link.json

@@ -0,0 +1,16 @@
+{
+    "ignorePatterns": [
+        {
+            "pattern": "^http(s)?://localhost"
+        }
+    ],
+    "replacementPatterns": [
+        {
+            "pattern": "^/registry",
+            "replacement": "https://opentelemetry.io/registry"
+        }
+    ],
+    "retryOn429": true,
+    "retryCount": 5,
+    "fallbackRetryDelay": "30s"
+}

.markdownlint.yaml

@@ -14,6 +14,9 @@ MD013: false
 MD024:
   siblings_only: true
 
+#single-title
+MD025: false
+
 # ol-prefix
 MD029:
   style: ordered

CHANGELOG.md

@@ -10,17 +10,57 @@ 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 |
+- The `Status` type was added to the `go.opentelemetry.io/otel/sdk/trace` package to represent the status of a span. (#1874)
+- The `SpanStub` type and its associated functions were added to the `go.opentelemetry.io/otel/sdk/trace/tracetest` package.
+  This type can be used as a testing replacement for the `SpanSnapshot` that was removed from the `go.opentelemetry.io/otel/sdk/trace` package. (#1873)
+
 ### 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)
+- `Set.Encoded(Encoder)` no longer caches the result of an encoding. (#1855)
+- Renamed `CloudZoneKey` to `CloudAvailabilityZoneKey` in Resource semantic conventions according to spec. (#1871)
+- The `StatusCode` and `StatusMessage` methods of the `ReadOnlySpan` interface and the `Span` produced by the `go.opentelemetry.io/otel/sdk/trace` package have been replaced with a single `Status` method.
+  This method returns the status of a span using the new `Status` type. (#1874)
+- The `ExportSpans` method of the`SpanExporter` interface type was updated to accept `ReadOnlySpan`s instead of the removed `SpanSnapshot`.
+  This brings the export interface into compliance with the specification in that it now accepts an explicitly immutable type instead of just an implied one. (#1873)
+- Unembed `SpanContext` in `Link`. (#1877)
 
 ### Deprecated
 
 ### Removed
 
+- Remove `resource.WithoutBuiltin()`. Use `resource.New()`. (#1810)
+- Unexported types `resource.FromEnv`, `resource.Host`, and `resource.TelemetrySDK`, Use the corresponding `With*()` to use individually. (#1810)
+- Removed the `Tracer` and `IsRecording` method from the `ReadOnlySpan` in the `go.opentelemetry.io/otel/sdk/trace`.
+  The `Tracer` method is not a required to be included in this interface and given the mutable nature of the tracer that is associated with a span, this method is not appropriate.
+  The `IsRecording` method returns if the span is recording or not.
+  A read-only span value does not need to know if updates to it will be recorded or not.
+  By definition, it cannot be updated so there is no point in communicating if an update is recorded. (#1873)
+- Removed the `SpanSnapshot` type from the `go.opentelemetry.io/otel/sdk/trace` package.
+  The use of this type has been replaced with the use of the explicitly immutable `ReadOnlySpan` type.
+  When a concrete representation of a read-only span is needed for testing, the newly added `SpanStub` in the `go.opentelemetry.io/otel/sdk/trace/tracetest` package should be used. (#1873)
+
 ### 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
@@ -65,6 +105,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   - `OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE`
   - `OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE`
 - Adds `otlpgrpc.WithTimeout` option for configuring timeout to the otlp/gRPC exporter. (#1821)
+- Adds `jaeger.WithMaxPacketSize` option for configuring maximum UDP packet size used when connecting to the Jaeger agent. (#1853)
 
 ### Fixed
 
@@ -76,6 +117,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Zipkin Exporter: Ensure mapping between OTel and Zipkin span data complies with the specification. (#1688)
 - Fixed typo for default service name in Jaeger Exporter. (#1797)
 - Fix flaky OTLP for the reconnnection of the client connection. (#1527, #1814)
+- Fix Jaeger exporter dropping of span batches that exceed the UDP packet size limit.
+  Instead, the exporter now splits the batch into smaller sendable batches. (#1828)
 
 ### Changed
 

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    {…}

README.md

@@ -5,7 +5,8 @@
 [![Go Report Card](https://goreportcard.com/badge/go.opentelemetry.io/otel)](https://goreportcard.com/report/go.opentelemetry.io/otel)
 [![Slack](https://img.shields.io/badge/slack-@cncf/otel--go-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C01NPAXACKT)
 
-The Go [OpenTelemetry](https://opentelemetry.io/) implementation.
+OpenTelemetry-Go is the [Go](https://golang.org/) implementation of [OpenTelemetry](https://opentelemetry.io/).
+It provides a set of APIs to directly measure performance and behavior of your software and send this data to observability platforms.
 
 ## Project Status
 
@@ -26,6 +27,17 @@ and
 Project versioning information and stability guarantees can be found in the
 [versioning documentation](./VERSIONING.md).
 
+| Signal | Status |
+| --- | --- |
+| Traces | Stable [release](https://github.com/orgs/open-telemetry/projects/5) is primary focus |
+| Metrics | Development paused [1] |
+| Logs | Frozen [2] |
+
+- [1]: The development of the metrics API and SDK has paused due to limited development resources, prioritization of a stable Traces release, and instability of the official overall design from the OpenTelemetry specification.
+   Pull Requests for metrics related issues are not being accepted currently outside of security vulnerability mitigations.
+- [2]: The Logs signal development is halted for this project while we develop both Traces and Metrics.
+   No Logs Pull Requests are currently being accepted.
+
 ### Compatibility
 
 This project is tested on the following systems.

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.