search

opentracing / opentracing-java

OpenTracing API for Java. 🛑 This library is DEPRECATED! https://github.com/opentracing/specification/issues/163
http://opentracing.io
Apache License 2.0
1.68k stars 344 forks source link

Docs reference outdated API #362

Open AdrianSchneble opened 4 years ago

AdrianSchneble commented 4 years ago

The "Scopes" doc references Tracer.SpanBuilder.startActiveSpan(boolean finishOnClose), which does not match the latest version of OpenTracing.

As far as I can tell, the default is now simply that every span is set as active when .started. Regardless, the docs should be changed to reflect the latest version.

This is not the only issue with the docs, there are also numerous other examples of outdated example code (in the "Scopes" doc or other sections of the docs).

I'm aware that OpenTracing is merging with OpenCensus into OpenTelemetry, but I don't think that's an "excuse" for incorrect documentation (insofar as voluntary contributors have to make "excuses").

whiskeysierra commented 4 years ago

As far as I can tell, the default is now simply that every span is set as active when .started.

That is not correct. The pattern is that span lifecycle (start/finish) is now properly separated from scope lifecycle (activate/close).

MxKaras commented 4 years ago

Given the changes, I'm trying to think under what conditions one would want to manage a scope's lifecycle. Is there any need to pay attention to it now?

whiskeysierra commented 4 years ago

Scopes are optional and users should be very interested in controlling the timeframe in which a span is active. It's not something that anyone should ignore.