Skip to content
This repository has been archived by the owner on May 23, 2023. It is now read-only.

Commit

Permalink
Repeat guidance in GlobalTracer class comments
Browse files Browse the repository at this point in the history
  • Loading branch information
bhs committed May 28, 2017
1 parent 95f29e9 commit 3d9499b
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 3 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Initialization is OpenTracing-implementation-specific. Generally speaking, the p

### Accessing the `Tracer`

Where possible, use dependency injection (of which there are many) to access the `Tracer` instance. For vanilla application code, this is often reasonable and cleaner for all of the usual DI reasons.
Where possible, use some form of dependency injection (of which there are many) to access the `Tracer` instance. For vanilla application code, this is often reasonable and cleaner for all of the usual DI reasons.

That said, instrumentation for packages that are themselves statically configured (e.g., JDBC drivers) may be unable to make use of said DI mechanisms for `Tracer` access, and as such they should fall back on [GlobalTracer](https://github.com/opentracing/opentracing-java/blob/master/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java). By and large, OpenTracing instrumentation should always allow the programmer to specify a `Tracer` instance to use for instrumentation, though the [GlobalTracer](https://github.com/opentracing/opentracing-java/blob/master/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java) is a reasonable fallback or default value.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,28 @@
import java.util.logging.Logger;

/**
* Global tracer that forwards all methods to another tracer
* that can be configured by calling {@link #register(Tracer)}.
* Global tracer that forwards all methods to another tracer that can be
* configured by calling {@link #register(Tracer)}.
*
* <p>
* The {@linkplain #register(Tracer) register} method should only be called once
* during the application initialization phase.<br>
* If the {@linkplain #register(Tracer) register} method is never called,
* the default {@link NoopTracer} is used.
*
* <p>
* Where possible, use some form of dependency injection (of which there are
* many) to access the `Tracer` instance. For vanilla application code, this is
* often reasonable and cleaner for all of the usual DI reasons.
*
* <p>
* That said, instrumentation for packages that are themselves statically
* configured (e.g., JDBC drivers) may be unable to make use of said DI
* mechanisms for {@link Tracer} access, and as such they should fall back on
* {@link GlobalTracer}. By and large, OpenTracing instrumentation should
* always allow the programmer to specify a {@link Tracer} instance to use for
* instrumentation, though the {@link GlobalTracer} is a reasonable fallback or
* default value.
*/
public final class GlobalTracer implements Tracer {
private static final Logger LOGGER = Logger.getLogger(GlobalTracer.class.getName());
Expand Down

0 comments on commit 3d9499b

Please sign in to comment.