@azure/mcp-linux-arm64 2.0.0-beta.9 → 2.0.0

package/dist/Instrumentation/Resources/api-reference/dotnet/TelemetryClient.md

@@ -0,0 +1,122 @@
+---
+title: TelemetryClient
+category: api-reference
+applies-to: 3.x
+---
+
+# TelemetryClient — Breaking Changes in 3.x
+
+`TelemetryClient` still works in 3.x but several constructors, properties, and method overloads were **removed or changed**. Code that uses removed overloads will not compile after upgrading.
+
+## Removed APIs
+
+| API | Status | Migration |
+| --- | --- | --- |
+| `new TelemetryClient()` (parameterless) | **Removed** | Use `TelemetryClient(TelemetryConfiguration)` via DI (constructor injection). |
+| `client.InstrumentationKey` | **Removed** | Use `TelemetryConfiguration.ConnectionString`. |
+| `TrackPageView(string)` | **Removed** | Use `TrackEvent(name, properties)` or `TrackRequest`. |
+| `TrackPageView(PageViewTelemetry)` | **Removed** | Use `TrackEvent(name, properties)` or `TrackRequest`. |
+
+## Changed method signatures
+
+The `IDictionary<string, double> metrics` parameter was **removed** from several Track methods. Code passing a metrics dictionary will not compile.
+
+| Method | 2.x signature | 3.x signature | Fix |
+| --- | --- | --- | --- |
+| `TrackEvent` | `(string, IDictionary<string,string>, IDictionary<string,double>)` | `(string, IDictionary<string,string>)` | Remove metrics dict. Track metrics separately via `TrackMetric()`. |
+| `TrackException` | `(Exception, IDictionary<string,string>, IDictionary<string,double>)` | `(Exception, IDictionary<string,string>)` | Remove metrics dict. Track metrics separately via `TrackMetric()`. |
+| `TrackAvailability` | 8-param with trailing `IDictionary<string,double>` | 7-param — metrics removed | Remove metrics dict. Track metrics separately via `TrackMetric()`. |
+
+### Example fix — TrackEvent
+
+**2.x (breaks in 3.x):**
+```csharp
+_telemetryClient.TrackEvent("OrderCreated",
+    new Dictionary<string, string> { ["OrderId"] = orderId },
+    new Dictionary<string, double> { ["ProcessingTimeMs"] = elapsed });
+```
+
+**3.x:**
+```csharp
+_telemetryClient.TrackEvent("OrderCreated",
+    new Dictionary<string, string> { ["OrderId"] = orderId });
+_telemetryClient.TrackMetric("OrderProcessingTimeMs", elapsed);
+```
+
+## Other changed APIs
+
+| API | Change | Migration |
+| --- | --- | --- |
+| `TrackDependency` (obsolete 5-param overload) | **Removed** | Use the full overload with `dependencyTypeName`, `target`, `data`, `startTime`, `duration`, `success`. |
+| `GetMetric` (all overloads) | `MetricConfiguration` and `MetricAggregationScope` parameters **removed** | Call the simplified overload: `GetMetric(metricId)` or `GetMetric(metricId, dim1, ...)`. |
+| `Track(ITelemetry)` | Internal routing changed — now delegates to specific Track methods | Review any direct `Track(ITelemetry)` calls; prefer specific Track methods. |
+| `StartOperation<T>` / `StopOperation<T>` | Now uses OpenTelemetry Activities internally | No code change needed — API is the same. |
+
+## Unchanged Track methods — no action needed
+
+These methods and their signatures are **identical** in 3.x:
+
+- `TrackEvent(string eventName)` — single-param overload
+- `TrackEvent(string eventName, IDictionary<string, string> properties)` — 2-param overload (no metrics)
+- `TrackException(Exception exception)` — single-param overload
+- `TrackException(Exception exception, IDictionary<string, string> properties)` — 2-param overload (no metrics)
+- `TrackTrace(string message)` and `TrackTrace(string, SeverityLevel)` and `TrackTrace(string, SeverityLevel, IDictionary<string,string>)`
+- `TrackMetric(string name, double value)` and other `TrackMetric` overloads
+- `TrackRequest(...)` — all overloads
+- `TrackDependency(...)` — full overload (not the obsolete 5-param)
+- `TrackAvailability(...)` — 7-param overload (without metrics dict)
+- `Flush()` and `FlushAsync(CancellationToken)`
+
+## TelemetryContext changes
+
+Several sub-context classes are now **internal** in 3.x:
+
+| Sub-context | Status | Previously accessible properties |
+| --- | --- | --- |
+| `Context.Cloud` | **Internal** | `RoleName`, `RoleInstance` — use `ConfigureResource(r => r.AddService("name"))` instead |
+| `Context.Component` | **Internal** | `Version` — use `ApplicationVersion` in service options |
+| `Context.Device` | **Internal** | `Type`, `Id`, `OperatingSystem`, etc. |
+| `Context.Session` | **Internal** | `Id`, `IsFirst` |
+
+These remain **public**: `Context.User` (`Id`, `AuthenticatedUserId`, `UserAgent`), `Context.Operation` (`Name`), `Context.Location` (`Ip`), `Context.GlobalProperties`.
+
+Properties made internal on remaining public sub-contexts:
+- `User.AccountId` — internal; set via properties dict on Track calls or custom processor
+- `Operation.Id`, `Operation.ParentId` — internal; managed by OpenTelemetry correlation
+- `Operation.CorrelationVector` — removed; no longer needed
+
+## Extensibility — ConfigureOpenTelemetryBuilder
+
+To register custom OpenTelemetry processors or instrumentations alongside TelemetryClient in 3.x:
+
+```csharp
+var config = TelemetryConfiguration.CreateDefault();
+config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+config.ConfigureOpenTelemetryBuilder(otel =>
+{
+    otel.WithTracing(t => t.AddProcessor<MyActivityProcessor>());
+    otel.WithLogging(l => l.AddProcessor<MyLogProcessor>());
+});
+```
+
+When using ASP.NET Core DI, use the service options + `ConfigureOpenTelemetryProvider` pattern instead — see ConfigureOpenTelemetryProvider.md.
+
+## Quick decision guide
+
+| Code pattern found | Action required? |
+| --- | --- |
+| `TrackEvent(name, props, metrics)` — 3 args | **Yes** — remove metrics dict, use `TrackMetric()` separately |
+| `TrackException(ex, props, metrics)` — 3 args | **Yes** — remove metrics dict, use `TrackMetric()` separately |
+| `TrackAvailability(..., metrics)` — 8 args | **Yes** — remove metrics dict, use `TrackMetric()` separately |
+| `TrackPageView(...)` | **Yes** — replace with `TrackEvent()` or `TrackRequest()` |
+| `GetMetric(..., MetricConfiguration, ...)` | **Yes** — remove config/scope params |
+| `new TelemetryClient()` (no args) | **Yes** — use DI or `TelemetryClient(TelemetryConfiguration)` |
+| `client.InstrumentationKey = ...` | **Yes** — use `TelemetryConfiguration.ConnectionString` |
+| `Context.Cloud.RoleName = ...` | **Yes** — use `ConfigureResource` |
+| `TrackEvent(name)` or `TrackEvent(name, props)` | No |
+| `TrackTrace(...)` | No |
+| `TrackMetric(...)` | No |
+| `TrackRequest(...)` | No |
+| `TrackDependency(...)` (full overload) | No |
+| `TrackException(ex)` or `TrackException(ex, props)` | No |
+| `Flush()` | No |

package/dist/Instrumentation/Resources/api-reference/dotnet/TelemetryConfigurationBuilder.md

@@ -0,0 +1,173 @@
+---
+title: TelemetryConfigurationBuilder
+category: api-reference
+applies-to: 3.x
+---
+
+# TelemetryConfiguration.ConfigureOpenTelemetryBuilder
+
+The non-DI extensibility API for Application Insights 3.x. Use this when you don't have an `IServiceCollection` — classic ASP.NET (`Global.asax`), console apps, or test scenarios.
+
+For DI-based apps (ASP.NET Core, Worker Service), use ConfigureOpenTelemetryTracerProvider(see in ConfigureOpenTelemetryProvider.md) instead.
+
+## API
+
+```csharp
+TelemetryConfiguration.ConfigureOpenTelemetryBuilder(
+    Action<IOpenTelemetryBuilder> configure)
+```
+
+## Setup pattern
+
+```csharp
+using Microsoft.ApplicationInsights.Extensibility;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Resources;
+
+var config = TelemetryConfiguration.CreateDefault();
+config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+
+config.ConfigureOpenTelemetryBuilder(otel =>
+{
+    // Add custom trace processors
+    otel.WithTracing(tracing =>
+    {
+        tracing.AddProcessor<MyEnrichmentProcessor>();
+        tracing.AddProcessor<MyFilterProcessor>();
+    });
+
+    // Add custom log processors
+    otel.WithLogging(logging =>
+    {
+        logging.AddProcessor<MyLogProcessor>();
+    });
+
+    // Set resource attributes (Cloud.RoleName, etc.)
+    otel.ConfigureResource(r => r.AddService(
+        serviceName: "MyWebApp",
+        serviceInstanceId: Environment.MachineName,
+        serviceVersion: "1.0.0"));
+});
+```
+
+## Add instrumentations
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+config.ConfigureOpenTelemetryBuilder(otel =>
+{
+    otel.WithTracing(tracing =>
+    {
+        tracing.AddRedisInstrumentation();
+        tracing.AddSqlClientInstrumentation(options =>
+        {
+            options.SetDbStatementForText = true;
+        });
+    });
+});
+```
+
+## Add exporters (dual export)
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Logs;
+
+config.ConfigureOpenTelemetryBuilder(otel =>
+{
+    // Console exporter for debugging
+    otel.WithTracing(tracing => tracing.AddConsoleExporter());
+    otel.WithLogging(logging => logging.AddConsoleExporter());
+
+    // OTLP exporter for secondary destination
+    otel.WithTracing(tracing => tracing.AddOtlpExporter());
+    otel.WithMetrics(metrics => metrics.AddOtlpExporter());
+});
+```
+
+## TelemetryClient usage
+
+In classic ASP.NET, create a **single static** `TelemetryClient` instance. `TelemetryConfiguration.CreateDefault()` returns a singleton shared with `ApplicationInsightsHttpModule` — do not create per-request instances.
+
+```csharp
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Resources;
+
+public class MvcApplication : HttpApplication
+{
+    public static TelemetryClient TelemetryClient { get; private set; }
+
+    protected void Application_Start()
+    {
+        var config = TelemetryConfiguration.CreateDefault();
+        config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+        config.ConfigureOpenTelemetryBuilder(otel =>
+        {
+            otel.WithTracing(tracing => tracing.AddProcessor<MyProcessor>());
+            otel.ConfigureResource(r => r.AddService("MyWebApp"));
+        });
+
+        TelemetryClient = new TelemetryClient(config);
+
+        AreaRegistration.RegisterAllAreas();
+        RouteConfig.RegisterRoutes(RouteTable.Routes);
+    }
+
+    protected void Application_End()
+    {
+        TelemetryClient?.Flush();
+        System.Threading.Tasks.Task.Delay(1000).Wait();
+    }
+}
+```
+
+Then in controllers:
+
+```csharp
+public class HomeController : Controller
+{
+    public ActionResult Index()
+    {
+        MvcApplication.TelemetryClient.TrackEvent("HomeVisited");
+        return View();
+    }
+}
+```
+
+## Relationship to ConfigureOpenTelemetryTracerProvider
+
+| Scenario | API to use |
+|---|---|
+| ASP.NET Core / Worker Service (DI) | `services.ConfigureOpenTelemetryTracerProvider(...)` |
+| Classic ASP.NET (Global.asax) | `config.ConfigureOpenTelemetryBuilder(...)` |
+| Console apps without DI | `config.ConfigureOpenTelemetryBuilder(...)` |
+| Tests | `config.ConfigureOpenTelemetryBuilder(...)` |
+
+Both APIs provide access to the same OTel builders (`TracerProviderBuilder`, `MeterProviderBuilder`, `LoggerProviderBuilder`). The difference is the entry point — `IServiceCollection` extension vs `TelemetryConfiguration` method.
+
+## Key differences from 2.x
+
+| 2.x Pattern | 3.x via `ConfigureOpenTelemetryBuilder` |
+|---|---|
+| `config.TelemetryInitializers.Add(new MyInit())` | `otel.WithTracing(t => t.AddProcessor<MyProcessor>())` in `OnStart` |
+| `config.TelemetryProcessorChainBuilder.Use(...)` | `otel.WithTracing(t => t.AddProcessor<MyProcessor>())` in `OnEnd` |
+| `config.TelemetryChannel = new InMemoryChannel()` | Not needed — export managed by OTel |
+| `config.TelemetrySinks.Add(...)` | `otel.WithTracing(t => t.AddOtlpExporter())` |
+
+## Notes
+
+- **`using OpenTelemetry;` is required** — the `WithTracing()`, `WithLogging()`, `WithMetrics()`, and `ConfigureResource()` extension methods on `IOpenTelemetryBuilder` are defined in the root `OpenTelemetry` namespace. Without this using directive, these methods will not resolve. This is separate from `using OpenTelemetry.Trace;` / `using OpenTelemetry.Logs;` which are also needed.
+- `CreateDefault()` returns a **static singleton** in 3.x (not a new instance). Call `ConfigureOpenTelemetryBuilder` only once, in `Application_Start`.
+- Connection string is **required** — 3.x throws if not set. For tests, use a dummy: `InstrumentationKey=00000000-0000-0000-0000-000000000000`.
+- Call `TelemetryClient.Flush()` in `Application_End` followed by a short delay to avoid data loss on shutdown.
+- `GlobalProperties` on `TelemetryClient.Context` works for custom properties. Other `Context` properties (User.Id, Operation.Name) have known propagation limitations in 3.x.

package/dist/Instrumentation/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/Instrumentation/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/Instrumentation/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.