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

Version 1.10.0 RC1

OpenTelemetry SDK 1.10 will be the first release where the metrics API is considered stable. The Metrics SDK continues to be in development and will be alpha.

We plan to release this RC1 with redundant metrics APIs deprecated, RC2 with them removed, and 1.10.0 the same as RC2 barring unforeseen issues.

API

• 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
• Double/LongMeasurement.observe has been renamed to record.observe is deprecated in this release
• GlobalMeterProvider has been deprecated. GlobalOpenTelemetry.getMeterProvider should be used instead

SDK

• The semantic conventions have been updated to 1.8.0

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

Metrics (Alpha)

• 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 (Alpha)

• LogDataBuilder can now take a SpanContext directly
• SdkLogEmitterProvider.get convenience method added

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

New Contributors

• @svalaskevicius made their first contribution in #3921
• @elevenzhan made their first contribution in #3951

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

Version 1.9.1

Bugfixes

• In Prometheus exporter, only populate exemplars for Prometheus types that support them
• Fix proto encoding of oneof values in metrics
• Correctly cleanup OkHttp client resources when shutting down exporters

Version 1.9.0

Note that due to an issue in publishing of Java artifacts, the 1.8.0 version has been skipped. The version before this one is 1.7.1.

General

• IMPORTANT: The deprecated io.opentelemetry:opentelemetry-proto module was removed. Java bindings for OTLP protobufs are now published via opentelemetry-proto-java, and available at maven coordinates io.opentelemetry.proto:opentelemetry-proto.

API

• New AttributesBuilder#remove(String) and AttributeBuilder#removeIf(Predicate<AttributeKey<?>>) methods improve ergonomics of modifying attributes.
• W3CBaggagePropagator now encodes baggage values in URL encoded UTF-8 format, per the W3C Baggage Specification.

SDK

• DelegatingSpanData has been promoted from incubation and is now available in the Trace SDK. The DelegatingSpanData class in the io.opentelemetry:opentelemetry-sdk-extension-tracing-incubator module is now deprecated.

Exporters

• The prometheus metric exporter now includes the time_unix_nano representing the epoch timestamp when collection occurred.
• The OTLP grpc exporters (OtlpGrpcSpanExporter, OtlpGrpcLogExporter, and OtlpGrpcMetricExporter) now include a default client implementation (okhttp). If a grpc implementation is detected on the classpath it will be used, but the exporters now work "out of the box" with no additional dependencies.

SDK Extensions

• IMPORTANT: The deprecated io.opentelemetry:opentelemetry-sdk-extension-async-processor module was removed. This module is now published via opentelemetry-java-contrib, and available at maven coordinates io.opentelemetry.contrib:opentelemetry-disruptor-processor.
• The ExecutorServiceSpanProcessor from the io.opentelemetry:opentelemetry-sdk-extension-tracing-incubator module is now deprecated.

Logging (alpha)

• This release includes a rework of the Log SDK to implement OTEP-0150 and to have more symmetry to the Trace SDK. LogSink is now LogEmitter. LogEmitter instances are obtained from SdkLogEmitterProvider. Other additions include MultiLogProcessor (accessed via LogProcessor#composite(...)), SimpleLogProcessor, InMemoryLogExporter, OtlpJsonLoggingLogExporter, and SystemOutLogExporter.
• The Log SDK maven coordinates have changed from io.opentelemetry:opentelemetry-sdk-extension-logging to io.opentelemetry:opentelemetry-sdk-logs.

Metrics (alpha)

• The new InMemoryMetricReader() constructor has been deprecated. Use InMemoryMetricReader.create() instead.
• A typo in Aggregation.explictBucketHistogram() has been fixed, and is now accessible at Aggregation.explicitBucketHistogram().
• The PeriodicMetricReader#builder(MetricExporter) builder replaces PeriodicMetricReader#newMetricReaderFactory(MetricExporter, Duration).
• Aggregation temporality is now influenced by metric exporters, and the ability to configure aggregation temporality via the view API has been removed. For example, the OTLP metric exporters support both DELTA and CUMULATIVE temporality. CUMULATIVE is the default preferred, but this can be changed either via programmatic configuration or
  via OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY if using autoconfigure.
• The MeterProvider#get(String instrumentationName, String instrumentationVersion, String schemaUrl) method is deprecated. Use MeterProvider#meterBuilder(String instrumentationName) with corresponding builder setters instead.
• Metric cardinality defenses have been added. Each instrument view now can have at most 2000 distinct metric streams per collection cycle. Recordings for additional streams are dropped with a diagnostic log message. Additionally, cumulative metric streams (both for synchronous and asynchronous instruments) are aggressively forgotten each time a metric export occurs that does not include recordings for a particular stream. The net effect is that there is now a cap on metric memory consumption.

Auto-configuration (alpha)

• BREAKING CHANGE: Remove deprecated otel.experimental.exporter.otlp.protocol, otel.experimental.exporter.otlp.{signal}.protocol properties. Please use otel.exporter.otlp.protocol, otel.exporter.otlp.{signal}.protocol instead.
• The autoconfigure module has introduced a powerful new AutoConfiguredOpenTelemetrySdkBuilder, and SPI for programmatically configuring the builder with AutoConfigurationCustomizerProvider. This provides improved ergonomics and control around autoconfigure customization.
• Added experimental support for enabling OTLP retry support for the grpc exporters. If enabled via otel.experimental.exporter.otlp.retry.enabled, a default retry policy will be used.
• The metric export interval of PeriodicMetricReader is now configured via otel.metric.export.interval. The existing otel.imr.export.interval property has been deprecated.
• The SPI classloader can now be specified when using the autoconfigure module programmatically.