OpenTelemetry Java Contrib v1.61.0 - Sampling policy migration
OpenTelemetry Java Contrib v1.61.0, published on October 9, 2026, changes how dynamic control interprets trace sampling values. Existing ratio configurations need a migration: leaving a value of 0.5 under trace-sampling now means 0.5% sampling instead of 50%. This release also changes JMX metric selection and adds a way to detect unread data discarded from disk buffers.
The full release notes are on the GitHub release page. This is not a prerelease, and it targets OpenTelemetry Java Instrumentation 2.32.0.
Sampling policies need an explicit unit
The breaking change is the distinction between percentages and ratios. The trace-sampling policy type now accepts percentages from 0.0 to 100.0. To preserve an existing ratio, change policyType: trace-sampling to policyType: sampling-rate and keep the numeric value unchanged.
For example, sampling-rate with 0.5 retains the previous 50% sampling intent. Keeping trace-sampling requires a value of 50.0 for that same percentage. Configuring both policy types at once is rejected, so choose one representation for the policy.
Full JSON policies also replace keep.probability with keep.ratio or keep.percentage. Review those field names alongside the policy type before upgrading. A configuration that still contains the old ratio under trace-sampling can reduce the intended sampling percentage by a factor of 100. The percentage policy change is the main compatibility item in this release.
JMX target names and Cassandra metrics change
JMX targets backed by instrumentation metric definitions now use plain names such as cassandra and kafka-connect. The experimental- prefix is deprecated and produces a warning.
For Cassandra, the default otel.jmx.target.source=auto now selects instrumentation definitions instead of the legacy definitions. Set otel.jmx.target.source=legacy to retain the previous metrics. If dashboards depend on those metrics, check this setting during the upgrade. The change affects which definitions supply the metrics, as well as the target naming convention.
Disk buffering can report discarded files
Disk buffering adds DiscardedFileListener, configured through FileStorageConfiguration.Builder.setDiscardedFileListener. It notifies callers when a stored file is deleted before all its data has been read.
The covered cases are expiration, deletion to enforce the folder size limit, and corruption. For applications using disk buffering, this gives operators a hook to observe data discarded from storage. The callback reports the deletion; the release notes do not describe a recovery mechanism for that data.
Kafka exporter picks up security fixes
The Kafka exporter pins zstd-jni to 1.5.7-20. That brings in security fixes not yet included through the kafka-clients dependency.
This is a dependency update for exporter users. The notes do not identify individual vulnerabilities or describe a configuration migration for this change.