Merge branch 'master' into jaeger-servicespecificbatches

.github/workflows/dotnet-core-cov.yml

@@ -27,17 +27,17 @@ jobs:
     - name: Setup .NET Core 2.1
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 2.1.807
+        dotnet-version: 2.1.x
 
     - name: Setup .NET Core 3.1
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.301
+        dotnet-version: 3.1.x
 
     - name: Setup .NET 5
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: '5.0.100-rc.2.20479.15'
+        dotnet-version: '5.0.x'
 
     - name: Install dependencies
       run: dotnet restore

.github/workflows/dotnet-core-linux.yml

@@ -30,7 +30,7 @@ jobs:
     - name: Setup .NET 5
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: '5.0.100-rc.2.20479.15'
+        dotnet-version: '5.0.x'
 
     - name: Install dependencies
       run: dotnet restore

.github/workflows/dotnet-core-win.yml

@@ -20,17 +20,17 @@ jobs:
     - name: Setup .NET Core 2.1
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 2.1.807
+        dotnet-version: 2.1.x
 
     - name: Setup .NET Core 3.1
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.301
+        dotnet-version: 3.1.x
 
     - name: Setup .NET 5
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: '5.0.100-rc.2.20479.15'
+        dotnet-version: '5.0.x'
 
     - name: Install dependencies
       run: dotnet restore

.github/workflows/dotnet-core.yml

@@ -26,17 +26,17 @@ jobs:
     - name: Setup .NET Core 2.1
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 2.1.807
+        dotnet-version: 2.1.x
 
     - name: Setup .NET Core 3.1
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.301
+        dotnet-version: 3.1.x
 
     - name: Setup .NET 5
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: '5.0.100-rc.2.20479.15'
+        dotnet-version: '5.0.x'
 
     - name: Install dependencies
       run: dotnet restore

NuGet.config

@@ -3,7 +3,6 @@
   <packageSources>
     <clear />
     <add key="NuGet" value="https://api.nuget.org/v3/index.json" />
-    <!--<add key="Dotnet5" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet5/nuget/v3/index.json" />-->
   </packageSources>
   <disabledPackageSources />
 </configuration>

build/Common.props

@@ -25,12 +25,12 @@
     <GoogleProtobufPkgVer>[3.6.1,4.0)</GoogleProtobufPkgVer>
     <GrpcPkgVer>[2.23.0,3.0)</GrpcPkgVer>
     <GrpcToolsPkgVer>[2.25.0,3.0)</GrpcToolsPkgVer>
-    <MicrosoftAspNetCoreHttpAbstractionsPkgVer>[2.1.1,5.0)</MicrosoftAspNetCoreHttpAbstractionsPkgVer>
-    <MicrosoftAspNetCoreHttpFeaturesPkgVer>[2.1.1,5.0)</MicrosoftAspNetCoreHttpFeaturesPkgVer>
+    <MicrosoftAspNetCoreHttpAbstractionsPkgVer>[2.1.1,6.0)</MicrosoftAspNetCoreHttpAbstractionsPkgVer>
+    <MicrosoftAspNetCoreHttpFeaturesPkgVer>[2.1.1,6.0)</MicrosoftAspNetCoreHttpFeaturesPkgVer>
     <MicrosoftAspNetTelemetryCorrelationPkgVer>[1.0.7,2.0)</MicrosoftAspNetTelemetryCorrelationPkgVer>
     <MicrosoftCodeAnalysisAnalyzersPkgVer>[3.3.1]</MicrosoftCodeAnalysisAnalyzersPkgVer>
     <MicrosoftCodeCoveragePkgVer>[16.9.0-preview-20201020-06]</MicrosoftCodeCoveragePkgVer>
-    <MicrosoftExtensionsHostingAbstractionsPkgVer>[2.1.0,5.0)</MicrosoftExtensionsHostingAbstractionsPkgVer>
+    <MicrosoftExtensionsHostingAbstractionsPkgVer>[2.1.0,6.0)</MicrosoftExtensionsHostingAbstractionsPkgVer>
     <MicrosoftExtensionsLoggingPkgVer>[2.1.0,6.0)</MicrosoftExtensionsLoggingPkgVer>
     <MicrosoftExtensionsLoggingConfigurationPkgVer>[2.1.0,6.0)</MicrosoftExtensionsLoggingConfigurationPkgVer>
     <MicrosoftNETFrameworkReferenceAssembliesPkgVer>[1.0.0,2.0)</MicrosoftNETFrameworkReferenceAssembliesPkgVer>
@@ -39,11 +39,11 @@
     <OpenTracingPkgVer>[0.12.1,0.13)</OpenTracingPkgVer>
     <StackExchangeRedisPkgVer>[2.1.58,3.0)</StackExchangeRedisPkgVer>
     <StyleCopAnalyzersPkgVer>[1.1.118,2.0)</StyleCopAnalyzersPkgVer>
-    <SystemCollectionsImmutablePkgVer>[1.4.0,5.0]</SystemCollectionsImmutablePkgVer>
-    <SystemDiagnosticSourcePkgVer>[5.0.0-rc.2.20475.5]</SystemDiagnosticSourcePkgVer>
-    <SystemReflectionEmitLightweightPkgVer>[4.7.0,5.0)</SystemReflectionEmitLightweightPkgVer>
-    <SystemTextJsonPkgVer>[4.7.0,5.0)</SystemTextJsonPkgVer>
-    <SystemThreadingTasksExtensionsPkgVer>[4.5.3,5.0)</SystemThreadingTasksExtensionsPkgVer>
+    <SystemCollectionsImmutablePkgVer>[1.4.0,6.0)</SystemCollectionsImmutablePkgVer>
+    <SystemDiagnosticSourcePkgVer>[5.0.0,6.0)</SystemDiagnosticSourcePkgVer>
+    <SystemReflectionEmitLightweightPkgVer>[4.7.0,6.0)</SystemReflectionEmitLightweightPkgVer>
+    <SystemTextJsonPkgVer>[4.7.0,6.0)</SystemTextJsonPkgVer>
+    <SystemThreadingTasksExtensionsPkgVer>[4.5.3,6.0)</SystemThreadingTasksExtensionsPkgVer>
   </PropertyGroup>
 
   <ItemGroup>

docs/Directory.Build.props

@@ -14,7 +14,7 @@
       Please sort alphabetically.
       Refer to https://docs.microsoft.com/en-us/nuget/concepts/package-versioning for semver syntax.
     -->
-    <MicrosoftExtensionsLoggingPkgVer>[5.0.0-rc.2.20475.5,6.0)</MicrosoftExtensionsLoggingPkgVer>
+    <MicrosoftExtensionsLoggingPkgVer>[5.0.0,6.0)</MicrosoftExtensionsLoggingPkgVer>
     <OpenTelemetryExporterConsolePkgVer>[0.4.0-beta.2,1.0)</OpenTelemetryExporterConsolePkgVer>
     <OpenTelemetryPkgVer>[0.4.0-beta.2,1.0)</OpenTelemetryPkgVer>
   </PropertyGroup>

docs/trace/extending-the-sdk/README.md

@@ -60,7 +60,110 @@ Exporter to the `TracerProvider` as shown in the example [here](./Program.cs).
 
 ## Instrumentation Library
 
-TBD
+The [inspiration of the OpenTelemetry
+project](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries)
+is to make every library and application observable out of the box by having
+them call OpenTelemetry API directly. However, many libraries will not have such
+integration, and as such there is a need for a separate library which would
+inject such calls, using mechanisms such as wrapping interfaces, subscribing to
+library-specific callbacks, or translating existing telemetry into OpenTelemetry
+model.
+
+A library which enables instrumentation for another library is called
+[Instrumentation
+Library](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md#instrumentation-library)
+and the library it instruments is called the [Instrumented
+Library](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md#instrumented-library).
+If a given library has built-in instrumentation with OpenTelemetry, then
+instrumented library and instrumentation library will be the same.
+
+The [OpenTelemetry .NET Github repo](../../../README.md#getting-started) ships
+the following instrumentation libraries. The individual docs for them describes
+the library they instrument, and steps for enabling them.
+
+* [ASP.NET](../../../src/OpenTelemetry.Instrumentation.AspNet/README.md)
+* [ASP.NET Core](../../../src/OpenTelemetry.Instrumentation.AspNetCore/README.md)
+* [gRPC client](../../../src/OpenTelemetry.Instrumentation.GrpcNetClient/README.md)
+* [HTTP clients](../../../src/OpenTelemetry.Instrumentation.Http/README.md)
+* [Redis
+  client](../../../src/OpenTelemetry.Instrumentation.StackExchangeRedis/README.md)
+* [SQL client](../../../src/OpenTelemetry.Instrumentation.SqlClient/README.md)
+
+### Writing own instrumentation library
+
+This section describes the steps required to write your own instrumentation
+library.
+
+*If you are writing a new library or modifying an existing library, the
+recommendation is to use [ActivitySource API/OpenTelemetry
+API](../../../src/OpenTelemetry.Api/README.md#introduction-to-opentelemetry-net-tracing-api)
+to instrument it and emit activity/span. If the instrumented library is
+instrumented using ActivitySource API, then there is no need of writing a
+separate instrumentation library, as instrumented and instrumentation library
+become same in this case. For applications to collect traces from this library,
+all that is needed is to enable the ActivitySource for the library using
+`AddSource` method of the `TracerProviderBuilder`. The following section is
+applicable only if you are writing an instrumentation library for an
+instrumented library which you cannot modify to emit activities directly*
+
+As mentioned earlier, the instrumentation library must use ActivitySource API to
+emit activities. The mechanics of how the instrumentation library works depends
+on each library. For example, StackExchangeRedis library allows hooks into the
+library, and the [StackExchangeRedis instrumentation
+library]../../../src/OpenTelemetry.Instrumentation.StackExchangeRedis/README.md)
+in this case, leverages them, and emits Span/Activity, on behalf of the
+instrumented library. Another example is System.Data.SqlClient for .NET
+Framework, which publishes events using `EventSource`. The [SqlClient
+instrumentation
+library](../../../src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlEventSourceListener.netfx.cs),
+in this case subscribes to the `EventSource` callbacks and in turn produces
+Activity.
+
+Irrespective of the mechanics used for achieving instrumentation, the
+instrumentation library must use [ActivitySource API/OpenTelemetry
+API](../../../src/OpenTelemetry.Api/README.md#introduction-to-opentelemetry-net-tracing-api)
+to emit Activities on behalf of the instrumented library.
+
+### Instrumentation library optional requirements
+
+The instrumentation library may provide extension methods on
+`TracerProviderBuilder`, to enable the instrumentation. Providing this extension
+method is optional, and the below guidance must be followed:
+
+1. If the instrumentation library requires state management tied to that of
+   `TracerProvider`, then it must register itself with the provider with the
+   `AddInstrumentation` method on the `TracerProviderBuilder`. This causes the
+   instrumentation to be created and disposed along with `TracerProvider`. If
+   the above is required, then it must also provide an extension method on
+   `TracerProviderBuilder`. Inside this extension method, it can do the
+   `AddInstrumentation` method, and `AddSource` to enable its ActivitySource for
+   the provider. An example instrumentation using this approach is
+   [StackExchangeRedis
+   instrumentation](../../../src/OpenTelemetry.Instrumentation.StackExchangeRedis/TracerProviderBuilderExtensions.cs)
+
+2. If the instrumentation library does not requires any state management tied to
+   that of `TracerProvider`, then providing `TracerProviderBuilder` extension
+   method is optional. If provided, then it must call `AddSource` to enable its
+   ActivitySource for the provider.
+3. If instrumentation library does not require state management, and is not
+   providing extension method, then the name of the ActivitySource used by the
+   instrumented library must be documented so that end users can enable it using
+   `AddSource` API.
+
+There is a special case for libraries which are already instrumented with
+[Activity](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md),
+but using the
+[DiagnosticSource](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md)
+method. These libraries already emit activities, but it may not conform to the
+OpenTelemetry semantic conventions. Also, as these libraries do not use
+ActivitySource to create Activity, they cannot be simply enabled. For this case,
+the recommended approach is to write instrumentation library which subscribe to
+the DiagnosticSource events from the instrumented library, and in turn produce
+*new* activity using ActivitySource. This new activity must be created as a
+sibling of the activity already produced by the library. i.e the new activity
+must have the same parent as the original activity. Some common examples of such
+libraries include Asp.Net, Asp.Net Core, HttpClient (.NET Core). Instrumentation
+libraries for these are already provided in this repo.
 
 ## Processor
 

examples/Console/TestOTelShimWithConsoleExporter.cs

@@ -36,18 +36,19 @@ internal static object Run(OpenTelemetryShimOptions options)
             // which decide to use OpenTelemetry.
 
             var tracer = TracerProvider.Default.GetTracer("MyCompany.MyProduct.MyWebServer");
-            var span = tracer.StartSpan("parent span");
-            span.SetAttribute("mystring", "value");
-            span.SetAttribute("myint", 100);
-            span.SetAttribute("mydouble", 101.089);
-            span.SetAttribute("mybool", true);
-            span.UpdateName("parent span new name");
-
-            var spanChild = tracer.StartSpan("child span");
-            spanChild.AddEvent("sample event").SetAttribute("ch", "value").SetAttribute("more", "attributes");
-            spanChild.End();
-
-            span.End();
+            using (var parentSpan = tracer.StartActiveSpan("parent span"))
+            {
+                parentSpan.SetAttribute("mystring", "value");
+                parentSpan.SetAttribute("myint", 100);
+                parentSpan.SetAttribute("mydouble", 101.089);
+                parentSpan.SetAttribute("mybool", true);
+                parentSpan.UpdateName("parent span new name");
+
+                var childSpan = tracer.StartSpan("child span");
+                childSpan.AddEvent("sample event").SetAttribute("ch", "value").SetAttribute("more", "attributes");
+                childSpan.SetStatus(Status.Ok);
+                childSpan.End();
+            }
 
             System.Console.WriteLine("Press Enter key to exit.");
 

src/OpenTelemetry.Api/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* Updated System.Diagnostics.DiagnosticSource to version 5.0.0
+
 ## 0.8.0-beta.1
 
 Released 2020-Nov-5