@azure/mcp-linux-arm64 2.0.0-beta.3 → 2.0.0-beta.30

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

@@ -0,0 +1,195 @@
+---
+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
+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 - library author registering sources
+
+A library can register its instrumentation without depending on the app's
+startup code:
+
+```csharp
+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/LogProcessors.md

@@ -0,0 +1,99 @@
+---
+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
+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/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.