Version 1.17.0

API

API Extensions

• DEPRECATION: the opentelemetry-extension-annotations module containing @WithSpan and @SpanAttribute annotations has been deprecated for removal in next major version. A copy of the code will instead be maintained in opentelemetry-java-instrumentation/instrumentation-annotations and published under coordinates io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:{version}.

SDK

Traces

• Add default implementation for SpanData#getInstrumentationScopeInfo() and ReadableSpan#getInstrumentationScopeInfo(). This fixes a previous mistake where those interfaces were extended without default implementation, a breaking change for source compatibility. Stricter checks have been added to ensure this mistake is not repeated.

Logs

• BREAKING: delete LogDataBuilder. A similar implementation of LogData called TestLogData has been added to opentelemetry-sdk-logs-testing.
• BREAKING: rename LogProcessor#emit(LogData) to LogProcessor#onEmit(ReadWriteLogRecord). The argument change from LogData to ReadWriteLogRecord allows implementations to mutate logs. To obtain LogData, call ReadWriteLogRecord#toLogData().
• Optimize SdkLogEmitterProvider to return noop LogEmitter when no LogProcessors are registered.

Exporter

• Split out shared and internal exporter classes from opentelemetry-exporter-otlp-common to opentelemetry-exporter-common.
• Add experimental support for OTLP header based authentication. To use, add a dependency on opentelemetry-exporter-common and call io.opentelemetry.exporter.internal.auth.Authenticator#setAuthenticatorOnDelegate(OtlpHttp{Signal}Builder, Authenticator).
• Add ability to collect export metrics on ZipkinSpanExporter via ZipkinSpanExporter#setMeterProvider(MeterProvider).
• Minor optimization to OkHttp based exporters to cache endpoint URLs. Applies to OtlpHttp{Signal}Exporter, OtlpGrpc{Signal}Exporter, and more.
• Fix diagnostic log message in OtlpGrpc{Signal}Exporter to include correct environment variables.

SDK Extensions

• Extend View file based configuration with support for specifying explicit bucket histogram bucket boundaries and exponential bucket counts.
• Extend autoconfigure SPI AutoConfigurationCustomizerProvider and ResourceProvider with option to specify ordering.
• Add autoconfigure SPI with ConfigurableLogExporterProvider, allowing custom named log exporters to be provided and selected via autoconfigure.
• Extend autoconfigure SPI with AutoConfigurationCustomizer#addPropertiesCustomizer, providing the ability examine current configuration properties and add / overwrite properties.

🙇 Thank you

This release was possible thanks to the following contributors who shared their brilliant ideas and awesome pull requests:

@anuraaga
@bogdandrutu
@breedx-splk
@chalin
@DaveCTurner
@deejgregor
@Donnerbart
@GrahamLea
@iRevive
@jack-berg
@JavaPerformance
@jkwatson
@lmolkova
@mateuszrzeszutek
@sfriberg
@trask
@trivikr

Version 1.16.0

API

• Fix bug ImmutableKeyValuePairs implementation that causes ArrayIndexOutOfBoundsException to be thrown under certain conditions.

SDK

Traces

• Optimize BatchSpanProcessor using JcTools.

Metrics

• Tighten up exponential histogram implementation for alignment with specification: Default to 160 positive and negative buckets. Remove ability to configure starting scale. Minimum number of buckets is one instead of zero.
• Allow MetricExporter and MetricReader to influence default aggregation. The default aggregation is used when no registered views match an instrument.

Exporter

• Fix handling of client keys in PEM format.
• For OTLP exporters, change behavior to use OkHttpGrpcExporter (OkHttp implementation that doesn't use any gRPC dependencies) unless OtlpGrpc{Signal}Builder#setChannel(ManagedChannel) is called by user. Previously, OkHttpGrpcExporter was used if no gRPC implementation was found on classpath.
• Add support to configure default aggregation on OTLP metric exporters via Otlp{Protocol}MetricExporterBuilder#setDefaultAggregationSelector(DefaultAggregationSelector).

Testing

• Add span status assertions.

SDK Extensions

• Autoconfigure properly handles non-string system properties.
• Autoconfigure normalizes hyphens - to periods . when accessing ConfigProperties.

OpenTracing Shim

• Add support for span wrappers.
• Store OpenTracing SpanContext in OpenTracing Span wrapper.
• Use Baggage of active span.

🙇 Thank you

This release was possible thanks to the following contributors who shared their brilliant ideas and awesome pull requests:

@aaron-ai
@anuraaga
@breedx-splk
@carlosalberto
@codeboten
@cuichenli
@fax4ever
@HaloFour
@jack-berg
@jkwatson
@jsuereth
@mateuszrzeszutek
@mohitmahi
@pavolloffay
@pureklkl
@trask
@xiangtianyu
@zeitlinger

Version 1.15.0

API

• Add batch callback API, allowing a single callback to record measurements to multiple metric instruments.

SDK

Metrics

• SdkMeterProvider#toString() now returns a useful string describing configuration.
• Fix bug preventing proper function of Metrics SDK when multiple readers are present (#4436).
• Fix reporting intervals for metrics for delta readers (#4400).

Exporter

• BREAKING: merge all stable OTLP exporters into opentelemetry-exporter-otlp. opentelemetry-exporter-otlp-trace, opentelemetry-exporter-otlp-metrics, opentelemetry-exporter-otlp-http-trace, and opentelemetry-exporter-otlp-http-metrics are no longer published and their contents have been merged into a single artifact.
• BREAKING: merge log OTLP exporters into opentelemetry-exporter-otlp-logs. opentelemetry-exporter-otlp-http-logs is no longer published and its contents have been merged into a single artifact.
• Upgrade to OTLP protobuf version 0.18.0.
• RetryInterceptor retries on SocketTimeoutException with no message.
• Added JaegerGrpcSpanExporterBuilder#setMeterProvider(), enabling support of experimental jaeger span export metrics.
• DEPRECATION: the opentelemetry-exporter-jaeger-proto module containing jaeger proto definitions and corresponding generated classes is deprecated for removal in next major version.
• OTLP gRPC exporters support overriding :authority via OtlpGrpc*ExporterBuilder#addHeader("host", "my-authority-override").

SDK Extensions

• BREAKING: Move ConfigureableMetricExporterProvider from opentelemetry-sdk-extension-autoconfigure to stable opentelemetry-sdk-extension-autoconfigure-spi.
• Autoconfigure now supports multiple values for otel.metrics.exporter.
• Autoconfigure now supports general attribute limits, applicable to span attributes, span event attributes, span link attributes, and log attributes.
• Autoconfigure now supports an experimental option to disable the SDK. If otel.experimental.sdk.enabled=true, AutoConfiguredOpenTelemetrySdk#getOpenTelemetrySdk() returns a minimal (but not noop) OpenTelemetrySdk. The same minimal instance is set to GlobalOpenTelemetry.
• New "get or default" methods have been added to ConfigProperties. E.g. ConfigProperties#getString("otel.metrics.exporter", "otlp") fetches the value for the property otel.metrics.exporter and returns otlp if it is not set.
• Fix bug in ContainerResource provider that caused it to throw an exception in some instances when containerd is used.

Micrometer shim

• Cache descriptions such that metrics with the same name use the first seen description.

🙇 Thank you

This release was possible thanks to the following contributors who shared their brilliant ideas and awesome pull requests:

@anuraaga
@breedx-splk
@chenjazz
@cyrille-leclerc
@donce
@Donnerbart
@evantorrie
@jack-berg
@jkwatson
@jonahaapala
@jsuereth
@kubawach
@laurit
@marcalff
@mateuszrzeszutek
@nicklocaso
@Oberon00
@pkgonan
@rupinder10
@trask
@wallezhang

Version v1.14.0

The metrics SDK is stable! New stable artifacts include:

• io.opentelemetry:opentelemetry-sdk-metrics (also now included in io.opentelemetry:opentelemetry-sdk)
• io.opentelemetry:opentelemetry-exporter-otlp-metrics (also now included in io.opentelemetry:opentelemetry-exporter-otlp)
• io.opentelemetry:opentelemetry-exporter-otlp-http-metrics
• Metrics testing components have been moved from io.opentelemetry:opentelemetry-sdk-metrics-testing to the stable io.opentelemetry:opentelemetry-sdk-testing.

While the API of the metrics SDK is now stable, there are a couple of known issues that will be addressed in the next release:

• The start time is incorrect for delta metrics when the first recording for a set of attributes occurs after the first collections (#4400).
• Registering multiple readers results in incorrect metrics (#4436).

SDK

Traces

• Fix bug where non-runtime exception breaks BatchSpanProcessor.
• Fix bug preventing attribute limits from applying to exception events.

Logs

• BREAKING: Drop deprecated methods referencing InstrumentationLibraryInfo from Log SDK.

Metrics

• Instrument name is validated. If invalid, a warning is logged and a noop instrument is returned.
• Default unit is empty instead of 1. If an invalid unit is set, a warning is logged and empty is used.
• Ensure symmetry between type of PointData and their type of exemplars (double or long).
• BREAKING: Rename MetricReader#flush() to MetricReader#forceFlush().
• Introduce AggregationTemporalitySelector interface for selecting aggregation temporality based on instrument. MetricReader and MetricExporter extend AggregationTemporalitySelector.

SDK Extensions

• BREAKING: Remove deprecated option to specify temporality with otel.exporter.otlp.metrics.temporality. Use otel.exporter.otlp.metrics.temporality.preference instead.
• Log warning when AwsXrayPropagator can't identify parent span id.
• Fix jaeger remote sampling bug preventing correct parsing of 0-probability sampling strategies.

Exporter

• Fix prometheus exporter formatting bug when there are no attributes.
• Ensure prometheus metrics with the same name are serialized as a group.
• BREAKING: OtlpHttpMetricExporterBuilder and OtlpGrpcMetricExporterBuilder configure aggregation temporality via #setAggregationTemporalitySelector(AggregationTemporalitySelector).

Testing

• BREAKING: Metrics testing components added to stable io.opentelemetry:opentelemetry-sdk-testing module, including InMemoryMetricReader, InMemoryMetricExporter, and MetricAssertions.assertThat(MetricData) has been moved to OpenTelemetryAssertions.assertThat(MetricData).
• BREAKING: The patterns for metrics assertions have been adjusted to better align with assertj conventions. See #4444 for examples demonstrating the change in assertion patterns.
• BREAKING: Metric assertion class names have been simplified.
• Add TraceAssert.hasSpansSatisfyingExactlyInAnyOrder(..) methods.

Micrometer shim

• Instrumentation scope name changed to io.opentelemetry.micrometer1shim.

Project tooling

• Many improvements to the build and release workflows. Big thanks to @trask for driving standardization across opentelemetry-java, opentelemetry-java-instrumentation, and opentelemetry-java-contrib!

🙇 Thank you

This release was possible thanks to the following contributors who shared their brilliant ideas and awesome pull requests:

@anuraaga
@arminru
@cbos
@chrismgrayftsinc
@gfelbing
@jack-berg
@jkwatson
@jsuereth
@kubawach
@laurit
@mateuszrzeszutek
@middlewareman
@OliverO2
@trask
@wallezhang
@ZQiannnn

Version v1.13.0

Although we originally intended 1.13.0 to be the first stable release of the metrics SDK, we've postponed it out of caution due to a large number of changes in both the metrics SDK specification and the java implementation. This release should be considered a release candidate for the metrics SDK. There are several notable changes mentioned in the Metrics section. Additionally, please note that the Auto-configuration module now enables metric export by default via OTLP, i.e. by default otel.metrics.exporter is set to otlp instead of none.

API

• Fix TraceStateBuilder reuse bug.

SDK

• InstrumentationScopeInfo replaces InstrumentationLibraryInfo. Methods returning InstrumentationLibraryInfo are deprecated.
• Add ResourceBuilder#removeIf(Predicate) method for symmetry with AttributesBuilder.

Traces

• Span events that record exceptions are instances of ExceptionEventData.

Metrics

• BREAKING: Remove MetricReader factory pattern:
  • MetricReader instances, rather than MetricReaderFacotry, are registered with SdkMeterProviderBuilder. For example: SdkMeterProvider.builder().registerMetricReader(PeriodicMetricReader.builder(exporter).build()).
  • MetricReader does not support custom implementations. Built-in readers include: PeriodicMetricReader, PrometheusHttpServer, and for testing, InMemoryMetricReader.
• BREAKING: Several breaking changes metrics to the Data classes:
  • MetriaData returns InstrumentationScopeInfo instead of InstrumentationLibraryInfo.
  • MetricData factories classes have been moved internal.
  • Exemplar data classes have been migrated to interfaces, and deprecated methods have been removed.
  • PointData classes have been migrated to interfaces.
  • ValueAtPercentile has been converted to ValueAtQuantile to reflect specification.
  • Drop HistogramPointData utility methods for finding bucket bounds.
• BREAKING: Move InstrumentType and InstrumentValueType to io.opentelemetry.sdk.metrics package.
• BREAKING: Several breaking changes to the InstrumentSelector / View APIs:
  • InstrumentSelector / View and corresponding builders have been moved to io.opentelemetry.sdk.metrics package.
  • InstrumentSelector meter selection criteria has been inlined and MeterSelector has been removed.
  • InstrumentSelector criteria has been reduced to reflect specification. All fields are exact match, except instrument name which accepts wildcard * and ? matches.
  • If InstrumentSelectorBuilder#build() is called without any selection criteria, an exception will be thrown.
  • View baggage appending attribute processor has been removed. Available for experimental use via SdkMeterProviderUtil#appendFilteredBaggageAttributes.
  • Concept of AttributeProcessor has been moved internal.
  • If a View configures an aggregation that is not compatible with the instrument type of a selected instrument, a warning is logged and the View is ignored.
• BREAKING: Remove deprecated Aggregation#histogram(). Use Aggregation#explicitBucketHistogram() instead.
• Relax behavior around conflicting instruments. If you register two instruments with the same name but conflicting description, unit, type, or value type, both will be exported and a warning will be logged indicating the metric identity conflict. Previously, the second registered would have produced a noop instrument. Likewise, if two views are registered that produce instruments with conflicting names, or if an instrument conflicts with a registered view's name, both will be exported and a warning will be logged indicating the view conflict.
• BREAKING: Exemplars have been moved to internal. By default, exemplars are enabled with with_sampled_trace filter. This can be adjusted via experimental APIs via SdkMeterProviderUtil#setExemplarFilter.
• BREAKING: MetricExporter#getPreferredTemporality() has been removed and replaced with getAggregationTemporality(InstrumentType), which allows exporters to dictate the aggregation temporality on a per-instrument basis. MetricExporter#alwaysCumulative(InstrumentType) and MetricExporter#deltaPreferred(Instrument) are provided as utilities representing common configurations.
• Callbacks associated with asynchronous instruments with multiple matching views will only be called once per collection, instead of once per view per collection.
• PeriodicMetricReader will no longer call MetricExporter#export if no metrics are available.
• BREAKING: SdkMeterProviderBuilder#setMinimumCollectionInterval has been removed. Available for experimental use via SdkMeterProviderUtil#setMinimumCollectionInterval.
• Introduce lock ensuring that metric collections occur sequentially.
• Add min and max to HistogramDataPoint.

Logs

• BREAKING: Deprecated name field has been removed.

Exporter

• Upgrade to OTLP protobuf version 0.16.0.
• Jaeger and Zipkin exporters export otel.scope.name and otel.scope.version, in addition to otel.library.name and otel.library.version which are retained for backwards compatibility.
• BREAKING: Remove deprecated PrometheusCollector. Use PrometheusHttpServer instead.
• Add support for mTLS authentication to OTLP and jaeger exporters.
• Only log once if OTLP gRPC export receives UNIMPLEMENTED.
• Jaeger remote sampler sets appropriate sampling strategy type if not provided in response.
• BREAKING: The setPreferredTemporality method has been removed from OtlpGrpcMetricExporterBuilder and OtlpHttpMetricExporterBuilder. Use setAggregationTemporality(Function<InstrumentType, AggregationTemporality>) instead.

SDK Extensions

• IMPORTANT: Auto-configuration sets otel.metrics.exporter to otlp instead of none, enabling metric export by default.
• Auto-configuration added otel.java.enabled.resource-providers property for opting into specific resource providers.

Micrometer shim

• Bring micrometer shim over from opentelemetry-java-instrumentation. Artifact is available at maven coordinates io.opentelemetry:opentelemetry-micrometer1-shim:1.13.0-alpha.
• Add support for "prometheus mode", enabling better naming when exporting micrometer metrics via prometheus.

Testing

• Add int overload for equalTo attribute assertion.
• Add SpanDataAssert.hasAttribute methods.

🙇 Thank you

This release was possible thanks to the following contributors who shared their brilliant ideas and awesome pull requests:

@anuraaga
@bogdandrutu
@breedx-splk
@HaloFour
@jack-berg
@jkamon
@jkwatson
@jsuereth
@kubawach
@mateuszrzeszutek
@mdii
@pokusak
@Rocksnake
@trask
@wallezhang
@zeitlinger

Version 1.12.0

This release includes many breaking changes to the metrics SDK as we move towards marking its first stable release.
Notably, if you configure metric Views or have written a custom metric exporter, many of the classes and methods will
have been moved or renamed. There are still a few remaining cleanups targeted for the next release after which there
should not be many. Thanks for bearing with us on this.

API

• New methods have been added to Context to propagate context for common Java 8 callback types
• AttributesBuilder.put now supports vararg versions for lists with AttributeKey
• Multiple metric async callbacks can be registered for the same instrument, and callbacks can be removed

SDK

• An issue with Android desugaring of the SDK has been worked around
• EXPERIMENTAL: Support for disabling resource keys with OTEL_EXPERIMENTAL_RESOURCE_DISABLED_KEYS
• Fixed handling of schemaUrl in Resource.toBuilder()
• BREAKING: Many changes to Data classes used during export
• BREAKING: Many view configuration methods have been removed

Metrics

• APIs deprecated in the previous release have been removed
• DEPRECATION: PrometheusCollector for exporting OpenTelemetry metrics with the prometheus client library has been deprecated
• EXPERIMENTAL: File-based configuration of views
• Prometheus exporter now supports JPMS modules

Logs

• DEPRECATION: LogData.getName has been deprecated for removal

Version 1.11.0

General

• Examples moved to opentelemetry-java-docs

SDK

Exporter

• Switch Jaeger remote sampler to use grpc lite
• Deprecate .setChannel(ManagedChannel) methods on OTLP gRPC exporters
• Deprecate .setChannel(ManagedChannel) methods on Jaeger gRPC exporter
• Experimental OTLP retry support now retries on connection timeouts

Metrics

• BREAKING Change: Deprecated InMemoryMetricExporter and InMemoryMetricReader have been removed. Use versions in opentelemetry-sdk-metrics-testing instead
• Deprecate InstrumentType values OBSERVABLE_SUM and OBSERVABLE_UP_DOWN_SUM in favor of OBSERVABLE_COUNTER and OBSERVABLE_UP_DOWN_COUNTER

Logs

• Add ability to configure log attribute limits via SdkLogEmitterProviderBuilder#setLogLimits(..)

SDK Extensions

• Auto-configuration added options to AutoConfigurationCustomizer for customizing SdkTracerProviderBuilder, SdkMeterProviderBuilder, MetricExporter, SdkLogEmitterProviderBuilder, and LogExporter
• Auto-configuration added option to skip shutdown hooks
• Auto-configuration adjusted the execution order of tracer and meter provider customization to happen after autoconfiguration
• Auto-configuration adjusted SPI factories to evaluate lazily
• Auto-configuration now uses sets configured SdkMeterProvider on BatchLogProcessor and BatchSpanProcessor
• Auto-configuration deprecated SdkTracerProviderConfigurer in favor of AutoConfigurationCustomizer#addTracerProviderCustomizer(..)

Version 1.10.1

Bugfixes

• Fix issue preventing registration of PrometheusCollector with SDK
• Allow retry policy to be set for OkHttpGrpcExporter

Version 1.10.0

(These release notes contain the content of the 1.10 RCs)

With this release, the OpenTelemetry metrics API has been marked stable - you can use it through the usual opentelemetry-api artifact. The SDK is still under development and not yet stable, but we hope this can open the door to instrumentation libraries using the metrics API.

API

• Performance of GlobalOpenTelemetry.get improved
• buildWithCallback for asynchronous metrics now return interfaces instead of void. The interfaces are empty but will allow adding functionality in the future
• BREAKING CHANGE: Double/LongMeasurement.observe have been removed, replaced with the record method.
• BREAKING CHANGE: GlobalMeterProvider has been removed
• BREAKING CHANGE: ObservableMeasurement, an empty interface, has been removed. This type was not previously deprecated but is expected to have no use in apps due to the lack of functionality
• The Metrics API has been merged into the opentelemetry-api artifact. OpenTelemetry.getMeterProvider() is the new entrypoint
• BREAKING CHANGE: Bound metrics instruments have been removed for now to allow more time to bake while still providing a stable metrics API
• A warning is logged now when registering async instruments with the same name. Previously subsequent invocations were just ignored.
• GlobalOpenTelemetry extended with helpers for meter creation

SDK

• The semantic conventions have been updated to 1.8.0
• Deprecated methods have been removed from the opentelemetry-sdk-autoconfigure artifact.

Exporter

• The OkHttp gRPC exporters now support experimental retry
• OkHttp dispatcher threads are now spawned as daemon threads
• The JPMS module name for the logs exporter has been fixed
• Metrics exporters can have temporality configured
• HTTP exporters now support experimental retry
• Jaeger exporter allows setting trusted certificates
• gRPC exporter metric typos corected

Metrics

• InMemoryMetricExporter has been moved to the opentelemetry-sdk-metrics-testing artifact. The current class has been deprecated in this release
• Metric instrument usage violations consistently report issues as debug logs
• Some user callbacks have been wrapped to catch exceptions instead of throwing
• MinMaxSumCount/Count aggregation has been removed
• Empty aggregator is renamed to drop
• Cumulative aggregations will not be aggressively dropped every collection cycle

Logs

• A opentelemetry-sdk-logs-testing module has been added
• SdkLogEmitterProvider is now available through OpenTelemetrySdk
• LogDataBuilder can now take a SpanContext directly
• SdkLogEmitterProvider.get convenience method added

AWS

• HTTP requests now use OkHttp instead of the JDK

OpenCensus Shim

• Shim span attributes are set before the span is created instead of after
• Exceptions are not thrown when activating a null span

SDK Extensions

• BREAKING CHANGE: Deprecated trace incubator types (DelegatingSpanData, SpanDataBuidler) have been removed
• BREAKING CHANGE: Deprecated ExecutorServiceSpanProcessor has been removed
• cloud.platform is now populated in AWS Resource
• Auto-configuration correctly uses configured class loader for configuring Resource
• Auto-configuration prints a debug log with the resolved tracer configuration
• Auto-configuration supports the logs signal

Version 1.10.0 RC2

This release continues preparation for the stable release of the metrics API. APIs deprecated in RC1 have been removed. It is expected for 1.10.0 to release with the same API as this release.

API

• Performance of GlobalOpenTelemetry.get improved
• buildWithCallback for asynchronous metrics now return interfaces instead of void. The interfaces are empty but will allow adding functionality in the future
• BREAKING CHANGE: Double/LongMeasurement.observe have been removed
• BREAKING CHANGE: GlobalMeterProvider has been removed
• BREAKING CHANGE: ObservableMeasurement, an empty interface, has been removed. This type was not previously deprecated but is expected to have no use in apps due to the lack of functionality

SDK

• HTTP exporters now support experimental retry
• Deprecated methods have been removed from the opentelemetry-sdk-autoconfigure artifact.

Metrics

• InMemoryMetricExporter has been moved to the opentelemetry-sdk-metrics-testing artifact. The current class has been deprecated in this release
• Metric instrument usage violations consistently report issues as debug logs

Logs

• A opentelemetry-sdk-logs-testing module has been added
• SdkLogEmitterProvider is now available through OpenTelemetrySdk

AWS

• HTTP requests now use OkHttp instead of the JDK

OpenCensus Shim

• Shim span attributes are set before the span is created instead of after
• Exceptions are not thrown when activating a null span

Full Changelog: v1.10.0-rc.1...v1.10.0-rc.2