0.31.0 Release Candidate

This issue tracks the final push for releasing the new 0.31 API for OpenTracing-Java.

After six months of research and exploration, the next version of the Java edition of OpenTracing is now available. This represents a significant effort on the part of a large group of people. The OpenTracing community has grown substantially in the last year, and that diversity is reflected in the quality of this work.

RC Branch: https://github.com/opentracing/opentracing-java/tree/v0.31.0

Current Status

• Scopes API approved.
• Documentation must be cleaned up and reviewed.
• Open call for Backwards compatibility and migration strategies.
• Open call for final API changes related to improving how we instrument code.
• Additions to the API (SpanContext extenstions, Observers, etc) should wait till the next version.

Finalized Changes

Scopes

The core motivating issue for this release was the simplification of context-propagation mechanism introduced in 0.30, and removal of reference-counting and lifecycle-management for spans.

• Scopes proposal: https://gist.github.com/tedsuo/16977473e6808773736f784b56e93d73
• Motivating issue: https://github.com/opentracing/specification/issues/80

Backwards Compatibility

The current proposal is to retain the v0.30 interfaces and related objects by moving them to the io.opentracing.v_030 namespace, and create a “shim” to allow v0.31 tracers to be wrapped in the v0.30 interface.

Repo: https://github.com/opentracing/opentracing-java-v030

Proposal: https://docs.google.com/document/d/1JIEBn0K0vQgMvyNhcJr57utizeWZ5Vf5cwmUr2GzwYc Initial compatibility PR (no shim yet): https://github.com/opentracing/opentracing-java/pull/215

Compatibility Goals

• Allow tracer implementors to support v0.30 without having to maintain both a v0.30 and a v0.31 API.
• Allow users to continue to use the v0.30 API while still consuming tracer implementation updates.
• Ideally, also allow users to progressively migrate their codebase to v0.31.

Release Process

• The new API is being developed on the 0.31.0 branch.
• Revisions should be requested as Pull Requests against this branch.
• master will continue to point at the latest patch version of the 0.30 branch, until 0.31 is officially released.
• Changes to the release candidate will be released on maven as 0.31.0.RC1, 0.31.0.RC2, etc.

Current RC snapshots

• http://search.maven.org/#artifactdetails|io.opentracing|opentracing-api|0.31.0-RC1|jar

Delayed until 0.32

Improved Binary format

The current binary format requires predetermined memory allocation, which requires a size calculation of baggage. A variable sized binary format would be preferable.

• Pull Request: https://github.com/opentracing/opentracing-java/pull/223
• Motivating issue: https://github.com/opentracing/opentracing-java/issues/95

Previous API proposals for 0.31

• Continuations: https://github.com/opentracing/opentracing-java/pull/166
• Scopes with optional Continuations: https://github.com/opentracing/opentracing-java/pull/172
• Scopes: https://github.com/opentracing/opentracing-java/pull/182
• TimeUnits: https://github.com/opentracing/opentracing-java/issues/180

[yurishkuro]

If we don’t know which way is the right way, it’s better not to force that decision via the API and let the user decide. We can always add a method with default behavior later; we can’t take one away or change its behavior.

[pavolloffay]

Who knows what default value will be in next release.

It definitely shouldn’t be changed once 1.0 is out, it would break existing code