.gitignore

@@ -8,7 +8,8 @@
 *.user
 *.userosscache
 *.sln.docstates
-.vscode/solution-explorer
+.vscode/
+.devcontainer/
 
 # User-specific files (MonoDevelop/Xamarin Studio)
 *.userprefs

OpenTelemetry.sln

@@ -199,6 +199,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TestApp.AspNetCore.5.0", "t
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "exception-reporting", "docs\trace\exception-reporting\exception-reporting.csproj", "{08D29501-F0A3-468F-B18D-BD1821A72383}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "customizing-the-sdk", "docs\trace\customizing-the-sdk\customizing-the-sdk.csproj", "{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -393,6 +395,10 @@ Global
 		{08D29501-F0A3-468F-B18D-BD1821A72383}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{08D29501-F0A3-468F-B18D-BD1821A72383}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{08D29501-F0A3-468F-B18D-BD1821A72383}.Release|Any CPU.Build.0 = Release|Any CPU
+		{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -423,6 +429,7 @@ Global
 		{13C10C9A-07E8-43EB-91F5-C2B116FBE0FC} = {3862190B-E2C5-418E-AFDC-DB281FB5C705}
 		{972396A8-E35B-499C-9BA1-765E9B8822E1} = {77C7929A-2EED-4AA6-8705-B5C443C8AA0F}
 		{08D29501-F0A3-468F-B18D-BD1821A72383} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
+		{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521}

README.md

@@ -2,10 +2,13 @@
 
 [![Slack](https://img.shields.io/badge/slack-@cncf/otel/dotnet-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C01N3BC2W7Q)
 [![codecov.io](https://codecov.io/gh/open-telemetry/opentelemetry-dotnet/branch/main/graphs/badge.svg?)](https://codecov.io/gh/open-telemetry/opentelemetry-dotnet/)
-[![Release](https://img.shields.io/github/v/release/open-telemetry/opentelemetry-dotnet?include_prereleases&style=)](https://github.com/open-telemetry/opentelemetry-dotnet/releases/)
-[![Nuget](https://img.shields.io/nuget/vpre/OpenTelemetry.svg)](https://www.nuget.org/profiles/OpenTelemetry)
+[![Release](https://img.shields.io/github/v/release/open-telemetry/opentelemetry-dotnet)](https://github.com/open-telemetry/opentelemetry-dotnet/releases/)
+[![Nuget](https://img.shields.io/nuget/v/OpenTelemetry.svg)](https://www.nuget.org/profiles/OpenTelemetry)
 [![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.svg)](https://www.nuget.org/profiles/OpenTelemetry)
 
+[![Windows](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/windows-ci.yml/badge.svg?branch=main)](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/windows-ci.yml)
+[![Linux](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/linux-ci.yml/badge.svg?branch=main)](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/linux-ci.yml)
+
 The .NET [OpenTelemetry](https://opentelemetry.io/) client.
 
 ## Supported .NET Versions
@@ -97,6 +100,7 @@ Approvers
 * [Eddy Nakamura](https://github.com/eddynaka), Microsoft
 * [Paulo Janotti](https://github.com/pjanotti), Splunk
 * [Reiley Yang](https://github.com/reyang), Microsoft
+* [Utkarsh Umesan Pillai](https://github.com/utpilla), Microsoft
 
 *Find more about the approver role in [community
 repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver).*

VERSIONING.md

@@ -56,9 +56,11 @@ changes. For example,
 shows the public APIs, per target framework for the
 `OpenTelemetry.Instrumentation.AspNetCore` package.
 
-Since no stable version has been released so far, every API is listed in the
-"Unshipped.txt" file. Once 1.0.0 is shipped, it'll be moved to "Shipped.txt"
-file.
+APIs which are released as part of stable packages will be listed in the
+"Shipped.txt" file, and those APIs which are released as part of
+[pre-release](#pre-releases) packages in the "Unshipped.txt". APIs will be moved
+from "Unshipped.txt" to "Shipped.txt" when the packages move from
+[pre-release](#pre-releases) to stable.
 
 ## Packaging
 

docs/logs/extending-the-sdk/MyExporter.cs

@@ -44,12 +44,21 @@ public override ExportResult Export(in Batch<LogRecord> batch)
 
             sb.Append($"{record}(");
 
+            int scopeDepth = -1;
+
             record.ForEachScope(ProcessScope, sb);
 
-            static void ProcessScope(object scope, StringBuilder builder)
-                => builder.Append($"{scope}");
+            void ProcessScope(LogRecordScope scope, StringBuilder builder)
+            {
+                if (++scopeDepth > 0)
+                {
+                    builder.Append(", ");
+                }
+
+                builder.Append($"{scope.Scope}");
+            }
 
-            sb.Append($")");
+            sb.Append(')');
         }
 
         Console.WriteLine($"{this.name}.Export([{sb.ToString()}])");

docs/trace/customizing-the-sdk/Program.cs

@@ -0,0 +1,78 @@
+// <copyright file="Program.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Diagnostics;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+public class Program
+{
+    private static readonly ActivitySource MyLibraryActivitySource = new ActivitySource(
+        "MyCompany.MyProduct.MyLibrary");
+
+    private static readonly ActivitySource ComponentAActivitySource = new ActivitySource(
+        "AbcCompany.XyzProduct.ComponentA");
+
+    private static readonly ActivitySource ComponentBActivitySource = new ActivitySource(
+        "AbcCompany.XyzProduct.ComponentB");
+
+    private static readonly ActivitySource SomeOtherActivitySource = new ActivitySource(
+        "SomeCompany.SomeProduct.SomeComponent");
+
+    public static void Main()
+    {
+        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+
+            // The following adds subscription to activities from Activity Source
+            // named "MyCompany.MyProduct.MyLibrary" only.
+            .AddSource("MyCompany.MyProduct.MyLibrary")
+
+            // The following adds subscription to activities from all Activity Sources
+            // whose name starts with "AbcCompany.XyzProduct.".
+            .AddSource("AbcCompany.XyzProduct.*")
+            .AddConsoleExporter()
+            .Build();
+
+        // This activity source is enabled.
+        using (var activity = MyLibraryActivitySource.StartActivity("SayHello"))
+        {
+            activity?.SetTag("foo", 1);
+            activity?.SetTag("bar", "Hello, World!");
+        }
+
+        // This activity source is enabled through wild card "AbcCompany.XyzProduct.*"
+        using (var activity = ComponentAActivitySource.StartActivity("SayHello"))
+        {
+            activity?.SetTag("foo", 1);
+            activity?.SetTag("bar", "Hello, World!");
+        }
+
+        // This activity source is enabled through wild card "AbcCompany.XyzProduct.*"
+        using (var activity = ComponentBActivitySource.StartActivity("SayHello"))
+        {
+            activity?.SetTag("foo", 1);
+            activity?.SetTag("bar", "Hello, World!");
+        }
+
+        // This activity source is not enabled, so activity will
+        // be null here.
+        using (var activity = SomeOtherActivitySource.StartActivity("SayHello"))
+        {
+            activity?.SetTag("foo", 1);
+            activity?.SetTag("bar", "Hello, World!");
+        }
+    }
+}

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

@@ -0,0 +1,118 @@
+# Customizing OpenTelemetry .NET SDK
+
+**This doc is work-in-progress.**
+
+## TracerProvider
+
+As shown in the [getting-started](../getting-started/README.md) doc, a valid
+[`TracerProvider`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#tracer-provider)
+must be configured and built to collect traces with OpenTelemetry .NET Sdk.
+`TracerProvider` holds all the configuration for tracing like samplers,
+processors, etc. Naturally, almost all the customizations must be done on the
+`TracerProvider`.
+
+## Building a TracerProvider
+
+Building a `TracerProvider` is done using `TracerProviderBuilder` which must be
+obtained by calling `Sdk.CreateTracerProviderBuilder()`. `TracerProviderBuilder`
+exposes various methods which configures the provider it is going to build. These
+includes methods like `SetSampler`, `AddProcessor` etc, and are explained in
+subsequent sections of this document. Once configuration is done, calling
+`Build()` on the `TracerProviderBuilder` builds the `TracerProvider` instance.
+Once built, changes to its configuration is not allowed, with the exception of
+adding more processors. In most cases, a single `TracerProvider` is created at
+the application startup, and is disposed when application shuts down.
+
+The snippet below shows how to build a basic `TracerProvider`. This will create
+a provider with default configuration, and is not particularly useful. The
+subsequent sections shows how to build a more useful provider.
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+using var tracerProvider = Sdk.CreateTracerProviderBuilder().Build();
+```
+
+## TracerProvider configuration
+
+`TracerProvider` holds the tracing configuration, which includes the following:
+
+1. The list of `ActivitySource`s (aka Tracers) from which traces are collected.
+2. The list of instrumentations enabled via
+   [InstrumentationLibrary](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library).
+3. The list of
+   [Processors](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor),
+   including exporting processors which exports traces to
+   [Exporters](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-exporter)
+4. The
+   [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)
+   associated with the traces.
+5. The
+   [Sampler](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampler)
+   to be used.
+
+### Activity Source
+
+`ActivitySource` denotes a
+[`Tracer`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer),
+which is used to start activities. The SDK follows an explicit opt-in model for
+listening to activity sources. i.e, by default, it listens to no sources. Every
+activity source which produce telemetry must be explicitly added to the tracer
+provider to start collecting traces from them.
+
+`AddSource` method on `TracerProviderBuilder` can be used to add a
+`ActivitySource` to the provider. The name of the `ActivitySource`
+(case-insensitive) must be the argument to this method. Multiple `AddSource` can
+be called to add more than one source. It also supports wild-card subscription
+model as well.
+
+It is not possible to add sources *after* the provider is built, by calling the
+`Build()` method on the `TracerProviderBuilder`.
+
+The snippet below shows how to add activity sources to the provider.
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    // The following subscribes to activities from Activity Source
+    // named "MyCompany.MyProduct.MyLibrary" only.
+    .AddSource("MyCompany.MyProduct.MyLibrary")
+    // The following subscribes to activities from all Activity Sources
+    // whose name starts with  "AbcCompany.XyzProduct.".
+    .AddSource("AbcCompany.XyzProduct.*")
+    .Build();
+```
+
+See [Program.cs](./Program.cs) for complete example.
+
+**Note**
+A common mistake while configuring `TracerProvider` is forgetting to add
+all `ActivitySources` to the provider. It is recommended to leverage the
+wild card subscription model where it makes sense. For example, if your
+application is expecting to enable tracing from a number of libraries
+from a company "Abc", the you can use `AddSource("Abc.*")` to enable
+all sources whose name starts with "Abc.".
+
+### Instrumentation
+
+// TODO
+
+### Processor
+
+// TODO
+
+### Resource
+
+// TODO
+
+### Sampler
+
+// TODO
+
+## Context Propagation
+
+// TODO: OpenTelemetry Sdk contents about Context.
+// TODO: Links to built-in instrumentations doing Propagation.

docs/trace/customizing-the-sdk/customizing-the-sdk.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <!---
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="$(OpenTelemetryExporterConsolePkgVer)" />
+    -->
+    <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
+  </ItemGroup>
+</Project>

docs/trace/getting-started/README.md

@@ -77,5 +77,7 @@ to learn more.
 
 ## Learn more
 
+* If you want to customize the Sdk, refer to [customizing
+  the SDK](../customizing-the-sdk/README.md).
 * If you want to build a custom exporter/processor/sampler, refer to [extending
   the SDK](../extending-the-sdk/README.md).

examples/AspNetCore/Controllers/WeatherForecastController.cs

@@ -20,6 +20,7 @@
 using System.Net.Http;
 using Examples.AspNetCore.Models;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Logging;
 
 namespace Examples.AspNetCore.Controllers
 {
@@ -32,23 +33,39 @@ public class WeatherForecastController : ControllerBase
             "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching",
         };
 
-        private static HttpClient httpClient = new HttpClient();
+        private static readonly HttpClient HttpClient = new HttpClient();
+
+        private readonly ILogger<WeatherForecastController> logger;
+
+        public WeatherForecastController(ILogger<WeatherForecastController> logger)
+        {
+            this.logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        }
 
         [HttpGet]
         public IEnumerable<WeatherForecast> Get()
         {
+            using var scope = this.logger.BeginScope("{Id}", Guid.NewGuid().ToString("N"));
+
             // Making an http call here to serve as an example of
             // how dependency calls will be captured and treated
             // automatically as child of incoming request.
-            var res = httpClient.GetStringAsync("http://google.com").Result;
+            var res = HttpClient.GetStringAsync("http://google.com").Result;
             var rng = new Random();
-            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
+            var forecast = Enumerable.Range(1, 5).Select(index => new WeatherForecast
             {
                 Date = DateTime.Now.AddDays(index),
                 TemperatureC = rng.Next(-20, 55),
                 Summary = Summaries[rng.Next(Summaries.Length)],
             })
             .ToArray();
+
+            this.logger.LogInformation(
+                "WeatherForecasts generated {count}: {forecasts}",
+                forecast.Length,
+                forecast);
+
+            return forecast;
         }
     }
 }