[docs] Top-level doc showing how to initialize the OpenTelemetry SDK (#5762)

Author: CodeBlanch

OpenTelemetry.sln

@@ -124,6 +124,9 @@ EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Benchmarks", "test\Benchmarks\Benchmarks.csproj", "{DE9130A4-F30A-49D7-8834-41DE3021218B}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1}"
+	ProjectSection(SolutionItems) = preProject
+		docs\README.md = docs\README.md
+	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{2C7DD1DA-C229-4D9E-9AF0-BCD5CD3E4948}"
 	ProjectSection(SolutionItems) = preProject
@@ -132,6 +135,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{2C
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "trace", "trace", "{5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}"
+	ProjectSection(SolutionItems) = preProject
+		docs\trace\README.md = docs\trace\README.md
+	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "metrics", "metrics", "{3277B1C0-BDFE-4460-9B0D-D9A661FB48DB}"
 	ProjectSection(SolutionItems) = preProject

README.md

@@ -6,9 +6,27 @@
 [![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.svg)](https://www.nuget.org/profiles/OpenTelemetry)
 [![Build](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/ci.yml)
 
-The .NET [OpenTelemetry](https://opentelemetry.io/) client.
+The .NET [OpenTelemetry](https://opentelemetry.io/) implementation.
 
-## Supported .NET Versions
+<details>
+<summary>Table of Contents</summary>
+
+* [Supported .NET versions](#supported-net-versions)
+* [Project status](#project-status)
+* [Getting started](#getting-started)
+  * [Getting started with Logging](#getting-started-with-logging)
+  * [Getting started with Metrics](#getting-started-with-metrics)
+  * [Getting started with Tracing](#getting-started-with-tracing)
+* [Repository structure](#repository-structure)
+* [Troubleshooting](#troubleshooting)
+* [Extensibility](#extensibility)
+* [Releases](#releases)
+* [Contributing](#contributing)
+* [References](#references)
+
+</details>
+
+## Supported .NET versions
 
 Packages shipped from this repository generally support all the officially
 supported versions of [.NET](https://dotnet.microsoft.com/download/dotnet) and
@@ -17,36 +35,88 @@ older Windows-based .NET implementation), except `.NET Framework 3.5`.
 Any exceptions to this are noted in the individual `README.md`
 files.
 
-## Project Status
+## Project status
 
-**Stable** across all 3 signals i.e. `Logs`, `Metrics`, and `Traces`.
+**Stable** across all 3 signals (`Logs`, `Metrics`, and `Traces`).
 
-See [Spec Compliance
-Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md)
-to understand which portions of the specification has been implemented in this
-repo.
+> [!CAUTION]
+> Certain components, marked as
+[pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases),
+are still work in progress and can undergo breaking changes before stable
+release. Check the individual `README.md` file for each component to understand its
+current state.
 
-## Getting Started
+To understand which portions of the [OpenTelemetry
+Specification](https://github.com/open-telemetry/opentelemetry-specification)
+have been implemented in OpenTelemetry .NET see: [Spec Compliance
+Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md).
 
-If you are new here, please read the getting started docs:
+## Getting started
 
-* [Logs](./docs/logs/README.md)
-* [Metrics](./docs/metrics/README.md)
-* [Traces](./docs/trace/README.md)
+If you are new here, please read the getting started docs:
 
-This repository includes multiple installable components, available on
-[NuGet](https://www.nuget.org/profiles/OpenTelemetry). Each component has its
-individual `README.md` file, which covers the instruction on how to install and
-how to get started. To find all the available components, please take a look at
-the `src` folder.
+### Getting started with Logging
+
+If you are new to
+[logging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md),
+it is recommended to first follow the [getting started in 5 minutes - ASP.NET
+Core Application](./docs/logs/getting-started-aspnetcore/README.md) guide or
+the [getting started in 5 minutes - Console
+Application](./docs/logs/getting-started-console/README.md) guide to get up
+and running.
+
+For general information and best practices see: [OpenTelemetry .NET
+Logs](./docs/logs/README.md). For a more detailed explanation of SDK logging
+features see: [Customizing OpenTelemetry .NET SDK for
+Logs](./docs/logs/customizing-the-sdk/README.md).
+
+### Getting started with Metrics
+
+If you are new to
+[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/README.md),
+it is recommended to first follow the [getting started in 5 minutes - ASP.NET
+Core Application](./docs/metrics/getting-started-aspnetcore/README.md) guide
+or the [getting started in 5 minutes - Console
+Application](./docs/metrics/getting-started-console/README.md) guide to get
+up and running.
+
+For general information and best practices see: [OpenTelemetry .NET
+Metrics](./docs/metrics/README.md). For a more detailed explanation of SDK
+metric features see: [Customizing OpenTelemetry .NET SDK for
+Metrics](./docs/metrics/customizing-the-sdk/README.md).
+
+### Getting started with Tracing
+
+If you are new to
+[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/README.md),
+it is recommended to first follow the [getting started in 5 minutes - ASP.NET
+Core Application](./docs/trace/getting-started-aspnetcore/README.md) guide
+or the [getting started in 5 minutes - Console
+Application](./docs/trace/getting-started-console/README.md) guide to get up
+and running.
+
+For general information and best practices see: [OpenTelemetry .NET
+Traces](./docs/trace/README.md). For a more detailed explanation of SDK tracing
+features see: [Customizing OpenTelemetry .NET SDK for
+Tracing](./docs/trace/customizing-the-sdk/README.md).
+
+## Repository structure
+
+This repository includes only what is defined in the [OpenTelemetry
+Specification](https://github.com/open-telemetry/opentelemetry-specification)
+and is shipped as separate packages through
+[NuGet](https://www.nuget.org/profiles/OpenTelemetry). Each component has an
+individual `README.md` and `CHANGELOG.md` file which covers the instructions on
+how to install and get started, and details about the individual changes made
+(respectively). To find all the available components, please take a look at the
+`src` folder.
 
 Here are the most commonly used components:
 
-* [OpenTelemetry .NET API](./src/OpenTelemetry.Api/README.md)
-* [OpenTelemetry .NET SDK](./src/OpenTelemetry/README.md)
-
-[Instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library)
-can be found in [contrib repository](https://github.com/open-telemetry/opentelemetry-dotnet-contrib).
+* [OpenTelemetry API](./src/OpenTelemetry.Api/README.md)
+* [OpenTelemetry SDK](./src/OpenTelemetry/README.md)
+* [OpenTelemetry Hosting
+  Extensions](./src/OpenTelemetry.Extensions.Hosting/README.md)
 
 Here are the [exporter
 libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#exporter-library):
@@ -59,16 +129,19 @@ libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/ma
 * [Prometheus HttpListener](./src/OpenTelemetry.Exporter.Prometheus.HttpListener/README.md)
 * [Zipkin](./src/OpenTelemetry.Exporter.Zipkin/README.md)
 
-See the [OpenTelemetry
-registry](https://opentelemetry.io/ecosystem/registry/?language=dotnet) and
-[OpenTelemetry .NET Contrib
-repo](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) for more
-components.
+Additional packages including [instrumentation
+libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library),
+exporters, resource detectors, and extensions can be found in the
+[opentelemetry-dotnet-contrib
+repository](https://github.com/open-telemetry/opentelemetry-dotnet-contrib)
+and/or the [OpenTelemetry
+registry](https://opentelemetry.io/ecosystem/registry/?language=dotnet).
 
 ## Troubleshooting
 
-See [Troubleshooting](./src/OpenTelemetry/README.md#troubleshooting).
-Additionally check readme file for the individual components for any additional
+For general instructions see:
+[Troubleshooting](./src/OpenTelemetry/README.md#troubleshooting). Additionally
+`README.md` files for individual components may contain more detailed
 troubleshooting information.
 
 ## Extensibility
@@ -80,17 +153,36 @@ extension scenarios:
   library](./docs/trace/extending-the-sdk/README.md#instrumentation-library).
 * Building a custom exporter for
   [logs](./docs/logs/extending-the-sdk/README.md#exporter),
-  [metrics](./docs/metrics/extending-the-sdk/README.md#exporter) and
+  [metrics](./docs/metrics/extending-the-sdk/README.md#exporter), and
   [traces](./docs/trace/extending-the-sdk/README.md#exporter).
 * Building a custom processor for
   [logs](./docs/logs/extending-the-sdk/README.md#processor) and
   [traces](./docs/trace/extending-the-sdk/README.md#processor).
 * Building a custom sampler for
   [traces](./docs/trace/extending-the-sdk/README.md#sampler).
 
+## Releases
+
+For details about upcoming planned releases see:
+[Milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones).
+The dates and features described in issues and milestones are estimates and
+subject to change.
+
+For highlights and annoucements for stable releases see: [Release
+Notes](./RELEASENOTES.md).
+
+To access packages, source code, and/or view a list of changes for all
+components in a release see:
+[Releases](https://github.com/open-telemetry/opentelemetry-dotnet/releases).
+
+Nightly builds from this repo are published to [MyGet](https://www.myget.org),
+and can be installed using the
+`https://www.myget.org/F/opentelemetry/api/v3/index.json` source.
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+For information about contributing to the project see:
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 We meet weekly on Tuesdays, and the time of the meeting alternates between 9AM
 PT and 4PM PT. The meeting is subject to change depending on contributors'
@@ -144,23 +236,7 @@ Maintainer/Approver/Triager](https://github.com/open-telemetry/community/blob/ma
 
 [![contributors](https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-dotnet)](https://github.com/open-telemetry/opentelemetry-dotnet/graphs/contributors)
 
-## Release Schedule
-
-See the [project
-milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones)
-for details on upcoming releases. The dates and features described in issues and
-milestones are estimates, and subject to change.
-
-See the [release
-notes](https://github.com/open-telemetry/opentelemetry-dotnet/releases) for
-existing releases.
-
-> [!CAUTION]
-> Certain components, marked as
-[pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases),
-are still work in progress and can undergo breaking changes before stable
-release. Check the individual `README.md` file for each component to understand its
-current state.
+## References
 
-Daily builds from this repo are published to MyGet, and can be installed from
-[this source](https://www.myget.org/F/opentelemetry/api/v3/index.json).
+* [OpenTelemetry Project](https://opentelemetry.io/)
+* [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification)

docs/README.md

@@ -0,0 +1,134 @@
+# OpenTelemetry .NET SDK
+
+## Initialize the SDK
+
+There are two different common initialization styles supported by OpenTelemetry.
+
+### Initialize the SDK using a host
+
+Users building applications based on
+[Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting)
+should utilize the
+[OpenTelemetry.Extensions.Hosting](../src/OpenTelemetry.Extensions.Hosting/README.md)
+package to initialize OpenTelemetry. This style provides a deep integration
+between the host infrastructure (`IServiceCollection`, `IServiceProvider`,
+`IConfiguration`, etc.) and OpenTelemetry.
+
+[AspNetCore](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host)
+applications are the most common to use the hosting model but there is also a
+[Generic Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host)
+which may be used in console, service, and worker applications.
+
+> [!NOTE]
+> When using `OpenTelemetry.Extensions.Hosting` only a single pipeline will be
+> created for each configured signal (logging, metrics, and/or tracing). Users
+> who need more granular control can create additional pipelines using the
+> manual style below.
+
+First install the
+[OpenTelemetry.Extensions.Hosting](../src/OpenTelemetry.Extensions.Hosting/README.md)
+package.
+
+Second call the `AddOpenTelemetry` extension using the host
+`IServiceCollection`:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Clear the default logging providers added by the host
+builder.Logging.ClearProviders();
+
+// Initialize OpenTelemetry
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(resource => /* Resource configuration goes here */)
+    .WithLogging(logging => /* Logging configuration goes here */)
+    .WithMetrics(metrics => /* Metrics configuration goes here */)
+    .WithTracing(tracing => /* Tracing configuration goes here */));
+```
+
+> [!NOTE]
+> Calling `WithLogging` automatically registers the OpenTelemetry
+> `ILoggerProvider` and enables `ILogger` integration.
+
+### Initialize the SDK manually
+
+Users running on .NET Framework or running without a host may initialize
+OpenTelemetry manually.
+
+> [!IMPORTANT]
+> When initializing OpenTelemetry manually make sure to ALWAYS dispose the SDK
+> and/or providers when the application is shutting down. Disposing
+> OpenTelemetry gives the SDK a chance to flush any telemetry held in memory.
+> Skipping this step may result in data loss.
+
+First install the [OpenTelemetry SDK](../src/OpenTelemetry/README.md) package or
+an exporter package such as
+[OpenTelemetry.Exporter.OpenTelemetryProtocol](../src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md).
+Exporter packages typically reference the SDK and will make it available via
+transitive reference.
+
+Second use one of the following initialization APIs (depending on the SDK
+version being used):
+
+#### Using 1.10.0 or newer
+
+The `OpenTelemetrySdk.Create` API can be used to initialize all signals off a
+single root builder and supports cross-cutting extensions such as
+`ConfigureResource` which configures a `Resource` to be used by all enabled
+signals. An `OpenTelemetrySdk` instance is returned which may be used to access
+providers for each signal. Calling `Dispose` on the returned instance will
+gracefully shutdown the SDK and flush any telemetry held in memory.
+
+> [!NOTE]
+> When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and
+> `IServiceProvider` will be created for the SDK and shared by all signals. An
+> `IConfiguration` is created automatically from environment variables.
+
+```csharp
+using OpenTelemetry;
+
+var sdk = OpenTelemetrySdk.Create(builder => builder
+    .ConfigureResource(resource => /* Resource configuration goes here */)
+    .WithLogging(logging => /* Logging configuration goes here */)
+    .WithMetrics(metrics => /* Metrics configuration goes here */)
+    .WithTracing(tracing => /* Tracing configuration goes here */));
+
+// During application shutdown
+sdk.Dispose();
+```
+
+To obtain an `ILogger` instance for emitting logs when using the
+`OpenTelemetrySdk.Create` API call the `GetLoggerFactory` extension method using
+the returned `OpenTelemetrySdk` instance:
+
+```csharp
+var logger = sdk.GetLoggerFactory().CreateLogger<Program>()
+logger.LogInformation("Application started");
+```
+
+#### Using 1.9.0 or older
+
+The following shows how to create providers for each individual signal. Each
+provider is independent and must be managed and disposed explicitly. There is no
+mechanism using this style to perform cross-cutting actions across signals.
+
+```csharp
+using Microsoft.Extensions.Logging;
+using OpenTelemetry;
+
+var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    /* Tracing configuration goes here */
+    .Build();
+
+var meterProvider = Sdk.CreateMeterProviderBuilder()
+    /* Metrics configuration goes here */
+    .Build();
+
+var loggerFactory = LoggerFactory.Create(builder => builder
+    .AddOpenTelemetry(options => /* Logging configuration goes here */));
+
+// During application shutdown
+tracerProvider.Dispose();
+meterProvider.Dispose();
+loggerFactory.Dispose();
+```

src/OpenTelemetry.Api/README.md

@@ -539,4 +539,8 @@ seeing these internal logs.
 
 ## References
 
-* [OpenTelemetry Project](https://opentelemetry.io/)
+* [OpenTelemetry Baggage API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md)
+* [OpenTelemetry Logs Bridge API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md)
+* [OpenTelemetry Metrics API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md)
+* [OpenTelemetry Propagators API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md)
+* [OpenTelemetry Tracing API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md)