Improve comments on the OpenTracing example (#4730)

examples/Console/TestOpenTracingShim.cs

@@ -37,23 +37,29 @@ internal static object Run(OpenTracingShimOptions options)
 
         // Instantiate the OpenTracing shim. The underlying OpenTelemetry tracer will create
         // spans using the "MyCompany.MyProduct.MyWebServer" source.
-        var tracer = new TracerShim(
+        var openTracingTracerShim = new TracerShim(
             TracerProvider.Default.GetTracer("MyCompany.MyProduct.MyWebServer"),
             Propagators.DefaultTextMapPropagator);
 
-        // Not necessary for this example, though it is best practice per
-        // the OpenTracing project to register a GlobalTracer.
-        OpenTracing.Util.GlobalTracer.Register(tracer);
+        // The OpenTracing Tracer shim instance must be registered prior to any calls
+        // to GlobalTracer.Instance, otherwise GlobalTracer.Instance will register a NoopTracer
+        // preventing sampling of any OpenTracing spans.
+        OpenTracing.Util.GlobalTracer.Register(openTracingTracerShim);
+
+        // The code ahead could just use the OpenTracing Tracer shim instance directly.
+        // However, an instrumentation using OpenTracing API will use the GlobalTracer.Instance
+        // to create spans.
+        var openTracingTracer = OpenTracing.Util.GlobalTracer.Instance;
 
         // The code below is meant to resemble application code that has been instrumented
         // with the OpenTracing API.
-        using (IScope parentScope = tracer.BuildSpan("Parent").StartActive(finishSpanOnDispose: true))
+        using (IScope parentScope = openTracingTracer.BuildSpan("Parent").StartActive(finishSpanOnDispose: true))
         {
             parentScope.Span.SetTag("my", "value");
             parentScope.Span.SetOperationName("parent span new name");
 
             // The child scope will automatically use parentScope as its parent.
-            using IScope childScope = tracer.BuildSpan("Child").StartActive(finishSpanOnDispose: true);
+            using IScope childScope = openTracingTracer.BuildSpan("Child").StartActive(finishSpanOnDispose: true);
             childScope.Span.SetTag("Child Tag", "Child Tag Value").SetTag("ch", "value").SetTag("more", "attributes");
         }