Pre-release 1.0.0-RC1

[Aneurysm9]

1.0.0-RC1 / 0.21.0

With this release we are introducing a split in module versions. The tracing API and SDK are entering the v1.0.0 Release Candidate phase with v1.0.0-RC1 while the experimental metrics API and SDK continue with v0.x releases at v0.21.0. Modules at major version 1 or greater will not depend on modules with major version 0.

Added

• Adds otlpgrpc.WithRetryoption for configuring the retry policy for transient errors on the otlp/gRPC exporter. (Implement retry policy for 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

• Added Status type to the go.opentelemetry.io/otel/sdk/trace package to represent the status of a span. (Add Status type to SDK #1874)
• Added SpanStub type and its associated functions 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. (Redefine ExportSpans of SpanExporter with ReadOnlySpan #1873)
• Adds support for scheme in OTEL_EXPORTER_OTLP_ENDPOINT according to the spec. (Add support for scheme in OTEL_EXPORTER_OTLP_ENDPOINT #1886)
• Adds trace.WithSchemaURL option for configuring the tracer with a Schema URL. (Add schema URL support to Tracer #1889)
• Added an example of using OpenTelemetry Go as a trace context forwarder. (Add Passthrough example #1912)
• ParseTraceState is added to the go.opentelemetry.io/otel/trace package.
  It can be used to decode a TraceState from a tracestate header string value. (#1937)
• Added Len method to the TraceState type in the go.opentelemetry.io/otel/trace package.
  This method returns the number of list-members the TraceState holds. (#1937)
• Creates package go.opentelemetry.io/otel/exporters/otlp/otlptrace that defines a trace exporter that uses a otlptrace.Client to send data.
  Creates package go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc implementing a gRPC otlptrace.Client and offers convenience functions, NewExportPipeline and InstallNewPipeline, to setup and install a otlptrace.Exporter in tracing .(OTLP trace gRPC exporter #1922)
• Added Baggage, Member, and Property types to the go.opentelemetry.io/otel/baggage package along with their related functions. (Add baggage implementation based on the W3C and OpenTelemetry specification #1967)
• Added ContextWithBaggage, ContextWithoutBaggage, and FromContext functions to the go.opentelemetry.io/otel/baggage package.
  These functions replace the Set, Value, ContextWithValue, ContextWithoutValue, and ContextWithEmpty functions from that package and directly work with the new Baggage type. (Add baggage implementation based on the W3C and OpenTelemetry specification #1967)
• The OTEL_SERVICE_NAME environment variable is the preferred source for service.name, used by the environment resource detector if a service name is present both there and in OTEL_RESOURCE_ATTRIBUTES. (sdk/resource: honor OTEL_SERVICE_NAME in fromEnv resource detector #1969)
• Creates package go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp implementing an HTTP otlptrace.Client and offers convenience functions, NewExportPipeline and InstallNewPipeline, to setup and install a otlptrace.Exporter in tracing. (add otlp trace http exporter #1963)
• Changes go.opentelemetry.io/otel/sdk/resource.NewWithAttributes to require a schema URL. The old function is still available as resource.NewSchemaless. This is a breaking change. (Add Schema URL support to Resource #1938)
• Several builtin resource detectors now correctly populate the schema URL. (Add Schema URL support to Resource #1938)
• Creates package go.opentelemetry.io/otel/exporters/otlp/otlpmetric that defines a metrics exporter that uses a otlpmetric.Client to send data.
• Creates package go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc implementing a gRPC otlpmetric.Client and offers convenience functions, New and NewUnstarted, to create an otlpmetric.Exporter.(OTLP metrics gRPC exporter #1991)
• Added go.opentelemetry.io/otel/exporters/stdout/stdouttrace exporter. (Split stdout exporter into stdouttrace and stdoutmetric #2005)
• Added go.opentelemetry.io/otel/exporters/stdout/stdoutmetric exporter. (Split stdout exporter into stdouttrace and stdoutmetric #2005)
• Added a TracerProvider() method to the "go.opentelemetry.io/otel/trace".Span interface. This can be used to obtain a TracerProvider from a given span that utilizes the same trace processing pipeline. (Add span.TracerProvider() #2009)

Changed

• Make NewSplitDriver from go.opentelemetry.io/otel/exporters/otlp take variadic arguments instead of a SplitConfig item.
  NewSplitDriver now automatically implements an internal noopDriver for SplitConfig fields that are not initialized. (Change NewSplitDriver paramater and initialization #1798)
• resource.New() now creates a Resource without builtin detectors. Previous behavior is now achieved by using WithBuiltinDetectors Option. (Removed different types of Detectors for Resources. #1810)
• Move the Event type from the go.opentelemetry.io/otel package to the go.opentelemetry.io/otel/sdk/trace package. (Move the Event type from the API to the SDK #1846)
• CI builds validate against last two versions of Go, dropping 1.14 and adding 1.16. (CI builds validate against last two versions of Go, dropping 1.14 and adding 1.16 #1865)
• BatchSpanProcessor now report export failures when calling ForceFlush() method. (drop failed to exporter batches and return error when forcing flush a span processor #1860)
• Set.Encoded(Encoder) no longer caches the result of an encoding. (remove Set.Encoded(Encoder) enconding cache #1855)
• Renamed CloudZoneKey to CloudAvailabilityZoneKey in Resource semantic conventions according to spec. (Update resource.go #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. (Add Status type to SDK #1874)
• Updated ExportSpans method of theSpanExporter interface type to accept ReadOnlySpans 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. (Redefine ExportSpans of SpanExporter with ReadOnlySpan #1873)
• Unembed SpanContext in Link. (Unembed SpanContext #1877)
• Generate Semantic conventions from the specification YAML. (Semantic Convention generation tooling #1891)
• Spans created by the global Tracer obtained from go.opentelemetry.io/otel, prior to a functioning TracerProvider being set, now propagate the span context from their parent if one exists. (Implement global default non-recording span #1901)
• The "go.opentelemetry.io/otel".Tracer function now accepts tracer options. (Add tracer option argument to global Tracer function #1902)
• Move the go.opentelemetry.io/otel/unit package to go.opentelemetry.io/otel/metric/unit. (Move the unit package to the metric module #1903)
• Changed go.opentelemetry.io/otel/trace.TracerConfig to conform to the Contributing guidelines (Update API configs. #1921)
• Changed go.opentelemetry.io/otel/trace.SpanConfig to conform to the Contributing guidelines. (Update API configs. #1921)
• Changed span.End() now only accepts Options that are allowed at End(). (Update API configs. #1921)
• Changed go.opentelemetry.io/otel/metric.InstrumentConfig to conform to the Contributing guidelines. (Update API configs. #1921)
• Changed go.opentelemetry.io/otel/metric.MeterConfig to conform to the Contributing guidelines. (Update API configs. #1921)
• Refactored option types according to the contribution style guide. (Refactor configs #1882)
• Move the go.opentelemetry.io/otel/trace.TraceStateFromKeyValues function to the go.opentelemetry.io/otel/oteltest package.
  This function is preserved for testing purposes where it may be useful to create a TraceState from attribute.KeyValues, but it is not intended for production use.
  The new ParseTraceState function should be used to create a TraceState. (Refactor Tracestate #1931)
• Updated MarshalJSON method of the go.opentelemetry.io/otel/trace.TraceState type to marshal the type into the string representation of the TraceState. (Refactor Tracestate #1931)
• The TraceState.Delete method from the go.opentelemetry.io/otel/trace package no longer returns an error in addition to a TraceState. (Refactor Tracestate #1931)
• Updated Get method of the TraceState type from the go.opentelemetry.io/otel/trace package to accept a string instead of an attribute.Key type. (Refactor Tracestate #1931)
• Updated Insert method of the TraceState type from the go.opentelemetry.io/otel/trace package to accept a pair of strings instead of an attribute.KeyValue type. (Refactor Tracestate #1931)
• Updated Delete method of the TraceState type from the go.opentelemetry.io/otel/trace package to accept a string instead of an attribute.Key type. (Refactor Tracestate #1931)
• Renamed NewExporter to New in the go.opentelemetry.io/otel/exporters/stdout package. (Refactor exporter creation functions #1985)
• Renamed NewExporter to New in the go.opentelemetry.io/otel/exporters/metric/prometheus package. (Refactor exporter creation functions #1985)
• Renamed NewExporter to New in the go.opentelemetry.io/otel/exporters/trace/jaeger package. (Refactor exporter creation functions #1985)
• Renamed NewExporter to New in the go.opentelemetry.io/otel/exporters/trace/zipkin package. (Refactor exporter creation functions #1985)
• Renamed NewExporter to New in the go.opentelemetry.io/otel/exporters/otlp package. (Refactor exporter creation functions #1985)
• Renamed NewUnstartedExporter to NewUnstarted in the go.opentelemetry.io/otel/exporters/otlp package. (Refactor exporter creation functions #1985)
• The go.opentelemetry.io/otel/semconv package has been moved to go.opentelemetry.io/otel/semconv/v1.4.0 to allow for multiple telemetry schema versions to be used concurrently. (Update semantic conventions to v1.4.0, move to versioned package #1987)
• Metrics test helpers in go.opentelemetry.io/otel/oteltest have been moved to go.opentelemetry.io/otel/metric/metrictest. (Remove dependency on metrics packages #1988)

Deprecated

• The go.opentelemetry.io/otel/exporters/metric/prometheus is deprecated, use go.opentelemetry.io/otel/exporters/prometheus instead. (Deprecate the exporters in the "trace" and "metric" sub-directories #1993)
• The go.opentelemetry.io/otel/exporters/trace/jaeger is deprecated, use go.opentelemetry.io/otel/exporters/jaeger instead. (Deprecate the exporters in the "trace" and "metric" sub-directories #1993)
• The go.opentelemetry.io/otel/exporters/trace/zipkin is deprecated, use go.opentelemetry.io/otel/exporters/zipkin instead. (Deprecate the exporters in the "trace" and "metric" sub-directories #1993)

Removed

• Removed resource.WithoutBuiltin(). Use resource.New(). (Removed different types of Detectors for Resources. #1810)
• Unexported types resource.FromEnv, resource.Host, and resource.TelemetrySDK, Use the corresponding With*() to use individually. (Removed different types of Detectors for Resources. #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. (Redefine ExportSpans of SpanExporter with ReadOnlySpan #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. (Redefine ExportSpans of SpanExporter with ReadOnlySpan #1873)
• Removed the Tracer method from the Span interface in the go.opentelemetry.io/otel/trace package.
  Using the same tracer that created a span introduces the error where an instrumentation library's Tracer is used by other code instead of their own.
  The "go.opentelemetry.io/otel".Tracer function or a TracerProvider should be used to acquire a library specific Tracer instead. (Remove the Tracer method from the Span API #1900)
  • The TracerProvider() method on the Span interface may also be used to obtain a TracerProvider using the same trace processing pipeline. (Add span.TracerProvider() #2009)
• The http.url attribute generated by HTTPClientAttributesFromHTTPRequest will no longer include username or password information. (Do not include authentication information in the http.url attribute #1919)
• Removed IsEmpty method of the TraceState type in the go.opentelemetry.io/otel/trace package in favor of using the added TraceState.Len method. (Refactor Tracestate #1931)
• Removed Set, Value, ContextWithValue, ContextWithoutValue, and ContextWithEmpty functions in the go.opentelemetry.io/otel/baggage package.
  Handling of baggage is now done using the added Baggage type and related context functions (ContextWithBaggage, ContextWithoutBaggage, and FromContext) in that package. (Add baggage implementation based on the W3C and OpenTelemetry specification #1967)
• The InstallNewPipeline and NewExportPipeline creation functions in all the exporters (prometheus, otlp, stdout, jaeger, and zipkin) have been removed.
  These functions were deemed premature attempts to provide convenience that did not achieve this aim. (Refactor exporter creation functions #1985)
• The go.opentelemetry.io/otel/exporters/otlp exporter has been removed. Use go.opentelemetry.io/otel/exporters/otlp/otlptrace instead. (Remove old OTLP exporter #1990)
• The go.opentelemetry.io/otel/exporters/stdout exporter has been removed. Use go.opentelemetry.io/otel/exporters/stdout/stdouttrace or go.opentelemetry.io/otel/exporters/stdout/stdoutmetric instead. (Split stdout exporter into stdouttrace and stdoutmetric #2005)

Fixed

• Only report errors from the "go.opentelemetry.io/otel/sdk/resource".Environment function when they are not nil. (Wrong error handling in resource.Environment() method #1850, Handle Resource env error when non-nil #1851)
• The Shutdown method of the simple SpanProcessor in the go.opentelemetry.io/otel/sdk/trace package now honors the context deadline or cancellation. (SimpleSpanProcessor.Shutdown needs to be configurable with a timeout that it honors #1616, Honor context deadline or cancellation in SimpleSpanProcessor.Shutdown #1856)
• BatchSpanProcessor now drops span batches that failed to be exported. (drop failed to exporter batches and return error when forcing flush a span processor #1860)
• Use http://localhost:14268/api/traces as default Jaeger collector endpoint instead of http://localhost:14250. (Fix default Jaeger collector endpoint #1898)
• Allow trailing and leading whitespace in the parsing of a tracestate header. (Refactor Tracestate #1931)
• Add logic to determine if the channel is closed to fix Jaeger exporter test panic with close closed channel. (Jaeger exporter test failure: panic: close of closed channel #1870, Bugfix jaeger exporter test panic #1973)
• Avoid transport security when OTLP endpoint is a Unix socket. (otlp: mark unix endpoints to work without transport security #2001)

[codecov]

Codecov Report

Merging #2013 (728cb35) into main (694c9a4) will not change coverage.
The diff coverage is 100.0%.

@@          Coverage Diff          @@
##            main   #2013   +/-   ##
=====================================
  Coverage   73.0%   73.0%           
=====================================
  Files        171     171           
  Lines       8687    8687           
=====================================
  Hits        6348    6348           
  Misses      2070    2070           
  Partials     269     269           

Impacted Files	Coverage Δ
version.go	100.0% <100.0%> (ø)

[MrAlias]

Looks good 🏅. As mentioned in the SIG meeting this needs updates to the website docs. My approval should persist with those changes added.

[jmacd]

🎉

[XSAM]

💯

[pellared]

How about changing the tag name to v1.0.0-rc.1
This is the convention that SemVer uses itself.
Example: https://semver.org/spec/v2.0.0-rc.1.html

Or at least v1.0.0-rc1 - I have never seen the capitals RC in tags before 😉

[Aneurysm9]

This was discussed in the SIG meeting and it is valid semver accepted by the Go module tooling. There's not a strong reason to change it. Plus, RC is an initialism and Go conventions dictate it be in all caps :)

[pellared]

OK😉

I also saw such patterns under: https://blog.golang.org/publishing-go-modules
And https://golang.org/ref/mod also has lowercase.
But it is not anything critical. Just a matter of taste 😄