Version 1.7.0

Version 1.7.0 (2021-10-08):

General

• IMPORTANT: The io.opentelemetry:opentelemetry-proto module should now be considered deprecated. It will be removed from publications in a future release. If you need Java bindings for the OTLP protobufs, they are now being published via the new opentelemetry-proto-java repository. They are at new maven coordinates: io.opentelemetry.proto:opentelemetry-proto and versioning is aligned with the released version of the protobuf definitions themselves.

SDK

Exporters

• BREAKING CHANGE: The Jaeger gRPC exporter does not directly use the protobuf-java library for
  marshaling trace data. Along with this, the opentelemetry-exporter-jaeger artifact does not
  contain generated protobuf classes for the Jaeger API. If you were using these in your
  application, you must update your build configuration to also include the new jaeger-proto
  artifact. This artifact will not be included in a future 2.0 release of the SDK so it is
  recommended to instead generated the protobuf classes in your own build.
• BREAKING CHANGE: The opentelemetry-exporter-otlp-http-* exporter default endpoint ports have
  changed from 4317 to 4318, in line with recent changes to the spec.
• The OTLP gRPC exporters will now function without the grpc-java dependency, if okhttp is
  present on the classpath.
• The (alpha) metrics that are generated by the gRPC exporters have changed slightly. They now have
  a slightly different instrumentation library name, "io.opentelemetry.exporters.otlp-grpc" and
  the names of the metrics have also changed. Now emitted are metrics with
  names otlp.exporter.seen and otlp.exported.exported. Note that it is likely this will change
  in the future as the metrics semantic conventions are more defined.

Auto-configuration (alpha)

• BREAKING CHANGE: The behavior of otel.exporter.otlp.endpoint has changed when the protocol
  is http/protobuf. The new behavior is in line with recent changes to the specification, which states that the signal path (e.g. v1/traces or v1/metrics) is appended to the configured endpoint. Values for signal specific endpoint configuration (e.g. otel.exporter.otlp.traces.endpoint and otel.exporter.otlp.metrics.endpoint) override the generic endpoint configuration and are used as-is without modification.
• The compression option for exporters now explicitly supports the none value, in addition to the existing gzip value.

Metrics (alpha)

• BREAKING CHANGE: The IntervalMetricReader has been removed, and replaced with
  a PeriodicMetricReader that provides an implementation of the new MetricReader interface.
• This release includes initial support for multiple exporters to be configured for a single SDK
  instance. See the SdkMeterProviderBuilder.registerMetricReader method for more details.
• This release includes initial support for the SDK recording of Metric Exemplars for sampled Spans.
  See SdkMeterProviderBuilder.setExemplarFilter and the ExemplarFilter interface for
  more details.

Logging (alpha)

• This release includes SDK extension interfaces for LogProcessors and LogExporters, and has
  implementations for batch log processing and export via OTLP. These classes are intended for usage
  in implementations of log appenders that emit OTLP log entries.

Version 1.6.0

API

• Various performance optimizations
  • 1 and 2 element Attributes instances now bypass some logic to reduce object allocations.
  • The result of hashCode() of AttributeKey is now cached.
  • Checks for base-16 validity of TraceId and SpanId have been optimized.
  • Internally created SpanContext instances now bypass unneeded validation.

Semantic Conventions (alpha)

• The SemanticAttributes and ResourceAttributes classes have been updated to match the semantic
  conventions as of specification release 1.6.1.

SDK

• The io.opentelemetry.sdk.trace.ReadableSpan interface has been expanded to include
  a getAttribute(AttributeKey) method.
• The io.opentelemetry.sdk.trace.SpanLimits class now supports enforcing a maximum Span attribute
  length (measured in characters) on String and String-array values.

Exporters

• The OTLP exporters have been undergone a significant internal rework. Various performance
  optimizations have been done on process of converting to the OTLP formats. Because of this, the exporter libraries
  no longer have a runtime dependency on the opentelemetry-proto artifact, or transitively protobuf. If you were
  using code from these libraries through these transitive dependencies, you will need to add them directly to your
  build.
• The OTLP metric exporter no longer exports the deprecated metric Labels, only Attributes. This
  means that your collector MUST support at least OTLP version 0.9.0 to properly ingest metric
  data.
• BREAKING CHANGE: The OtlpHttpMetricExporter class has been moved into
  the io.opentelemetry.exporter.otlp.http.metrics package.
• BUGFIX: The OtlpGrpcSpanExporter and OtlpGrpcMetricExporter will now wait for the underlying
  grpc channel to be terminated when shutting down.
• The OTLP exporters now optionally support gzip compression. It is not enabled by default.

SDK Extensions

• The AwsXrayIdGenerator in the opentelemetry-sdk-extension-aws module has been deprecated. This
  implementation has been superseded by the one in
  the opentelemetry-java-contrib
  project and will not be maintained here going forward.

Auto-configuration (alpha)

• The otel.traces.exporter/OTEL_TRACES_EXPORTER option now supports a comma-separated list of
  exporters.
• The Metrics SDK will no longer be configured by default. You must explicitly request an exporter
  configuration in order to have a Metrics SDK configured.
• BREAKING CHANGE: All SPI interfaces are now in a separate module from the autoconfiguration
  module: opentelemetry-sdk-extension-autoconfigure-spi.
• BREAKING CHANGE: ConfigProperties and ConfigurationException have been moved to a new
  package (io.opentelemetry.sdk.autoconfigure.spi) and
  module (opentelemetry-sdk-extension-autoconfigure-spi).
• BREAKING CHANGE: All SPI interfaces now take a ConfigProperties instance on their methods.
• BUGFIX: Exceptions thrown during the loading of an SPI implementation class are now handled more
  gracefully and will not bubble up unless you have explicitly requested the bad implementation as
  the one to use.
• You can now specify gzip compress for the OTLP exporters via the otel.exporter.otlp.compression
  /OTEL_EXPORTER_OTLP_COMPRESSION configuration option.
• You can now specify maximum Span attribute length via the otel.span.attribute.value.length.limit
  /OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT configuration option.

Metrics (alpha)

• BREAKING CHANGES: The metrics SDK has numerous breaking changes, both behavioral and in the SDK's
  configuration APIs.
  • The default aggregation for a Histogram instrument has been changed to be a Histogram, rather than a Summary.
  • Registration of Views has undergone significant rework to match the current state of the SDK specification. Please reach out on CNCF slack in the #otel-java channel, or in a github discussion if you need assistance with converting to the new Views API.
  • The OTLP exporter no longer exports the deprecated metric Labels, only Attributes. This means that your collector MUST support at least OTLP version 0.9.0 to properly ingest metric data.
  • It is no longer possible to provide custom aggregations via a View. This feature will return in the future.

Version 1.5.0

API

• The io.opentelemetry.context.ContextStorage interface now allows providing a root Context.

SDK

• The io.opentelemetry.sdk.trace.samplers.SamplingResult class has been enhanced with new factory methods for the static result values.
• The io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter now supports setting custom TLS certificates.
• The io.opentelemetry.sdk.trace.ReadableSpan interface now exposes the parent SpanContext directly.
• The io.opentelemetry.sdk.resources.Resource now exposes a getAttribute(AttributeKey) method to directly retrieve attributes.
• A new opentelemetry-exporter-otlp-http-trace module is now available to support OTLP over HTTP exports.

SDK Extensions

• The opentelemetry-sdk-extension-resources module now provides a new ContainerResource that auto-detects docker container Resource attributes.
• The Jaeger Remote Sampler in the opentelemetry-sdk-extension-jaeger-remote-sampler module is now java.io.Closeable.

Testing

• The SDK testing module (opentelemetry-sdk-testing) has been enhanced with additional assertions for Spans and Attributes.

Auto-configuration (alpha)

• BREAKING CHANGE: io.opentelemetry.sdk.autoconfigure.ConfigProperties in the opentelemetry-sdk-extension-autoconfigure is now an interface
  and io.opentelemetry.sdk.autoconfigure.OpenTelemetrySdkAutoConfiguration.initiatize() now accepts an optional ConfigProperties
  instance to add properties to the standard auto-detected ones.
• BREAKING CHANGE: OpenTelemetrySdkAutoConfiguration.getResource() has been removed in favor of using the new OpenTelemetryResourceAutoConfiguration class.
• The opentelemetry-sdk-extension-autoconfigure module now exposes a new OpenTelemetryResourceAutoConfiguration
  class specifically for acquiring autoconfigured Resource instances.
• The opentelemetry-sdk-extension-autoconfigure module now provides an option to not set the GlobalOpenTelemetry instance when auto-configuring.
• The opentelemetry-sdk-extension-autoconfigure module now has support for signal-specific timeout, header and TLS certificate configuration.
• A new SPI option is available for configuring a metrics exporter. See io.opentelemetry.sdk.autoconfigure.spi.ConfigurableMetricExporterProvider for details.
• A new OTEL_TRACES_SAMPLER/otel.traces.sampler option is available: jaeger_remote.
  • It can be configured using the OTEL_TRACES_SAMPLER_ARG/otel.traces.sampler.arg, which is parsed as a comma-separated map.
    • For example -Dotel.traces.sampler=jaeger_remote -Dotel.traces.sampler.arg=endpoint=192.168.1.5:14250,pollingInterval=5000,initialSamplingRate=0.01

Semantic Conventions (alpha)

• The SemanticAttributes and ResourceAttributes classes have been updated to match the semantic conventions
  as of specification release 1.5.0.

Metrics (alpha)

• BREAKING CHANGE: The Metrics API has been completely re-written to match the newly specified API.
  Please reach out on CNCF slack in the #otel-java channel,
  or in a github discussion if you need assistance with converting to the new API.
• A new opentelemetry-exporter-otlp-http-metrics module is now available to support OTLP over HTTP exports.

Version 1.4.1

• Fill labels in addition to attributes during OTLP metrics export to support versions of the
  OpenTelemetry Collector which do not support the new protocol yet.

Version 1.4.0

API

Enhancements

• You can now assign an OpenTelemetry schema URL to a Tracer via the new TracerBuilder class that is
  accessed via the TracerProvider or any of the global instances that delegate to one.

Extensions

• A new @SpanAttribute annotation has been added for adding method parameters to spans automatically. This
  has no implementation in this release, but should be supported by the auto-instrumentation agent soon.

Exporters

Bugfixes

• Calling shutdown() multiple times on the OTLP and Jaeger GRPC-based exporters will now work correctly and return a proper
  implementation of CompletableResultCode for the calls beyond the first.

SDK

Bugfixes

• If the jdk.unsupported package is not available, the BatchSpanProcessor will now fall back to a supported, standard Queue implementation.

Enhancements

• A Resource can now be assigned an OpenTelemetry schema URL via the ResourceBuilder or the create(Attributes, String)
  method on the Resource itself.
• You can now obtain a default Clock based on system time via Clock.getDefault. The sdk-testing artifact also provides
  a TestClock for unit testing.

Semantic Conventions (alpha)

• The SemanticAttributes and ResourceAttributes classes have been updated to match the semantic conventions
  as of specification release 1.4.0. These classes also now expose a SCHEMA_URL field which points at the
  version of the OpenTelemetry schema the files were generated from. There are no breaking changes in this update, only additions.

Metrics (alpha)

• You can now assign an OpenTelemetry schema URL to a Meter via the new MeterBuilder class that is
  accessed via the MeterProvider or any global instances that delegate to one.
• The metrics SDK now utilizes Attributes rather than Labels internally.
• You can now register an IntervalMetricReader as global and forceFlush the global reader.

Version 1.3.0

Changelog:

API

Enhancements

• Parsing of the W3C Baggage header has been optimized.

SDK

Behavioral Changes

• The implementation of SpanBuilder will no longer throw exceptions when null parameters are passed in. Instead,
  it will treat these calls as no-ops.

Enhancements

• Memory usage of the Tracing SDK has been greatly reduced when exporting via the OTLP or Jaeger exporters.
• The OTLP protobuf version has been updated to v0.9.0

Extensions

• A new experimental extension module has been added to provide a truly no-op implementation of the API. This
  is published under the io.opentelemetry.extension.noopapi name.
• The io.opentelemetry.sdk.autoconfigure module now supports the OTEL_SERVICE_NAME/otel.service.name
  environment variable/system property for configuring the SDK's Resource implementation.

Metrics (alpha)

• The autoconfiguration code for metrics now supports durations to be provided with units attached to them (eg. "100ms"). This includes
  the following environment variables/system properties:
  • OTEL_EXPORTER_OTLP_TIMEOUT/otel.exporter.otlp.timeout
  • OTEL_IMR_EXPORT_INTERVAL/otel.imr.export.interval

---

Many thanks to all the people who contributed to this release:
@anuraaga
@char16t
@iNikem
@jkwatson
@kubawach
@mxiamxia
@piotr-sumo
@wsargent
@Xyira

Version 1.2.0

General

Enhancements

• The "Implementation-Version" attribute has been added to the jar manifests for all published jar artifacts.

API

Enhancements

• A new method has been added to the Span and the SpanBuilder to enable adding a set of Attributes in one call, rather than
  having to iterate over the contents and add them individually. See Span.setAllAttributes(Attributes) and SpanBuilder.setAllAttributes(Attributes)

Behavioral Changes

• Previously, an AttributeKey with a null underlying key would preserve the null. Now, this will be converted to an empty String.

SDK

Enhancements

• The IdGenerator.random() method will now attempt to detect if it is being used in an Android environment, and use
  a more Android-friendly IdGenerator instance in that case. This will affect any usage of the SDK that does not
  explicitly specify a custom IdGenerator instance when running on Android.

Behavioral Changes

• The name used for Tracer instances that do not have a name has been changed to be an empty String, rather than the
  previously used "unknown" value. This change is based on a specification clarification.

Propagators

Bugfixes

• The B3 Propagator injectors now only include the relevant fields for the specific injection format.

Behavioral Changes

• The W3CBaggagePropagator will no longer explicitly populate an empty Baggage instance into the context when
  the header is unparsable. It will now return the provided Context instance unaltered, as is required by the specification.
• The AwsXrayPropagator will no longer explicitly populate an invalid Span instance into the context when
  the headers are unparsable. It will now return the provided Context instance unaltered, as is required by the specification.

Exporters

• The jaeger-thrift exporter has had its dependency on the jaeger-client library updated to version 1.6.0.
• The zipkin exporter now has an option to specific a custom timeout.
• The zipkin, jaeger and jaeger-thrift exporters will now report the otel.dropped_attributes_count and otel.dropped_events_count
  tags if the numbers are greater than zero.

Semantic Conventions (alpha)

Breaking Changes

• The SemanticAttributes and ResourceAttributes have both been updated to match the OpenTelemetry Specification v1.3.0 release, which
  includes several breaking changes.
• Values that were previously defined as enums are now defined as static public static final constants of the appropriate type.

OpenTracing Shim (alpha)

Enhancements

• Error logging support in the shim is now implemented according to the v1.2.0 specification.

SDK Extensions

• A new HostResource Resource and the corresponding ResourceProvider has been added.
  It will populate the host.name and host.arch Resource Attributes.
• A new ExecutorServiceSpanProcessor has been added to the opentelemetry-sdk-extension-tracing-incubator module. This implementation
  of a batch SpanProcessor allows you to provide your own ExecutorService to do the background export work.
• The autoconfigure module now supports providing the timeout setting for the Jaeger GRPC exporter via
  a system property (otel.exporter.jaeger.timeout) or environment variable (OTEL_EXPORTER_JAEGER_TIMEOUT).
• The autoconfigure module now supports providing the timeout setting for the Zipkin exporter via
  a system property (otel.exporter.zipkin.timeout) or environment variable (OTEL_EXPORTER_ZIPKIN_TIMEOUT).
• The autoconfigure module now exposes the EnvironmentResource class to provide programmatic access to a Resource
  built from parsing the otel.resource.attributes configuration property.

Metrics (alpha)

Breaking Changes

• The deprecated SdkMeterProvider.registerView() method has been removed. The ViewRegistry is now immutable and cannot
  be changed once the SdkMeterProvider has been built.

Bugfixes

• OTLP summaries now have the proper percentile value of 1.0 to represent the maximum; previously it was wrongly set to 100.0.

Enhancements

• There is now full support for delta-aggregations with the LongSumAggregator and DoubleSumAggregator.
  See AggregatorFactory.sum(AggregationTemporality). The previous AggregatorFactory.sum(boolean) has been
  deprecated and will be removed in the next release.

---

Many thanks to all the people who contributed to this release:

• @jkwatson
• @jack-berg
• @kubawach
• @harshita19244
• @anuraaga
• @HaloFour
• @arminru
• @Hangzhi
• @piotr-sumo
• @tydhot
• @malafeev
• @trask

Version 1.1.0

API

Bugfixes

• We now use our own internal @GuardedBy annotation for errorprone so there won't be an accidental
  transitive dependency on a 3rd-party jar.
• The TraceStateBuilder now will not crash when an empty value is provided.

Enhancements

• The Context class now provides methods to wrap java.util.concurrent.Executor and java.util.concurrent.ExecutorService
  instances to do context propagation using the current context. See io.opentelemetry.context.Context.taskWrapping(...) for
  more details.

OpenTracing Shim (alpha)

• The shim now supports methods that take a timestamp as a parameter.
• You can now specify both the TEXT_MAP and the HTTP_HEADER type propagators for the shim.
  See io.opentelemetry.opentracingshim.OpenTracingPropagators for details.

Extensions

• The AWS X-Ray propagator is now able to extract 64-bit trace ids.

SDK

Bugfixes

• The CompletableResultCode.join(long timeout, TimeUnit unit) method will no longer fail the result
  when the timeout happens. Nor will whenComplete actions be executed in that case.
• The SimpleSpanProcessor now keeps track of pending export calls and will wait for them to complete
  via a CompletableResultCode when forceFlush() is called. Similiarly, this is also done on shutdown().
• The Jaeger Thrift exporter now correctly populates the parent span id into the exporter span.

Enhancements

• The SpanBuilder provided by the SDK will now ignore Link entries that are reference an invalid SpanContext.
  This is an update from the OpenTelemetry Specification v1.1.0 release.
• The OTLP Exporters will now log more helpful messages when the collector is unavailable or misconfigured.
• The internals of the BatchSpanProcessor have had some optimization done on them, to reduce CPU
  usage under load.
• The Resource class now has builder() and toBuilder() methods and a corresponding ResourceBuilder class
  has been introduced for more fluent creation and modification of Resource instances.
• The standard exporters will now throttle error logging when export errors are too frequent. If more than 5
  error messages are logged in a single minute by an exporter, logging will be throttled down to only a single
  log message per minute.

SDK Extensions

Bugfixes

• Removed a stacktrace on startup when using the autoconfigure module without a metrics SDK on the classpath.

Enhancements

• The autoconfigure module now supports OTEL_EXPORTER_OTLP_METRICS_ENDPOINT and OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  settings, in addition to the combined OTEL_EXPORTER_OTLP_ENDPOINT environment variable. Corresponding
  system properties are also supported (-Dotel.exporter.otlp.metrics.endpoint and -Dotel.exporter.otlp.traces.endpoint).
• An SdkMeterProviderConfigurer SPI is now available in the autoconfigure module.

Semantic Conventions (alpha)

• The SemanticAttributes and ResourceAttributes have both been updated to match the OpenTelemetry Specification v1.1.0 release.
  This includes a breaking changes to the constants defined in the ResourceAttributes class:
  ResourceAttributes.CLOUD_ZONE has been replaced with ResourceAttributes.CLOUD_AVAILABILITY_ZONE.

Metrics (alpha)

Breaking Changes

• The ViewRegistry now lets you register View objects, rather than AggregatorFactory instances.
• GlobalMetricsProvider has been renamed to GlobalMeterProvider.
• View registration has been moved to the SdkMeterProviderBuilder and the methods on the SdkMeterProvider
  to add views have been deprecated. They will be removed in the next release.

Enhancements

• A new option for aggregation as Histograms is now available.

Many thanks to all the people who contributed to this release:

@anuraaga @jkwatson @jack-berg @Oberon00 @beanliu @malafeev @sbandadd @breedx-splk @as-polyakov @kubawach @austinlparker @harshita19244 @mateuszrzeszutek @piotr-sumo @topher1120

Version 1.0.1

Version 1.0.1 - 2021-03-11

Bugfixes

• AWS resource extensions have been fixed to not throw NullPointerException in actual AWS environment

Version 1.0.0

Version 1.0.0 - 2021-02-26

General

This releases marks the first stable release for the tracing, baggage and context APIs and the SDK.
Please see the Versioning document for stability guarantees.

The best source of a list of the now stable packages can be found in the opentelemetry-bom artifact in maven central.

Javadoc is available at javadoc.io. For example, javadoc.io for the API module.

Changes

• The opentelemetry-proto module is now versioned as an alpha module, as it contains non-stable
  metrics and logs signals. It has hence been removed from the main BOM.
• The opentelemetry-sdk-extension-otproto module has been removed. The classes in it have been moved
  to a new opentelemetry-exporter-otlp-common module but have been repackaged into an unsupported,
  internal package.

Metrics (alpha)

Breaking Changes

• PrometheusCollector.Builder inner class has been moved to the top level as PrometheusCollectorBuilder.

Many thanks to all the people who have contributed over the past few years! We couldn't have done without everyone's help.