diff --git a/README.md b/README.md index f3cf5142..47abf2fa 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java b/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java index 4cb41721..da7ed831 100644 --- a/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java +++ b/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java @@ -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)}. + * *

* The {@linkplain #register(Tracer) register} method should only be called once * during the application initialization phase.
* If the {@linkplain #register(Tracer) register} method is never called, * the default {@link NoopTracer} is used. + * + *

+ * 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 {@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());