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

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

@@ -0,0 +1,137 @@
+---
+title: AzureMonitorExporter
+category: api-reference
+applies-to: 3.x
+source: src/AzureMonitorExporterExtensions.cs, src/AzureMonitorExporterOptions.cs
+---
+
+# AddAzureMonitor*Exporter
+
+**Namespace:** `Azure.Monitor.OpenTelemetry.Exporter`
+
+## When to use
+
+- You are building a **console app, CLI tool, or background job** without the .NET Generic Host.
+- You need to export **only a subset** of signals (e.g., traces and metrics but not logs).
+- You need **different options per signal** (e.g., different credentials or storage directories).
+
+## Signatures
+
+```csharp
+public static TracerProviderBuilder AddAzureMonitorTraceExporter(
+    this TracerProviderBuilder builder,
+    Action<AzureMonitorExporterOptions>? configure = null,
+    TokenCredential? credential = null,
+    string? name = null);
+
+public static MeterProviderBuilder AddAzureMonitorMetricExporter(
+    this MeterProviderBuilder builder,
+    Action<AzureMonitorExporterOptions>? configure = null,
+    TokenCredential? credential = null,
+    string? name = null);
+
+public static LoggerProviderBuilder AddAzureMonitorLogExporter(
+    this LoggerProviderBuilder builder,
+    Action<AzureMonitorExporterOptions>? configure = null,
+    TokenCredential? credential = null,
+    string? name = null);
+```
+
+A legacy overload extending `OpenTelemetryLoggerOptions` also exists but is superseded by the `LoggerProviderBuilder` version above.
+
+## Behavior notes
+
+- **Cannot** be combined with `UseAzureMonitorExporter` in the same app — a runtime exception is thrown.
+- **Live Metrics** is not supported by per-signal methods. Setting `EnableLiveMetrics = true` has no effect — a warning is logged and the setting is ignored.
+- For hosted apps (ASP.NET Core, Worker Services), prefer `UseAzureMonitorExporter()`(see in UseAzureMonitorExporter.md) — it registers all three signals in one call with Live Metrics support.
+
+## 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` | **Ignored** by per-signal methods. Only applies with `UseAzureMonitorExporter`. |
+| `EnableTraceBasedLogsSampler` | `bool` | `true` | When `true`, only logs correlated to sampled traces are exported. Logs without trace context are always exported. |
+
+## Sampling
+
+`AddAzureMonitorTraceExporter` 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 |
+
+**Environment variable overrides** — `OTEL_TRACES_SAMPLER` / `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` |
+
+**Log sampling** — when `EnableTraceBasedLogsSampler` is `true` (default), logs correlated to a sampled-out trace are also dropped.
+
+## Minimal example
+
+```csharp
+using Azure.Monitor.OpenTelemetry.Exporter;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+// Connection string from APPLICATIONINSIGHTS_CONNECTION_STRING env var
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .AddAzureMonitorTraceExporter()));
+
+// sdk.Dispose() flushes and shuts down on exit.
+```
+
+## Full example
+
+```csharp
+using Azure.Identity;
+using Azure.Monitor.OpenTelemetry.Exporter;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+
+var credential = new DefaultAzureCredential();
+var connStr = Environment.GetEnvironmentVariable("APPLICATIONINSIGHTS_CONNECTION_STRING");
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .ConfigureResource(r => r.AddService("my-console-app"))
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .AddHttpClientInstrumentation()
+        .AddAzureMonitorTraceExporter(
+            configure: o =>
+            {
+                o.ConnectionString = connStr;
+                o.TracesPerSecond = null;
+                o.SamplingRatio = 0.5F;
+            },
+            credential: credential))
+    .WithMetrics(metrics => metrics
+        .AddMeter("MyApp")
+        .AddAzureMonitorMetricExporter(
+            configure: o => o.ConnectionString = connStr,
+            credential: credential)));
+// Logging intentionally omitted — only traces and metrics exported
+
+// sdk.Dispose() flushes all signals on exit.
+```
+
+## See also
+
+- UseAzureMonitorExporter (all signals)(see in UseAzureMonitorExporter.md)
+- WithTracing(see in WithTracing.md) · WithMetrics(see in WithMetrics.md) · WithLogging(see in WithLogging.md)

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

@@ -0,0 +1,218 @@
+---
+title: ConfigureOpenTelemetryProvider
+category: api-reference
+applies-to: 3.x
+---
+
+# ConfigureOpenTelemetry*Provider Extensions
+
+These `IServiceCollection` extension methods register actions used to
+configure OpenTelemetry providers. They work anywhere you have access to an
+`IServiceCollection` - in application startup, inside a builder's
+`ConfigureServices` callback, or in a shared extension method.
+
+## When to use
+
+- You want to **register sources, meters, or logging configuration separately**
+  from where the provider is created (e.g., different files, methods, or
+  packages).
+- You need to **add configuration from inside a `ConfigureServices` callback**
+  on a provider builder.
+- Your app has **modular startup** where each feature area configures its own
+  instrumentation independently.
+- You are a **library author** registering instrumentation without owning the
+  provider creation call.
+- You need access to `IServiceProvider` at configuration time to resolve
+  services such as `IConfiguration`.
+
+> [!IMPORTANT]
+> These methods register configuration but **do not create a
+> provider**. A provider must still be created via
+> Host & DI-Integrated (`AddOpenTelemetry`)(see in AddOpenTelemetry.md),
+> Unified Multi-Signal (`OpenTelemetrySdk.Create`)(see in OpenTelemetrySdkCreate.md), or
+> Per-Signal / Legacy (`Sdk.CreateTracerProviderBuilder`)(see in SdkCreateTracerProviderBuilder.md)
+> for the configuration to take effect.
+
+## Namespaces
+
+| Method | Namespace |
+| --- | --- |
+| `ConfigureOpenTelemetryTracerProvider` | `OpenTelemetry.Trace` |
+| `ConfigureOpenTelemetryMeterProvider` | `OpenTelemetry.Metrics` |
+| `ConfigureOpenTelemetryLoggerProvider` | `OpenTelemetry.Logs` |
+
+## Available methods
+
+| Method | Signal |
+| --- | --- |
+| `services.ConfigureOpenTelemetryTracerProvider(...)` | Tracing |
+| `services.ConfigureOpenTelemetryMeterProvider(...)` | Metrics |
+| `services.ConfigureOpenTelemetryLoggerProvider(...)` | Logging |
+
+### Overload 1 - `Action<*ProviderBuilder>` (executed immediately)
+
+```csharp
+public static IServiceCollection ConfigureOpenTelemetryTracerProvider(
+    this IServiceCollection services,
+    Action<TracerProviderBuilder> configure);
+
+public static IServiceCollection ConfigureOpenTelemetryMeterProvider(
+    this IServiceCollection services,
+    Action<MeterProviderBuilder> configure);
+
+public static IServiceCollection ConfigureOpenTelemetryLoggerProvider(
+    this IServiceCollection services,
+    Action<LoggerProviderBuilder> configure);
+```
+
+The `configure` delegate is **invoked immediately** (not deferred). Internally
+it creates a `*ProviderServiceCollectionBuilder` (e.g.,
+`TracerProviderServiceCollectionBuilder`) wrapping the `IServiceCollection` and
+passes it to the delegate. Because the delegate receives the builder before the
+`IServiceProvider` exists, it is **safe to register services** (e.g., call
+`AddSource`, `AddMeter`, `AddInstrumentation<T>`, etc.).
+
+### Overload 2 - `Action<IServiceProvider, *ProviderBuilder>` (deferred)
+
+```csharp
+public static IServiceCollection ConfigureOpenTelemetryTracerProvider(
+    this IServiceCollection services,
+    Action<IServiceProvider, TracerProviderBuilder> configure);
+
+public static IServiceCollection ConfigureOpenTelemetryMeterProvider(
+    this IServiceCollection services,
+    Action<IServiceProvider, MeterProviderBuilder> configure);
+
+public static IServiceCollection ConfigureOpenTelemetryLoggerProvider(
+    this IServiceCollection services,
+    Action<IServiceProvider, LoggerProviderBuilder> configure);
+```
+
+This overload registers the delegate as an `IConfigureTracerProviderBuilder` /
+`IConfigureMeterProviderBuilder` / `IConfigureLoggerProviderBuilder` singleton
+in the `IServiceCollection`. The delegate is **not invoked until the provider
+is being constructed** (when the `IServiceProvider` is available). Because the
+service container is already built at that point, **you cannot register new
+services** inside this callback - many builder helper extensions that register
+services will throw `NotSupportedException`.
+
+```csharp
+services.ConfigureOpenTelemetryTracerProvider((sp, tracing) =>
+{
+    var config = sp.GetRequiredService<IConfiguration>();
+    tracing.SetSampler(new TraceIdRatioBasedSampler(
+        config.GetValue<double>("Telemetry:SamplingRate")));
+});
+```
+
+## Example - separating source registration from exporter setup
+
+Register instrumentation sources early in startup, then configure exporters
+separately:
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Resources;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Register sources (could be in a different file or method)
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddSource("MyApp"));
+
+builder.Services.ConfigureOpenTelemetryMeterProvider(metrics =>
+    metrics.AddMeter("MyApp"));
+
+// Configure exporters and create the provider
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService("my-app"))
+    .WithTracing(tracing => tracing.AddOtlpExporter())
+    .WithMetrics(metrics => metrics.AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Example - setting cloud role name via ConfigureResource
+
+A common migration pattern: replace a custom `ITelemetryInitializer` that sets
+cloud role name with `ConfigureResource` + `AddService`:
+
+```csharp
+using OpenTelemetry.Resources; // Required for ResourceBuilder.AddService
+
+// Set cloud role name (replaces ITelemetryInitializer that set Context.Cloud.RoleName)
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.ConfigureResource(r => r.AddService(
+        serviceName: "MyService",
+        serviceInstanceId: Environment.MachineName)));
+```
+
+## Example - library author registering sources
+
+A library can register its instrumentation without depending on the app's
+startup code:
+
+```csharp
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+
+public static class MyLibraryExtensions
+{
+    public static IServiceCollection AddMyLibrary(this IServiceCollection services)
+    {
+        services.AddSingleton<MyService>();
+
+        services.ConfigureOpenTelemetryTracerProvider(tracing =>
+            tracing.AddSource("MyLibrary"));
+        services.ConfigureOpenTelemetryMeterProvider(metrics =>
+            metrics.AddMeter("MyLibrary"));
+
+        return services;
+    }
+}
+```
+
+The host application composes everything:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddMyLibrary();  // library registers its sources
+
+builder.Services.AddOpenTelemetry()          // app owns the provider
+    .ConfigureResource(r => r.AddService("my-app"))
+    .WithTracing(tracing => tracing.AddOtlpExporter())
+    .WithMetrics(metrics => metrics.AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+
+
+## Relationship with `WithTracing` / `WithMetrics` / `WithLogging`
+
+These methods are **complementary** with the `With*` methods, not
+interchangeable. `WithTracing()` / `WithMetrics()` / `WithLogging()` **register
+the provider**; `ConfigureOpenTelemetry*Provider` only **queues configuration
+actions**. Without a `With*` call (or equivalent provider creation), queued
+actions are never consumed.
+
+## Hosting package not required
+
+These methods are defined in `OpenTelemetry.Api.ProviderBuilderExtensions` and
+work with **any `IServiceCollection`** — hosted or non-hosted. The only
+requirement is that a provider is eventually resolved from the same
+`IServiceCollection` for the queued actions to take effect.
+
+## Related methods
+
+| Method | Defined on | Purpose |
+| --- | --- | --- |
+| Host & DI-Integrated (`AddOpenTelemetry`)(see in AddOpenTelemetry.md) | `IServiceCollection` | Creates the provider and starts the hosted service |
+| `.WithTracing()` / `.WithMetrics()` / `.WithLogging()` | `IOpenTelemetryBuilder` | Registers a provider for the signal and optionally configures it |
+| `.ConfigureResource()` | `IOpenTelemetryBuilder` | Shared resource configuration (internally uses `ConfigureOpenTelemetry*Provider`) |
+

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

@@ -0,0 +1,119 @@
+---
+title: ConfigureResource
+category: api-reference
+applies-to: 1.x
+---
+
+# .ConfigureResource()
+
+## API surface
+
+### On `IOpenTelemetryBuilder` (shared across all signals)
+
+| Method | Purpose |
+| --- | --- |
+| `.ConfigureResource(Action<ResourceBuilder>)` | Modify the resource for traces, metrics, **and** logs |
+
+### On individual provider builders
+
+| Method | Purpose |
+| --- | --- |
+| `TracerProviderBuilder.ConfigureResource(Action<ResourceBuilder>)` | Modify resource for tracing only |
+| `MeterProviderBuilder.ConfigureResource(Action<ResourceBuilder>)` | Modify resource for metrics only |
+| `LoggerProviderBuilder.ConfigureResource(Action<ResourceBuilder>)` | Modify resource for logging only |
+| `*.SetResourceBuilder(ResourceBuilder)` | Replace the resource builder entirely (all three builders) |
+
+### `ResourceBuilder` static methods
+
+| Method | Purpose |
+| --- | --- |
+| `ResourceBuilder.CreateDefault()` | Create builder with SDK defaults + env var detector |
+| `ResourceBuilder.CreateEmpty()` | Create builder with no attributes |
+
+### `ResourceBuilder` instance methods
+
+| Method | Purpose |
+| --- | --- |
+| `.AddService(string serviceName, ...)` | Add `service.name`, `service.namespace`, `service.version`, `service.instance.id` |
+| `.AddAttributes(IEnumerable<KeyValuePair<string, object>>)` | Add arbitrary resource attributes |
+| `.AddTelemetrySdk()` | Add `telemetry.sdk.*` attributes (included in `CreateDefault()`) |
+| `.AddEnvironmentVariableDetector()` | Parse `OTEL_RESOURCE_ATTRIBUTES` and `OTEL_SERVICE_NAME` env vars |
+| `.AddDetector(IResourceDetector)` | Add a custom resource detector |
+| `.AddDetector(Func<IServiceProvider, IResourceDetector>)` | Add a custom detector resolved from DI |
+| `.Clear()` | Remove all previously added detectors/resources |
+
+## When to use
+
+- Set `service.name`, `service.version`, and other resource attributes that identify your application.
+- Apply a shared resource across all three signals (traces, metrics, logs) via the top-level `IOpenTelemetryBuilder`.
+- Override or extend the default resource for a single signal's provider builder.
+- Add custom `IResourceDetector` implementations for cloud metadata or environment-specific attributes.
+- Call multiple times safely — each configuration action is applied sequentially.
+
+## Minimal example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService("my-api"))
+    .WithTracing(t => t.AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Full example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(resource => resource
+        .AddService(
+            serviceName: "order-api",
+            serviceNamespace: "ecommerce",
+            serviceVersion: "2.1.0",
+            autoGenerateServiceInstanceId: true)
+        .AddAttributes(new Dictionary<string, object>
+        {
+            ["deployment.environment"] = "production",
+            ["host.name"] = Environment.MachineName,
+        })
+        .AddEnvironmentVariableDetector())
+    .WithTracing(t => t.AddOtlpExporter())
+    .WithMetrics(m => m.AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Key parameters
+
+`AddService()` parameters:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `serviceName` | `string` | *(required)* | Value for `service.name` |
+| `serviceNamespace` | `string?` | `null` | Value for `service.namespace` |
+| `serviceVersion` | `string?` | `null` | Value for `service.version` |
+| `autoGenerateServiceInstanceId` | `bool` | `true` | Auto-generate a GUID for `service.instance.id` |
+| `serviceInstanceId` | `string?` | `null` | Explicit `service.instance.id` (overrides auto-generate) |
+
+## Behavior notes
+
+- `ConfigureResource()` on `IOpenTelemetryBuilder` delegates to `ConfigureResource()` on all three signal builders (tracer, meter, logger).
+- `ConfigureResource()` is **additive** — each call appends to the existing resource.
+- `SetResourceBuilder()` **replaces** the entire resource builder. Use `ConfigureResource()` unless you specifically need a full reset.
+- `CreateDefault()` includes `telemetry.sdk.*` attributes, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and a fallback `service.name` of `unknown_service:<process_name>`.
+- `AddDetector(Func<IServiceProvider, IResourceDetector>)` throws `NotSupportedException` if `ResourceBuilder.Build()` is called directly without an `IServiceProvider`.
+- Resource attributes are merged in registration order. Later values for the same key overwrite earlier ones.

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

@@ -0,0 +1,47 @@
+---
+title: ConsoleExporter
+category: api-reference
+applies-to: 1.x
+---
+
+# Console Exporter
+
+Writes traces, metrics, and logs to the console (stdout). Useful for **local development and debugging only** — not for production.
+
+## Package
+
+```
+OpenTelemetry.Exporter.Console
+```
+
+## Setup
+
+```csharp
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Logs;
+
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddConsoleExporter());
+
+builder.Services.ConfigureOpenTelemetryMeterProvider(metrics =>
+    metrics.AddConsoleExporter());
+
+builder.Services.ConfigureOpenTelemetryLoggerProvider(logging =>
+    logging.AddConsoleExporter());
+```
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `Targets` | `Console` | `ConsoleExporterOutputTargets.Console` or `Debug` (writes to `System.Diagnostics.Debug`). |
+
+## Notes
+
+- **Development only** — do not use in production. Adds significant overhead.
+- Useful for verifying that spans, metrics, and log records are being generated correctly.
+- Console exporter works alongside Azure Monitor — both receive the same telemetry.
+- Each signal needs its own `AddConsoleExporter()` call.
+- For production multi-destination export, use OTLP exporter instead.
+- **Non-DI usage:** Use `config.ConfigureOpenTelemetryBuilder(otel => otel.WithTracing(t => t.AddConsoleExporter()))` on `TelemetryConfiguration`. See TelemetryClient.md.

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

@@ -0,0 +1,56 @@
+---
+title: EntityFrameworkInstrumentation
+category: api-reference
+applies-to: 1.x
+---
+
+# Entity Framework Core Instrumentation
+
+## Package
+
+```
+OpenTelemetry.Instrumentation.EntityFrameworkCore
+```
+
+## Setup
+
+```csharp
+using OpenTelemetry.Trace;
+
+// EF Core is auto-instrumented via DiagnosticSource — no additional setup needed.
+// To customize, use ConfigureOpenTelemetryTracerProvider:
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddEntityFrameworkCoreInstrumentation(options =>
+    {
+        options.SetDbStatementForText = true;  // Include SQL text (be careful with PII)
+        options.SetDbStatementForStoredProcedure = true;
+    }));
+```
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `SetDbStatementForText` | `false` | Include raw SQL text in `db.statement` attribute. May contain PII. |
+| `SetDbStatementForStoredProcedure` | `true` | Include stored procedure names in `db.statement`. |
+| `EnrichWithIDbCommand` | `null` | `Action<Activity, IDbCommand>` callback to enrich spans with custom tags from the command. |
+| `Filter` | `null` | `Func<string, string, bool>` — filter by provider name and command text. Return `false` to suppress. |
+
+## Semantic conventions
+
+EF Core spans use the [OpenTelemetry Database semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/):
+
+| Attribute | Example |
+|---|---|
+| `db.system` | `microsoft.sql_server`, `postgresql`, `sqlite` |
+| `db.name` | `MyDatabase` |
+| `db.statement` | `SELECT * FROM Orders WHERE Id = @p0` (if `SetDbStatementForText = true`) |
+| `server.address` | `localhost` |
+| `server.port` | `5432` |
+
+## Notes
+
+- EF Core instrumentation relies on `DiagnosticSource` events emitted by EF Core itself — no additional packages needed for basic span collection.
+- The `OpenTelemetry.Instrumentation.EntityFrameworkCore` package is only needed to customize options (SQL text capture, enrichment, filtering).
+- Works with all EF Core providers (SQL Server, PostgreSQL, SQLite, MySQL, etc.).
+- **Non-DI usage:** If not using ASP.NET Core DI, use `config.ConfigureOpenTelemetryBuilder(otel => otel.WithTracing(t => t.AddEntityFrameworkCoreInstrumentation()))` on `TelemetryConfiguration`. See TelemetryClient.md.

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

@@ -0,0 +1,109 @@
+---
+title: HttpInstrumentation
+category: api-reference
+applies-to: 1.x
+---
+
+# HTTP Instrumentation — Client & Server Enrichment
+
+HTTP client and server instrumentation is auto-configured by both Azure Monitor Distro and Application Insights 3.x. This doc covers **customization**: enrichment, filtering, and advanced options.
+
+## Packages
+
+| Scope | Package | Auto-included? |
+|---|---|---|
+| HTTP Client (`HttpClient`) | `OpenTelemetry.Instrumentation.Http` | Yes (by Distro & AI 3.x) |
+| HTTP Server (ASP.NET Core) | `OpenTelemetry.Instrumentation.AspNetCore` | Yes (by Distro & AI 3.x) |
+
+You only need to install these packages explicitly if you want to **customize** the instrumentation options.
+
+## HTTP Client enrichment
+
+```csharp
+using OpenTelemetry.Trace;
+
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddHttpClientInstrumentation(options =>
+    {
+        options.EnrichWithHttpRequestMessage = (activity, request) =>
+        {
+            activity.SetTag("http.request.header.x-correlation-id",
+                request.Headers.TryGetValues("X-Correlation-Id", out var vals) ? vals.First() : null);
+        };
+        options.EnrichWithHttpResponseMessage = (activity, response) =>
+        {
+            activity.SetTag("http.response.content_length", response.Content.Headers.ContentLength);
+        };
+        options.FilterHttpRequestMessage = (request) =>
+        {
+            // Suppress health check calls
+            return request.RequestUri?.AbsolutePath != "/health";
+        };
+        options.RecordException = true;
+    }));
+```
+
+## HTTP Client options
+
+| Option | Default | Description |
+|---|---|---|
+| `EnrichWithHttpRequestMessage` | `null` | `Action<Activity, HttpRequestMessage>` to add tags from the request. |
+| `EnrichWithHttpResponseMessage` | `null` | `Action<Activity, HttpResponseMessage>` to add tags from the response. |
+| `EnrichWithException` | `null` | `Action<Activity, Exception>` to enrich on failure. |
+| `FilterHttpRequestMessage` | `null` | `Func<HttpRequestMessage, bool>` — return `false` to suppress span. |
+| `RecordException` | `false` | Record exception events on the span. |
+
+## HTTP Server (ASP.NET Core) enrichment
+
+```csharp
+using OpenTelemetry.Trace;
+
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddAspNetCoreInstrumentation(options =>
+    {
+        options.EnrichWithHttpRequest = (activity, request) =>
+        {
+            activity.SetTag("http.request.header.user-agent", request.Headers["User-Agent"].ToString());
+        };
+        options.EnrichWithHttpResponse = (activity, response) =>
+        {
+            activity.SetTag("http.response.custom_header", response.Headers["X-Custom"].ToString());
+        };
+        options.Filter = (httpContext) =>
+        {
+            // Suppress /health and /metrics endpoints
+            return httpContext.Request.Path != "/health"
+                && httpContext.Request.Path != "/metrics";
+        };
+        options.RecordException = true;
+    }));
+```
+
+## HTTP Server options
+
+| Option | Default | Description |
+|---|---|---|
+| `EnrichWithHttpRequest` | `null` | `Action<Activity, HttpRequest>` to add tags from the request. |
+| `EnrichWithHttpResponse` | `null` | `Action<Activity, HttpResponse>` to add tags from the response. |
+| `EnrichWithException` | `null` | `Action<Activity, Exception>` to enrich on failure. |
+| `Filter` | `null` | `Func<HttpContext, bool>` — return `false` to suppress span. |
+| `RecordException` | `false` | Record exception events on the span. |
+
+## Semantic conventions (auto-populated)
+
+| Attribute | Source |
+|---|---|
+| `http.request.method` | `GET`, `POST`, etc. |
+| `url.full` | Full URL (client) |
+| `url.path` | Path (server) |
+| `http.response.status_code` | `200`, `404`, etc. |
+| `server.address` | Target host (client) |
+| `network.protocol.version` | `1.1`, `2` |
+| `http.route` | Route template (server) |
+
+## Notes
+
+- Both client and server instrumentation are **already active** in AI 3.x setups. Adding the packages explicitly is only needed to access the `options` overload for enrichment/filtering.
+- Enrichment callbacks run synchronously on the hot path — keep them lightweight.
+- `Filter` on the server side is the recommended way to suppress health check / readiness probe spans (instead of a custom processor).
+- **Non-DI usage:** Use `config.ConfigureOpenTelemetryBuilder(otel => otel.WithTracing(t => t.AddHttpClientInstrumentation(...)))` on `TelemetryConfiguration`. See TelemetryClient.md.