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

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

@@ -0,0 +1,101 @@
+---
+title: LogProcessors
+category: api-reference
+applies-to: 1.x
+---
+
+# Log Processors — Enrichment & Redaction
+
+## Key concepts
+
+- Subclass `BaseProcessor<LogRecord>`. Only `OnEnd` is called (not `OnStart`).
+- Register via `.AddProcessor<T>()` — see WithLogging.md.
+- **Log filtering:** Use `ILoggingBuilder.AddFilter<OpenTelemetryLoggerProvider>()` — processor-level filtering is not reliable because `CompositeProcessor` iterates all processors regardless and `LogRecord` has no `Recorded` flag.
+
+## Filtering — use `AddFilter`
+
+```csharp
+using OpenTelemetry.Logs; // Required for OpenTelemetryLoggerProvider
+
+builder.Logging.AddFilter<OpenTelemetryLoggerProvider>("Microsoft.AspNetCore", LogLevel.Warning);
+builder.Logging.AddFilter<OpenTelemetryLoggerProvider>("System.Net.Http", LogLevel.Warning);
+```
+
+This prevents log records from entering the OpenTelemetry pipeline entirely.
+
+## Enrichment — add attributes
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+
+public class LogEnrichmentProcessor : BaseProcessor<LogRecord>
+{
+    public override void OnEnd(LogRecord data)
+    {
+        var attributes = data.Attributes?.ToList()
+            ?? [];
+
+        attributes.Add(new("deployment.environment", "production"));
+        attributes.Add(new("host.name", Environment.MachineName));
+
+        data.Attributes = attributes;
+
+        base.OnEnd(data);
+    }
+}
+```
+
+## Redaction — mask sensitive data
+
+```csharp
+using System.Linq;
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+
+public class RedactionProcessor : BaseProcessor<LogRecord>
+{
+    private static readonly HashSet<string> SensitiveKeys = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "password", "token", "secret", "authorization", "api_key"
+    };
+
+    public override void OnEnd(LogRecord data)
+    {
+        if (data.Attributes != null)
+        {
+            data.Attributes = data.Attributes.Select(attr =>
+                SensitiveKeys.Contains(attr.Key)
+                    ? new KeyValuePair<string, object?>(attr.Key, "[REDACTED]")
+                    : attr).ToList();
+        }
+
+        base.OnEnd(data);
+    }
+}
+```
+
+## Inspectable `LogRecord` properties
+
+`CategoryName`, `LogLevel`, `EventId`, `FormattedMessage` (when `IncludeFormattedMessage = true`), `Attributes`, `TraceId`, `SpanId`, `Timestamp`.
+
+## Migration from Application Insights 2.x
+
+If the old `ITelemetryInitializer` or `ITelemetryProcessor` touched `TraceTelemetry` or `EventTelemetry`, those now map to `LogRecord`:
+
+| 2.x Property | LogRecord equivalent |
+| --- | --- |
+| `trace.Properties["key"]` / `GlobalProperties["key"]` | Add to `data.Attributes` |
+| `trace.SeverityLevel` | `data.LogLevel` |
+| `trace.Message` | `data.FormattedMessage` or `data.Attributes` |
+| `if (item is TraceTelemetry)` type check | Check `data.CategoryName` or `data.LogLevel` |
+| Severity-based filtering in processor | `ILoggingBuilder.AddFilter<OpenTelemetryLoggerProvider>()` |
+
+## Telemetry type mapping
+
+| Source | Application Insights telemetry type |
+| --- | --- |
+| `ILogger` logs | `TraceTelemetry` |
+| `ILogger` logs with `microsoft.custom_event.name` attribute | `EventTelemetry` |
+
+See ActivityProcessors.md for `ActivityKind` → `RequestTelemetry`/`DependencyTelemetry` mapping.

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

@@ -0,0 +1,146 @@
+---
+title: OpenTelemetrySdk.Create
+category: api-reference
+applies-to: 3.x
+---
+
+# OpenTelemetrySdk.Create()
+
+> [!IMPORTANT]
+> **Introduced in 1.10.0.** This is the recommended way to initialize the SDK
+> in non-hosted applications.
+
+## When to use
+
+- **Console apps, CLI tools, background jobs** that do not use the .NET Generic
+  Host.
+- Any non-hosted process that needs **multiple signals** (traces + metrics +
+  logs) under a single lifecycle boundary.
+
+## Minimal example
+
+```csharp
+using OpenTelemetry;
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .ConfigureResource(r => r.AddService("my-console-app"))
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .AddConsoleExporter())
+    .WithMetrics(metrics => metrics
+        .AddMeter("MyApp")
+        .AddConsoleExporter()));
+
+// Application logic goes here.
+// sdk.Dispose() is called by `using`, which flushes all signals.
+```
+
+## Using logging
+
+`OpenTelemetrySdk` exposes an `ILoggerFactory` via the `GetLoggerFactory()`
+extension method:
+
+```csharp
+using Microsoft.Extensions.Logging;
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .WithLogging(logging => logging.AddConsoleExporter()));
+
+var logger = sdk.GetLoggerFactory().CreateLogger<Program>();
+logger.LogInformation("Hello from {Source}", "OpenTelemetry");
+```
+
+## Full multi-signal example
+
+```csharp
+using System.Diagnostics;
+using System.Diagnostics.Metrics;
+using Microsoft.Extensions.Logging;
+using OpenTelemetry;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Trace;
+
+var activitySource = new ActivitySource("MyApp");
+var meter = new Meter("MyApp");
+var requestCounter = meter.CreateCounter<long>("requests");
+
+using var sdk = OpenTelemetrySdk.Create(builder => builder
+    .ConfigureResource(r => r.AddService("my-console-app"))
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .AddOtlpExporter())
+    .WithMetrics(metrics => metrics
+        .AddMeter("MyApp")
+        .AddOtlpExporter())
+    .WithLogging(logging => logging
+        .AddOtlpExporter()));
+
+var logger = sdk.GetLoggerFactory().CreateLogger<Program>();
+
+using (var activity = activitySource.StartActivity("ProcessRequest"))
+{
+    requestCounter.Add(1);
+    logger.LogInformation("Request processed");
+}
+// sdk.Dispose() flushes and shuts down all three providers.
+```
+
+## API surface
+
+`OpenTelemetrySdk.Create()` accepts an `Action<IOpenTelemetryBuilder>`. The
+builder exposes the same extension methods used by the hosted
+`AddOpenTelemetry()` path:
+
+| Method | Purpose |
+| --- | --- |
+| `.WithTracing(Action<TracerProviderBuilder>)` | Configure tracing |
+| `.WithMetrics(Action<MeterProviderBuilder>)` | Configure metrics |
+| `.WithLogging(Action<LoggerProviderBuilder>)` | Configure logging |
+| `.ConfigureResource(Action<ResourceBuilder>)` | Set resource attributes (shared across all signals) |
+
+## Returned object
+
+```mermaid
+classDiagram
+    class OpenTelemetrySdk {
+        +IDisposable
+        +TracerProvider TracerProvider
+        +MeterProvider MeterProvider
+        +LoggerProvider LoggerProvider
+        +GetLoggerFactory() ILoggerFactory
+    }
+    note for OpenTelemetrySdk "GetLoggerFactory() is an extension method"
+```
+
+Unconfigured signals return **no-op** provider instances - safe to access but
+they emit nothing.
+
+## Lifecycle
+
+- **Single disposal.** Calling `sdk.Dispose()` shuts down the internal
+  `IServiceProvider`, which gracefully flushes and disposes all configured
+  providers.
+- **Internally creates its own DI container.** Processors, exporters, and
+  other services registered via `.ConfigureServices()` live inside this
+  container.
+- **Environment-variable support.** An `IConfiguration` instance backed by
+  environment variables is created automatically, so standard `OTEL_*`
+  environment variables are respected.
+
+## Comparison with the per-signal builders
+
+| Concern | `OpenTelemetrySdk.Create()` | `Sdk.CreateTracerProviderBuilder()` |
+| --- | --- | --- |
+| Signals | All in one builder | One builder per signal |
+| Resource config | Shared `.ConfigureResource()` | Must repeat per builder |
+| Disposal | Single `Dispose()` | One `Dispose()` per provider |
+| Internal DI | Yes | No |
+| Minimum SDK version | 1.10.0 | Any |
+
+> [!TIP]
+> **Need the .NET Host?** Use
+> `services.AddOpenTelemetry()`(see in AddOpenTelemetry.md) instead -- same
+> builder API, but lifecycle is managed by the host.

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

@@ -0,0 +1,88 @@
+---
+title: OtlpExporter
+category: api-reference
+applies-to: 1.x
+---
+
+# OTLP Exporter
+
+Export traces, metrics, and logs to any OpenTelemetry Protocol (OTLP) compatible backend (e.g. Jaeger, Grafana Tempo, Aspire Dashboard, custom collectors).
+
+## Package
+
+```
+OpenTelemetry.Exporter.OpenTelemetryProtocol
+```
+
+## Setup
+
+```csharp
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Exporter;
+
+// Azure Monitor is already configured via AddApplicationInsightsTelemetry.
+// Add OTLP as a secondary exporter:
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddOtlpExporter(options =>
+    {
+        options.Endpoint = new Uri("http://localhost:4317");
+        options.Protocol = OtlpExportProtocol.Grpc;
+    }));
+
+builder.Services.ConfigureOpenTelemetryMeterProvider(metrics =>
+    metrics.AddOtlpExporter(options =>
+    {
+        options.Endpoint = new Uri("http://localhost:4317");
+    }));
+
+builder.Services.ConfigureOpenTelemetryLoggerProvider(logging =>
+    logging.AddOtlpExporter(options =>
+    {
+        options.Endpoint = new Uri("http://localhost:4317");
+    }));
+```
+    .WithTracing(tracing => tracing.AddOtlpExporter())
+    .WithMetrics(metrics => metrics.AddOtlpExporter());
+```
+
+### Environment variable configuration
+
+Instead of code, configure via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OTLP endpoint URL |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc` | Protocol: `grpc` or `http/protobuf` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | — | Headers as `key=value` pairs, comma-separated |
+| `OTEL_EXPORTER_OTLP_TIMEOUT` | `10000` | Timeout in milliseconds |
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `Endpoint` | `http://localhost:4317` | Backend URL. Use port `4317` for gRPC, `4318` for HTTP. |
+| `Protocol` | `Grpc` | `OtlpExportProtocol.Grpc` or `OtlpExportProtocol.HttpProtobuf` |
+| `Headers` | `null` | Custom headers (e.g. auth tokens). Format: `"key=value"` |
+| `TimeoutMilliseconds` | `10000` | Export timeout. |
+| `ExportProcessorType` | `Batch` | `Batch` or `Simple`. Use `Simple` for debugging only. |
+| `BatchExportProcessorOptions` | default | Batch size, delay, queue size for batch processor. |
+
+## Common backends
+
+| Backend | Endpoint | Protocol |
+|---|---|---|
+| Aspire Dashboard | `http://localhost:4317` | gRPC |
+| Jaeger | `http://localhost:4317` | gRPC |
+| Grafana Tempo | `http://localhost:4317` | gRPC |
+| Grafana Cloud | `https://otlp-gateway-*.grafana.net/otlp` | HTTP (`http/protobuf`) |
+| Seq | `http://localhost:5341/ingest/otlp/v1/traces` | HTTP |
+
+## Notes
+
+- OTLP exporter works **alongside** Azure Monitor — data is sent to both destinations.
+- For local development with Aspire Dashboard, use `http://localhost:4317` with gRPC.
+- `AddOtlpExporter()` with no arguments uses environment variables or defaults.
+- Each signal (traces, metrics, logs) needs its own `AddOtlpExporter()` call.
+- **Non-DI usage:** Use `config.ConfigureOpenTelemetryBuilder(otel => otel.WithTracing(t => t.AddOtlpExporter(...)))` on `TelemetryConfiguration`. See TelemetryClient.md.

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

@@ -0,0 +1,63 @@
+---
+title: RedisInstrumentation
+category: api-reference
+applies-to: 1.x
+---
+
+# Redis Instrumentation (StackExchange.Redis)
+
+## Package
+
+```
+OpenTelemetry.Instrumentation.StackExchangeRedis
+```
+
+## Setup
+
+```csharp
+using OpenTelemetry.Trace;
+using OpenTelemetry.Instrumentation.StackExchangeRedis;
+
+// Register IConnectionMultiplexer in DI
+builder.Services.AddSingleton<IConnectionMultiplexer>(
+    ConnectionMultiplexer.Connect("localhost:6379"));
+
+// Add Redis instrumentation
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddRedisInstrumentation());
+```
+
+## Options with customization
+
+```csharp
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddRedisInstrumentation(options =>
+    {
+        options.SetVerboseDatabaseStatements = true;
+    }));
+```
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `SetVerboseDatabaseStatements` | `false` | Include full Redis command in `db.statement` (e.g. `GET mykey`). |
+| `EnrichActivityWithTimingEvents` | `true` | Add Redis timing events (enqueue, sent, response) as Activity events. |
+| `Enrich` | `null` | `Action<Activity, IProfiledCommand>` callback to add custom tags. |
+| `FlushInterval` | 1 second | How often to flush profiling sessions. |
+
+## Semantic conventions
+
+| Attribute | Example |
+|---|---|
+| `db.system` | `redis` |
+| `db.statement` | `GET mykey` (if verbose) |
+| `server.address` | `localhost` |
+| `server.port` | `6379` |
+| `db.redis.database_index` | `0` |
+
+## Notes
+
+- The Redis instrumentation hooks into `StackExchange.Redis` profiling. It requires either DI-registered `IConnectionMultiplexer` (auto-discovered) or passing the connection explicitly.
+- When using DI registration, the instrumentation automatically discovers all `IConnectionMultiplexer` instances — no need to pass the connection manually.
+- **Non-DI usage:** Use `config.ConfigureOpenTelemetryBuilder(otel => otel.WithTracing(t => t.AddRedisInstrumentation(connection)))` on `TelemetryConfiguration`. See TelemetryClient.md.

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

@@ -0,0 +1,86 @@
+---
+title: Sampling
+category: api-reference
+applies-to: 1.x
+---
+
+# SetSampler()
+
+## API surface
+
+### `SetSampler` overloads
+
+| Method | Purpose |
+| --- | --- |
+| `.SetSampler(Sampler)` | Set a sampler instance directly |
+| `.SetSampler<T>()` | Set a sampler resolved from DI (registered as singleton) |
+| `.SetSampler(Func<IServiceProvider, Sampler>)` | Set a sampler via factory delegate |
+
+### `SamplingDecision` enum
+
+| Value | `IsAllDataRequested` | `Recorded` flag | Description |
+| --- | --- | --- | --- |
+| `Drop` | `false` | `false` | Activity created but not recorded or exported |
+| `RecordOnly` | `true` | `false` | Activity recorded (spans visible to processors) but not exported |
+| `RecordAndSample` | `true` | `true` | Activity fully recorded and exported |
+
+## When to use
+
+- Control the volume of traces exported to your backend by sampling a percentage of requests.
+- Honor parent sampling decisions for distributed traces while applying custom logic to root spans.
+- Drop traces entirely for specific scenarios (e.g., health checks) using a custom sampler.
+- Replace the SDK default sampler (`ParentBasedSampler(AlwaysOnSampler)`).
+
+## Minimal example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .SetSampler(new TraceIdRatioBasedSampler(0.1))
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Full example
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddSource("MyApp")
+        .SetSampler(new ParentBasedSampler(
+            rootSampler: new TraceIdRatioBasedSampler(0.25),
+            remoteParentSampled: new AlwaysOnSampler(),
+            remoteParentNotSampled: new AlwaysOffSampler(),
+            localParentSampled: new AlwaysOnSampler(),
+            localParentNotSampled: new AlwaysOffSampler()))
+        .AddOtlpExporter());
+
+var app = builder.Build();
+app.Run();
+```
+
+## Behavior notes
+
+- The SDK default sampler is `ParentBasedSampler(new AlwaysOnSampler())` — all root spans are sampled, child spans follow the parent decision.
+- `SetSampler()` replaces any previously set sampler. Only the last call takes effect.
+- `TraceIdRatioBasedSampler` is deterministic: the same trace ID always produces the same sampling decision, ensuring consistency across services.
+- `SamplingResult` can carry additional attributes and a `TraceStateString` that are attached to the span if sampled.
+- Samplers are invoked **before** the span is fully created. Returning `Drop` means the `Activity` object is created but receives no data and is not exported.
+- To implement a custom sampler, subclass `Sampler` and override `ShouldSample(in SamplingParameters)`.
+
+## See also
+
+- Use `AddProcessor` with a filtering processor if you need to drop spans **after** they are recorded (post-sampling). See ActivityProcessors.md for filtering and enrichment patterns.

package/dist/Instrumentation/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/Instrumentation/Resources/api-reference/dotnet/SqlClientInstrumentation.md

@@ -0,0 +1,53 @@
+---
+title: SqlClientInstrumentation
+category: api-reference
+applies-to: 1.x
+---
+
+# SQL Client Instrumentation
+
+## Package
+
+```
+OpenTelemetry.Instrumentation.SqlClient
+```
+
+## Setup
+
+```csharp
+using OpenTelemetry.Trace;
+
+builder.Services.ConfigureOpenTelemetryTracerProvider(tracing =>
+    tracing.AddSqlClientInstrumentation(options =>
+    {
+        options.SetDbStatementForText = true;   // Include SQL text
+        options.RecordException = true;          // Record exception details on spans
+    }));
+```
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `SetDbStatementForText` | `false` | Include SQL command text in `db.statement`. May contain PII. |
+| `SetDbStatementForStoredProcedure` | `true` | Include stored procedure name in `db.statement`. |
+| `RecordException` | `false` | Record exception details as span events when SQL commands fail. |
+| `EnableConnectionLevelAttributes` | `false` | Add `server.address` and `server.port` from the connection string. |
+| `Enrich` | `null` | `Action<Activity, string, object>` to enrich with custom tags. Event names: `OnCustom`. |
+| `Filter` | `null` | `Func<object, bool>` — return `false` to suppress a span. |
+
+## Semantic conventions
+
+| Attribute | Example |
+|---|---|
+| `db.system` | `microsoft.sql_server` |
+| `db.name` | `MyDatabase` |
+| `db.statement` | `SELECT * FROM Users WHERE Id = @Id` |
+| `server.address` | `myserver.database.windows.net` |
+
+## Notes
+
+- Works with both `System.Data.SqlClient` and `Microsoft.Data.SqlClient`.
+- If using EF Core with SQL Server, you may not need this package separately — EF Core instrumentation captures the same spans. Use this when you have raw `SqlCommand` / `SqlConnection` calls alongside or instead of EF Core.
+- `SetDbStatementForText = true` captures raw SQL which may contain sensitive data. Use with caution in production.
+- **Non-DI usage:** Use `config.ConfigureOpenTelemetryBuilder(otel => otel.WithTracing(t => t.AddSqlClientInstrumentation()))` on `TelemetryConfiguration`. See TelemetryClient.md.