@azure/mcp-linux-arm64 2.0.0-beta.27 → 2.0.0-beta.28

package/dist/Resources/api-reference/dotnet/SdkCreateTracerProviderBuilder.md

@@ -0,0 +1,127 @@
+---
+title: SdkCreateTracerProviderBuilder
+category: api-reference
+applies-to: 3.x
+---
+
+# Sdk.CreateTracerProviderBuilder / Sdk.CreateMeterProviderBuilder
+
+> [!WARNING]
+> **Legacy pattern (<= 1.9.0).** These APIs still work but are no longer the
+> recommended path. For new code, prefer
+> Unified Multi-Signal (`OpenTelemetrySdk.Create`)(see in OpenTelemetrySdkCreate.md) (non-hosted) or
+> Host & DI-Integrated (`AddOpenTelemetry`)(see in AddOpenTelemetry.md) (hosted).
+
+## When to use
+
+- Codebases targeting OpenTelemetry .NET SDK **< 1.10.0**.
+- **Single-signal** scenarios (e.g., only tracing in a unit test).
+- Quick benchmarks or throwaway scripts where minimal setup is preferred.
+
+## Minimal example - tracing only
+
+```csharp
+using System.Diagnostics;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+// 1. Define an ActivitySource
+var activitySource = new ActivitySource("MyApp");
+
+// 2. Build a TracerProvider
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSource("MyApp")
+    .ConfigureResource(r => r.AddService("my-service"))
+    .AddConsoleExporter()
+    .Build();
+
+// 3. Create spans
+using (var activity = activitySource.StartActivity("DoWork"))
+{
+    activity?.SetTag("result", "ok");
+}
+// TracerProvider.Dispose() is called by `using`, which flushes buffered spans.
+```
+
+## Multi-signal example
+
+Each signal requires its own builder and its own `Dispose()` call:
+
+```csharp
+using System.Diagnostics;
+using System.Diagnostics.Metrics;
+using Microsoft.Extensions.Logging;
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Trace;
+
+// Tracing
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSource("MyApp")
+    .AddConsoleExporter()
+    .Build();
+
+// Metrics
+using var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .AddMeter("MyApp")
+    .AddConsoleExporter()
+    .Build();
+
+// Logging (uses ILoggerFactory, not a provider builder)
+using var loggerFactory = LoggerFactory.Create(builder => builder
+    .AddOpenTelemetry(options => options.AddConsoleExporter()));
+
+var logger = loggerFactory.CreateLogger<Program>();
+logger.LogInformation("Application started");
+```
+
+> [!NOTE]
+> Compare the above with
+> Unified Multi-Signal (`OpenTelemetrySdk.Create`)(see in OpenTelemetrySdkCreate.md), which achieves
+> the same result with a single builder and a single `Dispose()`.
+
+## API surface
+
+### TracerProviderBuilder
+
+| Method | Purpose |
+| --- | --- |
+| `.AddSource(params string[] names)` | Subscribe to `ActivitySource` names |
+| `.AddProcessor(BaseProcessor<Activity>)` | Add a span processor |
+| `.SetSampler(Sampler)` | Set the sampling strategy |
+| `.ConfigureResource(Action<ResourceBuilder>)` | Attach resource attributes |
+| `.AddConsoleExporter()` | Export spans to stdout |
+| `.AddOtlpExporter()` | Export spans via OTLP |
+| `.Build()` | Returns a `TracerProvider` |
+
+### MeterProviderBuilder
+
+| Method | Purpose |
+| --- | --- |
+| `.AddMeter(params string[] names)` | Subscribe to `Meter` names |
+| `.AddView(...)` | Configure metric views |
+| `.SetExemplarFilter(ExemplarFilterType)` | Control exemplar collection |
+| `.ConfigureResource(Action<ResourceBuilder>)` | Attach resource attributes |
+| `.AddConsoleExporter()` | Export metrics to stdout |
+| `.AddOtlpExporter()` | Export metrics via OTLP |
+| `.Build()` | Returns a `MeterProvider` |
+
+## Lifecycle
+
+- **Caller owns disposal.** You must call `Dispose()` (or use `using`) on each
+  provider to flush pending telemetry and release resources.
+- Each provider is **independent** - disposing one does not affect the others.
+- In a typical app, create providers at startup and dispose at shutdown.
+
+## Why this pattern is considered legacy
+
+1. **Verbose for multi-signal apps.** Three builders, three disposals, three
+   independent resource configurations.
+2. **No shared `IServiceProvider`.** Processors and exporters that need
+   dependency injection must be constructed manually.
+3. **No unified lifecycle.** Each signal must be coordinated separately.
+
+`OpenTelemetrySdk.Create()` (>= 1.10.0) resolves all three issues while staying
+host-free.
+

package/dist/Resources/api-reference/dotnet/UseAzureMonitor.md

@@ -0,0 +1,96 @@
+---
+title: UseAzureMonitor
+category: api-reference
+applies-to: 3.x
+source: Azure.Monitor.OpenTelemetry.AspNetCore/OpenTelemetryBuilderExtensions.cs
+---
+
+# UseAzureMonitor
+
+**Namespace:** `Azure.Monitor.OpenTelemetry.AspNetCore`
+
+## Overview
+
+Extension method on `IOpenTelemetryBuilder` that configures OpenTelemetry with Azure Monitor exporters and automatic instrumentation.
+
+## Signature
+
+```csharp
+public static IOpenTelemetryBuilder UseAzureMonitor(
+    this IOpenTelemetryBuilder builder);
+
+public static IOpenTelemetryBuilder UseAzureMonitor(
+    this IOpenTelemetryBuilder builder,
+    Action<AzureMonitorOptions> configureAzureMonitor);
+```
+
+## Usage
+
+### Basic (environment variable connection string)
+
+```csharp
+using Azure.Monitor.OpenTelemetry.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddOpenTelemetry().UseAzureMonitor();
+```
+
+### With options
+
+```csharp
+using Azure.Monitor.OpenTelemetry.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
+{
+    options.ConnectionString = "InstrumentationKey=...";
+    options.SamplingRatio = 0.5f;
+});
+```
+
+## AzureMonitorOptions Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ConnectionString` | `string?` | Azure Monitor connection string. If not set, reads from `APPLICATIONINSIGHTS_CONNECTION_STRING` env var |
+| `SamplingRatio` | `float` | Sampling ratio (0.0 to 1.0). Default: 1.0 (100%) |
+| `EnableLiveMetrics` | `bool` | Enable Live Metrics stream. Default: true |
+| `Credential` | `TokenCredential?` | Azure credential for AAD authentication |
+| `Resource` | `Resource?` | Custom OpenTelemetry resource |
+
+## What It Configures
+
+Calling `UseAzureMonitor()` automatically adds:
+
+**Tracing:**
+- ASP.NET Core instrumentation
+- HttpClient instrumentation
+- SQL Client instrumentation
+- Azure SDK instrumentation
+- Azure Monitor trace exporter
+
+**Metrics:**
+- ASP.NET Core instrumentation
+- HttpClient instrumentation
+- Runtime instrumentation
+- Azure Monitor metric exporter
+
+**Logging:**
+- Azure Monitor log exporter
+
+## Chaining with Additional Configuration
+
+```csharp
+builder.Services.AddOpenTelemetry()
+    .UseAzureMonitor()
+    .WithTracing(tracing => tracing
+        .AddSource("MyCustomSource")
+        .AddProcessor<MyCustomProcessor>())
+    .WithMetrics(metrics => metrics
+        .AddMeter("MyCustomMeter"));
+```
+
+## See Also
+
+- AddOpenTelemetry(see in AddOpenTelemetry.md)
+- Azure Monitor Distro concept(see in azure-monitor-distro.md)

package/dist/Resources/api-reference/dotnet/UseAzureMonitorExporter.md

@@ -0,0 +1,146 @@
+---
+title: UseAzureMonitorExporter
+category: api-reference
+applies-to: 3.x
+source: src/OpenTelemetryBuilderExtensions.cs
+---
+
+# UseAzureMonitorExporter
+
+**Namespace:** `Azure.Monitor.OpenTelemetry.Exporter`
+
+## When to use
+
+- You want Azure Monitor export **without** the automatic instrumentation that `UseAzureMonitor` (distro) adds.
+- You want a single call that registers exporters for **all three signals** (traces, metrics, logs).
+- You want **Live Metrics** support (per-signal methods do not support it).
+- You are adding Azure Monitor to a pipeline that already calls `AddOpenTelemetry()` with custom providers.
+
+## Signatures
+
+```csharp
+public static IOpenTelemetryBuilder UseAzureMonitorExporter(
+    this IOpenTelemetryBuilder builder);
+
+public static IOpenTelemetryBuilder UseAzureMonitorExporter(
+    this IOpenTelemetryBuilder builder,
+    Action<AzureMonitorExporterOptions> configureAzureMonitor);
+```
+
+Automatically calls `WithTracing()`, `WithMetrics()`, and `WithLogging()`.
+Sets the sampler, configures `IncludeFormattedMessage = true` on the logger,
+and enables Live Metrics.
+
+## Behavior notes
+
+- **Cannot** be combined with per-signal methods (`AddAzureMonitorTraceExporter`, etc.) in the same app — a runtime exception is thrown.
+- Chaining additional `WithTracing()` / `WithMetrics()` / `WithLogging()` calls adds configuration to the existing provider — it does not create a second one.
+- See AzureMonitorExporter(see in AzureMonitorExporter.md) for the per-signal approach.
+
+## AzureMonitorExporterOptions
+
+Inherits `Azure.Core.ClientOptions`.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `ConnectionString` | `string` | `null` | Application Insights connection string. Falls back to `APPLICATIONINSIGHTS_CONNECTION_STRING` env var. |
+| `Credential` | `TokenCredential` | `null` | Azure AD token credential for Entra-based auth. |
+| `SamplingRatio` | `float` | `1.0F` | Fixed-percentage sampling ratio (0.0–1.0). Only used when `TracesPerSecond` is `null`. |
+| `TracesPerSecond` | `double?` | `5.0` | Rate-limited sampling target. Takes precedence over `SamplingRatio`. Set to `null` to use fixed-percentage sampling. |
+| `StorageDirectory` | `string` | `null` | Custom directory for offline/retry storage. Uses OS temp by default. |
+| `DisableOfflineStorage` | `bool` | `false` | Disables persistent storage for failed telemetry. |
+| `EnableLiveMetrics` | `bool` | `true` | Enables Live Metrics stream. |
+| `EnableTraceBasedLogsSampler` | `bool` | `true` | When `true`, only logs correlated to sampled traces are exported. Logs without trace context are always exported. |
+
+## Sampling
+
+The exporter automatically configures a trace sampler — you do not need to set one yourself.
+
+**Two modes**, controlled by `TracesPerSecond` and `SamplingRatio`:
+
+| Mode | Activated when | Sampler | Example |
+|---|---|---|---|
+| Rate-limited (default) | `TracesPerSecond` is non-null | `RateLimitedSampler` — caps throughput to N traces/sec | `TracesPerSecond = 5.0` → ~5 traces/sec |
+| Fixed-percentage | `TracesPerSecond` is `null` | `ApplicationInsightsSampler` — samples a fixed ratio | `SamplingRatio = 0.4F` → 40% of traces |
+
+Because `TracesPerSecond` defaults to `5.0`, rate-limited sampling is active out of the box. To switch to fixed-percentage sampling:
+
+```csharp
+builder.Services.AddOpenTelemetry()
+    .UseAzureMonitorExporter(o =>
+    {
+        o.TracesPerSecond = null;   // disable rate-limited sampling
+        o.SamplingRatio = 0.25F;   // keep 25% of traces
+    });
+```
+
+**Environment variable overrides** — `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`:
+
+| `OTEL_TRACES_SAMPLER` | `OTEL_TRACES_SAMPLER_ARG` | Effect |
+|---|---|---|
+| `microsoft.rate_limited` | `5` | `TracesPerSecond = 5.0` |
+| `microsoft.fixed_percentage` | `0.4` | `SamplingRatio = 0.4F`, `TracesPerSecond = null` |
+
+Environment variables override `IConfiguration` values, which override code defaults.
+
+**Log sampling** — when `EnableTraceBasedLogsSampler` is `true` (default), logs correlated to a sampled-out trace are also dropped. Logs without trace context are always exported.
+
+## Minimal example
+
+```csharp
+using Azure.Monitor.OpenTelemetry.Exporter;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Connection string from APPLICATIONINSIGHTS_CONNECTION_STRING env var
+builder.Services.AddOpenTelemetry().UseAzureMonitorExporter();
+
+var app = builder.Build();
+app.Run();
+```
+
+## Full example
+
+```csharp
+using Azure.Identity;
+using Azure.Monitor.OpenTelemetry.Exporter;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .UseAzureMonitorExporter(o =>
+    {
+        o.ConnectionString = builder.Configuration["AzureMonitor:ConnectionString"];
+        o.Credential = new DefaultAzureCredential();
+        o.TracesPerSecond = null;              // switch to fixed-percentage sampling
+        o.SamplingRatio = 0.5F;               // keep 50% of traces
+        o.EnableTraceBasedLogsSampler = false; // export all logs
+    })
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .AddSource("MyApp"));
+
+var app = builder.Build();
+app.Run();
+```
+
+### Non-hosted (console / CLI)
+
+```csharp
+using Azure.Monitor.OpenTelemetry.Exporter;
+using OpenTelemetry;
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .UseAzureMonitorExporter()
+    .WithTracing(tracing => tracing.AddSource("MyApp")));
+
+// sdk.Dispose() flushes all signals on exit.
+```
+
+## See also
+
+- UseAzureMonitor (distro)(see in UseAzureMonitor.md)
+- Per-signal exporters (AzureMonitorExporter)(see in AzureMonitorExporter.md)
+- AddOpenTelemetry(see in AddOpenTelemetry.md)

package/dist/Resources/api-reference/dotnet/WithLogging.md

@@ -0,0 +1,109 @@
+---
+title: WithLogging
+category: api-reference
+applies-to: 1.x
+---
+
+# .WithLogging()
+
+## API surface
+
+| Method | Purpose |
+| --- | --- |
+| `.WithLogging()` | Enable logging with defaults |
+| `.WithLogging(Action<LoggerProviderBuilder>)` | Enable logging and configure the provider builder |
+| `.WithLogging(Action<LoggerProviderBuilder>?, Action<OpenTelemetryLoggerOptions>?)` | Configure both provider and logger options |
+| `ILoggingBuilder.AddOpenTelemetry()` | Register OpenTelemetry logger without the host builder |
+| `ILoggingBuilder.AddOpenTelemetry(Action<OpenTelemetryLoggerOptions>?)` | Register with options configuration |
+| `builder.AddProcessor(BaseProcessor<LogRecord>)` | Add a log processor instance |
+| `builder.AddProcessor<T>()` | Add a processor resolved from DI (singleton) |
+| `builder.AddProcessor(Func<IServiceProvider, BaseProcessor<LogRecord>>)` | Add a processor via factory |
+
+See also: ConfigureResource.md for resource configuration
+
+## When to use
+
+- Route `ILogger` log records through the OpenTelemetry pipeline in an ASP.NET Core or Worker Service app.
+- Configure `OpenTelemetryLoggerOptions` (formatted messages, scopes, state parsing) alongside the provider.
+- Use `AddOpenTelemetry()` on `ILoggingBuilder` when you need logging without the full `AddOpenTelemetry()` builder (e.g., non-host `ServiceCollection`).
+- Call multiple times safely — only one `LoggerProvider` is created per `IServiceCollection`.
+
+## Minimal example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .WithLogging(logging => logging
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Full example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Resources;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService("order-api"))
+    .WithLogging(
+        configureBuilder: logging => logging
+            .AddProcessor<MyLogEnrichmentProcessor>()
+            .AddOtlpExporter(),
+        configureOptions: options =>
+        {
+            options.IncludeFormattedMessage = true;
+            options.IncludeScopes = true;
+            options.ParseStateValues = true;
+        });
+
+var app = builder.Build();
+app.Run();
+```
+
+### Alternative: ILoggingBuilder.AddOpenTelemetry()
+
+Use this when you don't have an `IOpenTelemetryBuilder` — for example, a bare `ServiceCollection`:
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using OpenTelemetry.Logs;
+
+var services = new ServiceCollection();
+
+services.AddLogging(logging => logging
+    .AddOpenTelemetry(options =>
+    {
+        options.IncludeFormattedMessage = true;
+    }));
+```
+
+## Key parameters
+
+`OpenTelemetryLoggerOptions` properties:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `IncludeFormattedMessage` | `bool` | `false` | Include the formatted log message on `LogRecord` |
+| `IncludeScopes` | `bool` | `false` | Include log scopes on `LogRecord` |
+| `ParseStateValues` | `bool` | `false` | Parse state into `LogRecord.Attributes` (sets `State` to `null`) |
+
+## Behavior notes
+
+- `WithLogging()` automatically registers an `ILoggerProvider` named `"OpenTelemetry"`.
+- `AddOpenTelemetry()` on `ILoggingBuilder` does **not** support all `IServiceCollection` features available to tracing/metrics (e.g., `ConfigureServices` extensions).
+- When `IncludeFormattedMessage` is `false`, the formatted message is still included if no message template is found.
+- When `ParseStateValues` is `true`, `LogRecord.State` is always `null` — use `LogRecord.Attributes` instead.
+- State parsing happens automatically (regardless of `ParseStateValues`) if the logged state implements `IReadOnlyList<KeyValuePair<string, object>>`.
+- Processors run in registration order. Export processors should be added last.
+- `OpenTelemetryLoggerOptions` reloading is disabled internally to prevent unwanted re-creation of processors/exporters during `IConfiguration` reloads.

package/dist/Resources/api-reference/dotnet/WithMetrics.md

@@ -0,0 +1,105 @@
+---
+title: WithMetrics
+category: api-reference
+applies-to: 1.x
+---
+
+# .WithMetrics()
+
+## API surface
+
+| Method | Purpose |
+| --- | --- |
+| `.WithMetrics()` | Enable metrics with no additional configuration |
+| `.WithMetrics(Action<MeterProviderBuilder>)` | Enable metrics and configure the `MeterProviderBuilder` |
+| `builder.AddMeter(params string[] names)` | Subscribe to one or more `Meter` names |
+| `builder.AddReader(MetricReader)` | Add a metric reader instance |
+| `builder.AddReader<T>()` | Add a reader resolved from DI (registered as singleton) |
+| `builder.AddReader(Func<IServiceProvider, MetricReader>)` | Add a reader via factory |
+| `builder.AddView(string instrumentName, string name)` | Rename a metric stream (no wildcards) |
+| `builder.AddView(string instrumentName, MetricStreamConfiguration)` | Customize aggregation for an instrument (wildcards allowed) |
+| `builder.AddView(Func<Instrument, MetricStreamConfiguration?>)` | Programmatic view selection |
+| `builder.SetMaxMetricStreams(int)` | Set max metric streams (default: 1000) |
+| `builder.SetExemplarFilter(ExemplarFilterType)` | Set exemplar filter (`AlwaysOff`, `AlwaysOn`, `TraceBased`) |
+
+See also: ConfigureResource.md for resource configuration
+
+## When to use
+
+- Enable metrics collection in an ASP.NET Core or Worker Service app via `AddOpenTelemetry()`.
+- Enable metrics in a standalone/console app via `OpenTelemetrySdk.Create()`.
+- Subscribe to `Meter` names from your application code or instrumentation libraries.
+- Configure views to customize aggregation, rename streams, or set cardinality limits.
+- Call multiple times safely — only one `MeterProvider` is created per `IServiceCollection`.
+
+## Minimal example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Metrics;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .WithMetrics(metrics => metrics
+        .AddMeter("MyApp")
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Full example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Resources;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService("order-api"))
+    .WithMetrics(metrics => metrics
+        .AddMeter("OrderService", "PaymentService")
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .AddView("request-duration", new ExplicitBucketHistogramConfiguration
+        {
+            Boundaries = new double[] { 0.01, 0.05, 0.1, 0.5, 1, 5, 10 }
+        })
+        .SetMaxMetricStreams(500)
+        .SetExemplarFilter(ExemplarFilterType.TraceBased)
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+### Standalone (non-host) usage
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Metrics;
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .WithMetrics(metrics => metrics
+        .AddMeter("MyConsoleApp")
+        .AddOtlpExporter()));
+```
+
+## Key parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxMetricStreams` | `int` | 1000 | Maximum number of metric streams allowed (min: 1) |
+| `exemplarFilter` | `ExemplarFilterType` | `AlwaysOff` | Controls how measurements are offered to exemplar reservoirs |
+
+## Behavior notes
+
+- `AddMeter()` accepts exact `Meter` names — unregistered meters are ignored.
+- `AddView()` with a wildcard (`*`) in `instrumentName` cannot rename a stream (would cause conflicts).
+- Views are applied in registration order. The first matching view wins per instrument.
+- `SetMaxMetricPointsPerMetricStream()` is obsolete since 1.10.0 — use `MetricStreamConfiguration.CardinalityLimit` via `AddView` instead.
+- `WithMetrics()` automatically registers an `IMetricsListener` named `"OpenTelemetry"` to bridge `System.Diagnostics.Metrics`.
+- When used with `AddOpenTelemetry()`, the host manages `MeterProvider` lifecycle — do **not** call `Dispose()` manually.

package/dist/Resources/api-reference/dotnet/WithTracing.md

@@ -0,0 +1,91 @@
+---
+title: WithTracing
+category: api-reference
+applies-to: 1.x
+---
+
+# .WithTracing()
+
+## API surface
+
+| Method | Purpose |
+| --- | --- |
+| `.WithTracing()` | Enable tracing with no additional configuration |
+| `.WithTracing(Action<TracerProviderBuilder>)` | Enable tracing and configure the `TracerProviderBuilder` |
+| `builder.AddSource(params string[] names)` | Subscribe to one or more `ActivitySource` names |
+| `builder.AddInstrumentation<T>()` | Add an instrumentation library via DI |
+| `builder.AddProcessor(BaseProcessor<Activity>)` | Add an activity processor instance |
+| `builder.AddProcessor<T>()` | Add a processor resolved from DI (registered as singleton) |
+| `builder.AddProcessor(Func<IServiceProvider, BaseProcessor<Activity>>)` | Add a processor via factory |
+| `builder.SetErrorStatusOnException(bool)` | Auto-set `Status.Error` on unhandled exceptions (default `true`) |
+
+See also: Sampling.md for `SetSampler()` overloads · ConfigureResource.md for resource configuration
+
+## When to use
+
+- Enable distributed tracing in an ASP.NET Core or Worker Service app via `AddOpenTelemetry()`.
+- Enable tracing in a standalone/console app via `OpenTelemetrySdk.Create()`.
+- Subscribe to `ActivitySource` names so the SDK captures spans from your code or instrumentation libraries.
+- Attach processors (e.g., `BatchActivityExportProcessor`) or set a custom sampler.
+- Call multiple times safely — only one `TracerProvider` is created per `IServiceCollection`.
+
+## Minimal example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Full example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService("order-api"))
+    .WithTracing(tracing => tracing
+        .AddSource("OrderService", "PaymentService")
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .SetSampler(new ParentBasedSampler(new TraceIdRatioBasedSampler(0.5)))
+        .AddProcessor<MyFilteringProcessor>()
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+### Standalone (non-host) usage
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .WithTracing(tracing => tracing
+        .AddSource("MyConsoleApp")
+        .AddOtlpExporter()));
+
+// sdk.TracerProvider is available if needed
+```
+
+## Behavior notes
+
+- `AddSource()` accepts wildcard-free `ActivitySource` names. Activities from unregistered sources are dropped.
+- Processors run in registration order. Export processors should be added last.
+- When used with `AddOpenTelemetry()`, the host manages `TracerProvider` lifecycle — do **not** call `Dispose()` manually.
+- When used with `OpenTelemetrySdk.Create()`, you own the `OpenTelemetrySdk` instance and must dispose it.