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

Deferring Asynchronous Work example from README does not match with example #258

Open wsargent opened 6 years ago

wsargent commented 6 years ago

In https://github.com/opentracing/opentracing-java/blob/master/README.md#deferring-asynchronous-work

The example has 3 steps:

  1. Start a Span via either startManual or startActive(false) to prevent the Span from being finished upon Scope deactivation.
  2. In the closure/Runnable/Future/etc itself, invoke tracer.scopeManager().activate(span, false) to re-activate the Span and get a new Scope, then deactivate() it when the Span is no longer active (or use try-with-resources for less typing).
  3. In the closure/Runnable/Future/etc where the end of the task is reached, invoke tracer.scopeManager().activate(span, true) to re-activate the Span and have the new Scope close the Span automatically.

However, the code sample has only two steps:

io.opentracing.Tracer tracer = ...;
...
// STEP 1 ABOVE: start the Scope/Span
try (Scope scope = tracer.buildSpan("ServiceHandlerSpan").startActive(false)) {
    ...
    final Span span = scope.span();
    doAsyncWork(new Runnable() {
        @Override
        public void run() {

            // STEP 2 ABOVE: reactivate the Span in the callback, passing true to
            // startActive() if/when the Span must be finished.
            try (Scope scope = tracer.scopeManager().activate(span, false)) {
                ...
            }
        }
    });
}

Since tracer.scopeManager().activate(span, true) is never called here, either the code sample or the text should be updated.