Merge branch 'main' into alanwest/otlp-user-agent

Author: alanwest

CONTRIBUTING.md

@@ -59,8 +59,9 @@ of Windows.
 * Visual Studio 2022+ or Visual Studio Code
 * .NET Framework 4.6.2+
 
-**Note:** : Visual Studio 2022 preview is **recommended** due to projects
-targeting `.net7.0` which is in preview currently.
+> **Note**
+> Visual Studio 2022 preview is **recommended** due to projects needing
+to target .NET preview versions.
 
 ### Public API
 

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

@@ -101,7 +101,8 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder()
 
 See [Program.cs](./Program.cs) for complete example.
 
-**Note:** A common mistake while configuring `MeterProvider` is forgetting to
+> **Note**
+> A common mistake while configuring `MeterProvider` is forgetting to
 add the required `Meter`s to the provider. It is recommended to leverage the
 wildcard subscription model where it makes sense. For example, if your
 application is expecting to enable instruments from a number of libraries from a
@@ -276,7 +277,8 @@ default boundaries. This requires the use of
     })
 ```
 
-**Note:** The SDK currently does not support any changes to `Aggregation` type
+> **Note**
+> The SDK currently does not support any changes to `Aggregation` type
 by using Views.
 
 See [Program.cs](./Program.cs) for a complete example.
@@ -329,7 +331,8 @@ ignored. The SDK chooses the key/value combinations in the order in which they
 are emitted. `SetMaxMetricPointsPerMetricStream` can be used to override the
 default.
 
-**Note:**: One `MetricPoint` is reserved for every `MetricStream` for the
+> **Note**
+> One `MetricPoint` is reserved for every `MetricStream` for the
 special case where there is no key/value pair associated with the metric. The
 maximum number of `MetricPoint`s has to accommodate for this special case.
 
@@ -395,7 +398,8 @@ AnotherFruitCounter.Add(5, new("name", "banana"), new("color", "yellow")); // Ex
 AnotherFruitCounter.Add(4, new("name", "mango"), new("color", "yellow")); // Not exported
 ```
 
-**Note:** The above limit is *per* metric stream, and applies to all the metric
+> **Note**
+> The above limit is *per* metric stream, and applies to all the metric
 streams. There is no ability to apply different limits for each instrument at
 this moment.
 

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

@@ -38,7 +38,8 @@ appBuilder.Services.AddOpenTelemetry()
     .StartWithHost();
 ```
 
-**Note:** The
+> **Note**
+> The
 [StartWithHost](../../../src/OpenTelemetry.Extensions.Hosting/README.md#extension-method-reference)
 extension automatically starts and stops the `TracerProvider` with the host.
 
@@ -51,7 +52,8 @@ required.
 Call `Sdk.CreateTracerProviderBuilder()` to obtain a builder and then call
 `Build()` once configuration is done to retrieve the `TracerProvider` instance.
 
-**Note:** Once built changes to `TracerProvider` configuration are not allowed,
+> **Note**
+> Once built changes to `TracerProvider` configuration are not allowed,
 with the exception of adding more processors.
 
 In most cases a single `TracerProvider` is created at the application startup,
@@ -127,7 +129,8 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
 
 See [Program.cs](./Program.cs) for complete example.
 
-**Note:** A common mistake while configuring `TracerProvider` is forgetting to
+> **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
@@ -171,7 +174,8 @@ processor classes `SimpleExportProcessor` & `BatchExportProcessor` are provided
 to support invoking exporters through the processor pipeline and implement the
 standard behaviors prescribed by the OpenTelemetry specification.
 
-**Note:** The SDK only ever invokes processors and has no direct knowledge of
+> **Note**
+> The SDK only ever invokes processors and has no direct knowledge of
 any registered exporters.
 
 #### Processor Configuration
@@ -193,12 +197,14 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
 tracerProvider.AddProcessor(new MyProcessor3());
 ```
 
-**Note:** The order of processor registration is important. Each processor added
+> **Note**
+> The order of processor registration is important. Each processor added
 is invoked in order by the SDK. For example if a simple exporting processor is
 added before an enrichment processor the exported data will not contain anything
 added by the enrichment because it happens after the export.
-
-**Note:** A `TracerProvider` assumes ownership of **all** processors added to
+<!-- This comment is to make sure the two notes above and below are not merged -->
+> **Note**
+> A `TracerProvider` assumes ownership of **all** processors added to
 it. This means that the provider will call the `Shutdown` method on all
 registered processors when it is shutting down and call the `Dispose` method on
 all registered processors when it is disposed. If multiple providers are being
@@ -233,14 +239,15 @@ For exporting purposes, the SDK provides the following built-in processors:
   : This is an exporting processor which passes telemetry to the configured
   exporter immediately without any batching.
 
-**Note:** A special processor
+> **Note**
+> A special processor
 [CompositeProcessor&lt;T&gt;](../../../src/OpenTelemetry/CompositeProcessor.cs)
 is used by the SDK to chain multiple processors together and may be used as
 needed by users to define sub-pipelines.
-
-**Note:** The processors shipped from this SDK are generic implementations and
-support tracing and logging by implementing `Activity` and `LogRecord`
-respectively.
+<!-- This comment is to make sure the two notes above and below are not merged -->
+> **Note**
+> The processors shipped from this SDK are generic implementations and support
+tracing and logging by implementing `Activity` and `LogRecord` respectively.
 
 Follow [this](../extending-the-sdk/README.md#processor) document to learn about
 writing custom processors.
@@ -368,7 +375,8 @@ Sdk.SetDefaultTextMapPropagator(new MyCustomPropagator());
 
 ## Dependency injection support
 
-**Note:** This information applies to the OpenTelemetry SDK version 1.4.0 and
+> **Note**
+> This information applies to the OpenTelemetry SDK version 1.4.0 and
 newer only.
 
 The SDK implementation of `TracerProviderBuilder` is backed by an
@@ -412,13 +420,15 @@ When using the `Sdk.CreateTracerProviderBuilder` method the `TracerProvider`
 owns its own `IServiceCollection`. It will only be able to see services
 registered into that collection.
 
-**Note:** It is important to correctly manage the lifecycle of the
+> **Note**
+> It is important to correctly manage the lifecycle of the
 `TracerProvider`. See [Building a TracerProvider](#building-a-tracerprovider)
 for details.
 
 #### Using the OpenTelemetry.Extensions.Hosting package
 
-**Note:** If you are authoring an [ASP.NET Core
+> **Note**
+> If you are authoring an [ASP.NET Core
 application](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host)
 or using the [.NET Generic
 Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) the
@@ -447,7 +457,8 @@ which is used to automatically start the `TracerProvider` when the host starts
 and the host will automatically shutdown and dispose the `TracerProvider` when
 it is shutdown.
 
-**Note:** Multiple calls to `WithTracing` will configure the same
+> **Note**
+> Multiple calls to `WithTracing` will configure the same
 `TracerProvider`. Only a single `TraceProvider` may exist in an
 `IServiceCollection` \ `IServiceProvider`.
 
@@ -469,9 +480,11 @@ it is shutdown.
   factory function to create the processor instance.
 
 * `ConfigureServices`: Registers a callback function for configuring the
-  `IServiceCollection` used by the `TracerProviderBuilder`. **Note:**
-  `ConfigureServices` may only be called before the `IServiceProvider` has been
-  created after which point services can no longer be added.
+  `IServiceCollection` used by the `TracerProviderBuilder`.
+
+  > **Note**
+  > `ConfigureServices` may only be called before the `IServiceProvider`
+  has been created after which point services can no longer be added.
 
 * `SetSampler<T>`: Register type `T` (must derive from `Sampler`) as the sampler
   for the `TracerProvider`.
@@ -480,9 +493,19 @@ it is shutdown.
   implementationFactory)`: Adds a sampler into the `TracerProvider` using a
   factory function to create the sampler instance.
 
+> **Note**
+> The factory functions accepting `IServiceProvider` may always be used
+regardless of how the SDK is initialized. When using an external service
+collection (ex: `appBuilder.Services.AddOpenTelemetry()`), as is common in
+ASP.NET Core hosts, the `IServiceProvider` will be the instance shared and
+managed by the host. When using "Sdk.Create" functions, as is common in .NET
+Framework hosts, the provider creates its own `IServiceCollection` and will
+build an `IServiceProvider` from it to make available to extensions.
+
 ## Configuration files and environment variables
 
-**Note:** This information applies to the OpenTelemetry SDK version 1.4.0 and
+> **Note**
+> This information applies to the OpenTelemetry SDK version 1.4.0 and
 newer only.
 
 The OpenTelemetry .NET SDK integrates with the standard
@@ -546,7 +569,8 @@ variables users may also manage these settings via the command-line,
 configuration files, or any other source registered with the .NET configuration
 engine. This provides greater flexibility than what the specification defines.
 
-**Note:** Not all of the environment variables defined in the specification are
+> **Note**
+> Not all of the environment variables defined in the specification are
 supported. Consult the individual project README files for details on specific
 environment variable support.
 
@@ -580,7 +604,8 @@ environment variables.
   dotnet run --OTEL_SERVICE_NAME "MyService"
   ```
 
-**Note:** The [.NET
+> **Note**
+> The [.NET
   Configuration](https://learn.microsoft.com/dotnet/core/extensions/configuration)
   pattern is hierarchical meaning the order of registered configuration sources
   controls which value will seen by the SDK when it is defined in multiple

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

@@ -124,7 +124,8 @@ guidelines.
 This section describes the steps required to write a custom instrumentation
 library.
 
-**Note:** If you are writing a new library or modifying an existing library the
+> **Note**
+> If you are writing a new library or modifying an existing library the
 recommendation is to use the [ActivitySource API/OpenTelemetry
 API](../../../src/OpenTelemetry.Api/README.md#introduction-to-opentelemetry-net-tracing-api)
 to emit activity/span instances directly. If a library is instrumented using the
@@ -204,8 +205,11 @@ Writing an instrumentation library typically involves 3 steps.
        * If an extension is not provided, then the name of the `ActivitySource`
          used by the instrumented library must be documented so that end users
          can enable it by calling `AddSource` on the `TracerProviderBuilder`
-         being configured. **Note:** Changing the name of the source should be
-         considered a breaking change.
+         being configured.
+
+         > **Note**
+         > Changing the name of the source should be considered a
+         breaking change.
 
 ### Special case : Instrumentation for libraries producing legacy Activity
 
@@ -354,15 +358,17 @@ A demo ResourceDetector is shown [here](./MyResourceDetector.cs).
 
 ## Registration extension method guidance for library authors
 
-**Note:** This information applies to the OpenTelemetry SDK version 1.4.0 and
+> **Note**
+> This information applies to the OpenTelemetry SDK version 1.4.0 and
 newer only.
 
 Library authors are encouraged to provide extension methods users may call to
 register custom OpenTelemetry components into their `TracerProvider`s. These
 extension methods can target either the `TracerProviderBuilder` or the
 `IServiceCollection` classes. Both of these patterns are described below.
 
-**Note:** Libraries providing SDK plugins such as exporters, resource detectors,
+> **Note**
+> Libraries providing SDK plugins such as exporters, resource detectors,
 and/or samplers should take a dependency on the [OpenTelemetry SDK
 package](https://www.nuget.org/packages/opentelemetry). Library authors
 providing instrumentation should take a dependency on `OpenTelemetry.Api` or
@@ -397,7 +403,8 @@ When providing registration extensions:
   from starting. The OpenTelemetry SDK is allowed to crash if it cannot be
   started. It **MUST NOT** crash once running.
 
-**Note:** The SDK implementation of `TracerProviderBuilder` ensures that the
+> **Note**
+> The SDK implementation of `TracerProviderBuilder` ensures that the
 [.NET
 Configuration](https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration)
 engine is always available by creating a root `IConfiguration` from environment
@@ -625,7 +632,8 @@ single `AddMyLibrary` extension to configure the library itself and optionally
 turn on OpenTelemetry integration for multiple signals (tracing & metrics in
 this case).
 
-**Note:** `ConfigureOpenTelemetryTracerProvider` and
+> **Note**
+> `ConfigureOpenTelemetryTracerProvider` and
 `ConfigureOpenTelemetryMeterProvider` do not automatically start OpenTelemetry.
 The host is responsible for either calling `StartWithHost` in the
 [OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md)

docs/trace/reporting-exceptions/README.md

@@ -142,7 +142,8 @@ It might be useful to automatically capture the unhandled exceptions, travel
 through the unfinished activities and export them for troubleshooting. Here goes
 one possible way of doing this:
 
-**WARNING:** Use `AppDomain.UnhandledException` with caution. A throw in the
+> **Warning**
+> Use `AppDomain.UnhandledException` with caution. A throw in the
 handler puts the process into an unrecoverable state.
 
 ```csharp

src/OpenTelemetry.Api/README.md

@@ -488,7 +488,8 @@ Windows-based .NET implementation).
 
     The above requires import of the `System.Diagnostics.Metrics` namespace.
 
-    **Note:** It is important to note that `Meter` instances are created by
+    > **Note**
+    > It is important to note that `Meter` instances are created by
     using its constructor, and *not* by calling a `GetMeter` method on the
     `MeterProvider`. This is an important distinction from the [OpenTelemetry
     specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter),

src/OpenTelemetry.Exporter.Console/README.md

@@ -6,7 +6,8 @@
 The console exporter prints data to the Console window.
 ConsoleExporter supports exporting logs, metrics and traces.
 
-**Note:** this exporter is intended to be used during learning how telemetry
+> **Note**
+> This exporter is intended to be used during learning how telemetry
 data are created and exported. It is not recommended for any production
 environment.
 

src/OpenTelemetry.Extensions.Hosting/README.md

@@ -32,11 +32,13 @@ Targeting `OpenTelemetry.OpenTelemetryBuilder`:
 
 ### Obsolete OpenTelemetry SDK pre-1.4.0 extensions
 
-**Note:** The below extension methods should be called by application host code
+> **Note**
+> The below extension methods should be called by application host code
 only. Library authors see: [Registration extension method guidance for library
 authors](../../docs/trace/extending-the-sdk/README.md#registration-extension-method-guidance-for-library-authors).
-
-**Note:** Multiple calls to the below extensions will **NOT** result in multiple
+<!-- This comment is to make sure the two notes above and below are not merged -->
+> **Note**
+> Multiple calls to the below extensions will **NOT** result in multiple
 providers. To establish multiple providers use the
 `Sdk.CreateTracerProviderBuilder()` and/or `Sdk.CreateMeterProviderBuilder()`
 methods. See [TracerProvider