Working toward a 1.0 release

[jkwatson]

I have created a milestone called "1.0" in the project. I have assigned all the issues/PRs to it that I think are needed. If there are additional things that are needed, please call them out in this discussion.

Here is the current set of open issues: https://github.com/open-telemetry/opentelemetry-java/issues?q=is%3Aopen+is%3Aissue+milestone%3A1.0

In addition, if there is an item there without an assignee and you are interested in working on one, please comment on the issue, or in this discussion.

Thanks!

[jkwatson]

Note: we have marked the OT and OC shim modules as alpha, so I am removing items related to them from the 1.0 milestone.

[jkwatson]

Note: as of today, the opentelemetry-bom contains the following artifact ids. Please review and make sure these are the items that we are prepared to declare as stable for a 1.0.0 release:

        <artifactId>opentelemetry-proto</artifactId>
        <artifactId>opentelemetry-api</artifactId>
        <artifactId>opentelemetry-context</artifactId>
        <artifactId>opentelemetry-exporter-jaeger</artifactId>
        <artifactId>opentelemetry-exporter-jaeger-thrift</artifactId>
        <artifactId>opentelemetry-exporter-logging</artifactId>
        <artifactId>opentelemetry-exporter-logging-otlp</artifactId>
        <artifactId>opentelemetry-exporter-zipkin</artifactId>
        <artifactId>opentelemetry-extension-annotations</artifactId>
        <artifactId>opentelemetry-extension-kotlin</artifactId>
        <artifactId>opentelemetry-extension-trace-propagators</artifactId>
        <artifactId>opentelemetry-sdk</artifactId>
        <artifactId>opentelemetry-sdk-common</artifactId>
        <artifactId>opentelemetry-sdk-testing</artifactId>
        <artifactId>opentelemetry-sdk-trace</artifactId>
        <artifactId>opentelemetry-sdk-extension-aws</artifactId>
        <artifactId>opentelemetry-sdk-extension-jaeger-remote-sampler</artifactId>
        <artifactId>opentelemetry-sdk-extension-otproto</artifactId>
        <artifactId>opentelemetry-sdk-extension-resources</artifactId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
        <artifactId>opentelemetry-exporter-otlp-trace</artifactId>

[anuraaga]

All the maintainers discussed and we have decided to target 1.0 at the end of the month with one final RC. There will be a few more breaks but we hope this is in the interest of all the users for the years to come.

Here are rough notes on what we discussed in case anyone is interested.

---

Potential fixes if another RC
This document tries to capture all potential fixes that we may be able to do if we have one more RC, and a delay of the GA for 1 or 2 weeks.

This document does not try to suggest that these changes are required, but aims to capture all possible improvements so that a decision is going to be made knowing all opportunities.

Some of the issues may still require some more discussions and thinking, but we are trying just to collect all issues that may result in breaking changes and make a decision on all of them not individually. Also all these issues are simple renames, or removing some helpers, with no new functionality or new behaviors added.

Rename of all getEmpty() to empty() based on the issue #2786
YES
Consider removing of the Baggage.toBuilder API, a decision if that is better than just documenting is still needed, but removing will still be on the table, see #2784
Make it consistent with SpanBuilder
Babbage.builder().put(...).build().makeCurrent()
Baggage.builder() static method would capture current context?
(if you don’t setNoParent)
Option: keep toBuilder() and remove setNoParent/setParent on builder
Baggage.current().toBuilder().put(...).build().makeCurrent()
YES
Fixing the put/set inconsistency, see issue #2746, except for Span.setAttribute. If it’s a bare “set”, change it to “put”
YES
Before making a decision Span.setAttribute has to also be considered part of the inconsistency, and maybe the decision could be to ignore this issue, or to change everything to set. Also we may just decide that the set attribute is very special and the only place we use set.
NO on Span.setAttribute, keeping it as is, because it’s a very stable API and because it’s not a bare “set”, and because System.setProperty()
24-hours until this decision is BAKED
Possibility of removing the getTraceIdRandomPart and make it an internal detail to the TraceIdBasedSampler, see #2785.
REMOVE (can always be added back later)
More confidence on moving some java properties out of the SDK, see #2796. This can also be done even if no other RC as the issue says, but there seem to be some reservations.
YES move resource SPI out of SDK
Separate OsResource.create() static accessor and autoconfigure SPI implementations
Remove accessor for TelemetrySdk Resource
Fix inner classes everywhere, see #2738. Or maybe not if we don’t think it makes sense even if the opportunity to break the API is on the table.
YES
Fix SpanLimits getters/setters names to confirm with latest spec changes.
NO renaming, but will add javadoc to mention corresponding spec env vars
Sub-proposal to remove MaxLengthOfAttributeValues?
YES
I would consider for TraceState.getDefault() a rename to TraceState.empty() to be consistent with baggage (worth checking if the same change can be done in other places, e.g. Attributes, Labels, etc.).
YES
Sub-proposal to remove Tracer.getDefault()
YES
TraceFlags.getDefault() - KEEP
Sub-proposal to rename TracerProvider.getDefault() to TracerProvider.noop()
YES
Rename OpenTelemetry.getPropagating(...) to OpenTelemetry.propagating(...)
YES
Double check no public static singletons exposed as fields instead of methods
Only public statics should be Semantic Attribute constants?

All decisions above are final, except for #4, which has a 24-hour grace period. No other changes allowed.

RC3 target for end of Wed

1.0 target for end of Friday, Feb 26th (Pacific Time)

[jkwatson]

oof. formatting. would be so cool if google docs had a way to export as markdown.