Clean up documentation of OpenTracing shim (#1637)

examples/Console/Program.cs

@@ -51,7 +51,7 @@ namespace Examples.Console
                     (ZPagesOptions options) => TestZPagesExporter.Run(),
                     (ConsoleOptions options) => TestConsoleExporter.Run(options),
                     (OpenTelemetryShimOptions options) => TestOTelShimWithConsoleExporter.Run(options),
-                    (OpenTracingShimOptions options) => TestOpenTracingWithConsoleExporter.Run(options),
+                    (OpenTracingShimOptions options) => TestOpenTracingShim.Run(options),
                     (OtlpOptions options) => TestOtlpExporter.Run(options.Endpoint),
                     errs => 1);
 

examples/Console/TestOpenTracingShim.cs

@@ -1,4 +1,4 @@
-// <copyright file="TestOpenTracingWithConsoleExporter.cs" company="OpenTelemetry Authors">
+// <copyright file="TestOpenTracingShim.cs" company="OpenTelemetry Authors">
 // Copyright The OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,7 +23,7 @@ using OpenTracing;
 
 namespace Examples.Console
 {
-    internal class TestOpenTracingWithConsoleExporter
+    internal class TestOpenTracingShim
     {
         internal static object Run(OpenTracingShimOptions options)
         {
@@ -35,13 +35,18 @@ namespace Examples.Console
                     .AddConsoleExporter()
                     .Build();
 
-            // The above line is required only in applications
-            // which decide to use OpenTelemetry.
+            // Instantiate the OpenTracing shim. The underlying OpenTelemetry tracer will create
+            // spans using the "MyCompany.MyProduct.MyWebServer" source.
+            var tracer = new TracerShim(
+                TracerProvider.Default.GetTracer("MyCompany.MyProduct.MyWebServer"),
+                Propagators.DefaultTextMapPropagator);
 
-            // Following shows how to use the OpenTracing shim
-
-            var tracer = new TracerShim(TracerProvider.Default.GetTracer("MyCompany.MyProduct.MyWebServer"), new TraceContextPropagator());
+            // Not necessary for this example, though it is best practice per
+            // the OpenTracing project to register a GlobalTracer.
+            OpenTracing.Util.GlobalTracer.Register(tracer);
 
+            // 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))
             {
                 parentScope.Span.SetTag("my", "value");

src/OpenTelemetry.Shims.OpenTracing/README.md

@@ -3,12 +3,23 @@
 [![NuGet](https://img.shields.io/nuget/v/OpenTelemetry.Shims.OpenTracing.svg)](https://www.nuget.org/packages/OpenTelemetry.Shims.OpenTracing)
 [![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.Shims.OpenTracing.svg)](https://www.nuget.org/packages/OpenTelemetry.Shims.OpenTracing)
 
+The OpenTelemetry project aims to provide backwards compatibility with the
+[OpenTracing](https://opentracing.io) project in order to ease migration of
+instrumented codebases.
+
+The OpenTracing Shim for OpenTelemetry .NET is an implementation of an
+OpenTracing Tracer providing a compatible shim on top of the OpenTelemetry API.
+
 ## Installation
 
 ```shell
 dotnet add package OpenTelemetry.Shims.OpenTracing
 ```
 
+See
+[`TestOpenTracingShim.cs`](../../examples/Console/TestOpenTracingShim.cs)
+for an example of how to use the OpenTracing shim.
+
 ## References
 
 * [OpenTelemetry Project](https://opentelemetry.io/)