[docs] Top-level doc showing how to initialize the OpenTelemetry SDK

OpenTelemetry.sln

@@ -123,6 +123,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

docs/README.md

@@ -0,0 +1,134 @@
+# Getting started with OpenTelemetry
+
+## 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/README.md

@@ -5,9 +5,11 @@
 
 * [Installation](#installation)
 * [Introduction](#introduction)
-* [Getting started with Logging](#getting-started-with-logging)
-* [Getting started with Metrics](#getting-started-with-metrics)
-* [Getting started with Tracing](#getting-started-with-tracing)
+* [Getting started](#getting-started)
+  * [Getting started with Logging](#getting-started-with-logging)
+    * [ILogger integration](#ilogger-integration)
+  * [Getting started with Metrics](#getting-started-with-metrics)
+  * [Getting started with Tracing](#getting-started-with-tracing)
 * [Troubleshooting](#troubleshooting)
   * [Configuration Parameters](#configuration-parameters)
   * [Remarks](#remarks)
@@ -22,52 +24,62 @@ dotnet add package OpenTelemetry
 ## Introduction
 
 OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It
-implements the Tracing API, the Metrics API, and the Context API.  Once a valid
-SDK is installed and configured, all the OpenTelemetry API methods, which were
-no-ops without an SDK, will start emitting telemetry.
-This SDK also supports [ILogger](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger)
-integration.
+implements the Logging API, Metrics API, Tracing API, Resource API, and the
+Context API. Once a valid SDK is installed and configured all the OpenTelemetry
+API methods, which were no-ops without an SDK, will start emitting telemetry.
+This SDK also ships with an [ILogger integration](#ilogger-integration).
 
-The SDK deals with concerns such as sampling, processing pipeline, exporting
-telemetry to a particular backend etc. In most cases, users indirectly install
-and enable the SDK, when they install a particular exporter.
+The SDK deals with concerns such as sampling, processing pipelines (exporting
+telemetry to a particular backend, etc.), metrics aggregation, and other
+concerns outlined in the [OpenTelemetry
+Specification](https://github.com/open-telemetry/opentelemetry-specification).
+In most cases, users indirectly install and enable the SDK when they install an
+exporter.
 
-## Getting started with Logging
+## Getting started
 
-If you are new to logging, it is recommended to first follow the [getting
-started in 5 minutes - Console
+For general information about how to initialize the OpenTelemetry SDK see
+[getting started](../../docs//README.md).
+
+### 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.
 
-While [OpenTelemetry
-logging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md)
-specification is an experimental signal, `ILogger` is the de-facto logging API
-provided by the .NET runtime and is a stable API recommended for production use.
-This repo ships an OpenTelemetry
-[provider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers),
-which provides the ability to enrich logs emitted with `ILogger` with
-`ActivityContext`, and export them to multiple destinations, similar to tracing.
-`ILogger` based API will become the OpenTelemetry .NET implementation of
-OpenTelemetry logging.
+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
+#### ILogger integration
+
+This repo ships an
+[ILoggerProvider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers)
+implementation which automatically enriches logs emitted using
+[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging) with trace
+correlation information (`ActivityContext`).
+
+### Getting started with Metrics
 
 If you are new to
-[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md),
+[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.
+Application](../../docs/metrics/getting-started-console/README.md) guide to get
+up and running.
 
 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
+### Getting started with Tracing
 
 If you are new to
-[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md),
+[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