@danieljvdm/dev-kit 1.0.1 → 2.0.0

package/skills/sentry/references/sdks/dotnet/tracing.md

@@ -0,0 +1,897 @@
+# Tracing — Sentry .NET SDK
+
+> Minimum SDK: `Sentry` ≥4.0.0\
+> OpenTelemetry bridge: `Sentry.OpenTelemetry` ≥3.34.0 · OTLP export:
+> `Sentry.OpenTelemetry.Exporter` ≥6.5.0\
+> Custom measurements: `Sentry` ≥3.23.0\
+> Profiling (Alpha): `Sentry.Profiling` ≥4.0.0, .NET 8+ only
+
+---
+
+## How Tracing Is Activated
+
+Tracing is **disabled by default**. Enable it by setting `TracesSampleRate` or
+`TracesSampler` during `SentrySdk.Init()`:
+
+```csharp
+SentrySdk.Init(options =>
+{
+    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
+    options.TracesSampleRate = 1.0; // capture all transactions (lower in production)
+});
+```
+
+> **Without one of these set**, no spans or transactions are created regardless of other
+> configuration.
+
+---
+
+## `TracesSampleRate` — Uniform Sampling
+
+A `double?` between `0.0` (capture nothing) and `1.0` (capture everything).
+Defaults to `null` (disabled).
+
+```csharp
+options.TracesSampleRate = 0.2; // sample 20% of transactions
+```
+
+---
+
+## `TracesSampler` — Dynamic Per-Transaction Sampling
+
+When set, takes **precedence** over `TracesSampleRate`. Receives a
+`TransactionSamplingContext` and returns `double?` (0.0–1.0) or `null` (falls back to
+`TracesSampleRate`).
+
+```csharp
+options.TracesSampler = context =>
+{
+    var name = context.TransactionContext.Name;
+    var op   = context.TransactionContext.Operation;
+
+    // Drop health checks entirely
+    if (name.Contains("/health") || name.Contains("/ping"))
+        return 0.0;
+
+    // Always capture checkout flow
+    if (name == "checkout" || op == "perform-checkout")
+        return 1.0;
+
+    // Read caller-supplied hint
+    if (context.CustomSamplingContext.TryGetValue("isCritical", out var flag) && flag is true)
+        return 1.0;
+
+    return 0.1; // default: 10%
+};
+```
+
+### Passing Custom Sampling Context
+
+```csharp
+var transaction = SentrySdk.StartTransaction(
+    new TransactionContext("checkout", "http.server"),
+    new Dictionary<string, object?> { ["isCritical"] = true }
+);
+```
+
+`TransactionSamplingContext` shape:
+
+```csharp
+public class TransactionSamplingContext
+{
+    public ITransactionContext TransactionContext { get; }
+    public IReadOnlyDictionary<string, object?> CustomSamplingContext { get; }
+}
+```
+
+---
+
+## ASP.NET Core Middleware Integration
+
+### Setup
+
+```csharp
+// Program.cs — .NET 6+ minimal API
+var builder = WebApplication.CreateBuilder(args);
+
+builder.WebHost.UseSentry(options =>
+{
+    options.Dsn = "https://...@o0.ingest.sentry.io/...";
+    options.TracesSampleRate = 1.0;
+    options.SendDefaultPii = true; // include user info in transactions
+});
+
+var app = builder.Build();
+
+app.UseRouting();
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapControllers();
+
+app.Run();
+```
+
+### What Happens Automatically
+
+| Behavior                       | Detail                                                                                                    |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| One transaction per request    | `SentryTracingMiddleware` creates an `ITransactionTracer` for every HTTP request                          |
+| Route-based naming             | Transaction name = route template (e.g., `GET /api/users/{id}`) with `TransactionNameSource.Route`        |
+| Error linking                  | Transaction is set on scope → all errors captured during the request are linked to it                     |
+| Distributed trace continuation | Incoming `sentry-trace` + `baggage` headers are read; `ContinueTrace()` is called automatically           |
+| Outgoing HTTP spans            | `SentryHttpMessageHandler` auto-registered with `IHttpClientFactory` → child spans on every outbound call |
+| EF Core / SQLClient spans      | `DiagnosticSource` integration adds `db.*` child spans automatically (≥3.9.0)                             |
+| Transaction send               | Finished and sent to Sentry when the response is written                                                  |
+
+### Dropping or Renaming Transactions
+
+```csharp
+options.SetBeforeSendTransaction(transaction =>
+{
+    // Drop internal/health routes
+    if (transaction.Name.StartsWith("GET /internal/")) return null;
+
+    return transaction;
+});
+```
+
+---
+
+## Auto-Instrumentation Reference
+
+| Integration                          | Spans Created                                   | Package                                                        | Notes                                               |
+| ------------------------------------ | ----------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
+| ASP.NET Core requests                | `http.server` transaction per request           | `Sentry.AspNetCore`                                            | Enabled automatically by `UseSentry()`              |
+| Outgoing HTTP (`IHttpClientFactory`) | `http.client` spans                             | `Sentry.AspNetCore`                                            | Requires active transaction on scope                |
+| EF Core queries                      | `db.query.compile`, `db.connection`, `db.query` | `Sentry.DiagnosticSource` (auto in `Sentry.AspNetCore` ≥3.9.0) | Opt out with `DisableDiagnosticSourceIntegration()` |
+| SQLClient                            | `db.connection`, `db.query`                     | `Sentry.DiagnosticSource`                                      | Same as EF Core                                     |
+| Azure Functions Worker               | Transaction per invocation                      | `Sentry.AzureFunctions.Worker`                                 | Auto-registered                                     |
+| Hangfire jobs                        | Transaction per job                             | `Sentry.Hangfire`                                              | Auto-registered                                     |
+| `Microsoft.Extensions.AI`            | `ai.*` spans                                    | `Sentry.Extensions.AI`                                         | —                                                   |
+
+### EF Core Span Types
+
+Three spans are created automatically per EF Core query:
+
+```
+db.query.compile   — query compilation / optimization (cached after first run)
+db.connection      — database connection lifecycle
+db.query           — actual SQL execution
+```
+
+### Outgoing HTTP Auto-Instrumentation
+
+Spans are only created when there is an **active transaction on scope**. For manual
+`HttpClient` construction outside of `IHttpClientFactory`:
+
+```csharp
+var sentryHandler = new SentryHttpMessageHandler();
+var httpClient = new HttpClient(sentryHandler);
+
+// Must have a transaction active first
+var tx = SentrySdk.StartTransaction("my-op", "http.client");
+SentrySdk.ConfigureScope(s => s.Transaction = tx);
+
+var response = await httpClient.GetStringAsync("https://api.example.com");
+// ^ creates a "GET https://api.example.com" child span
+
+tx.Finish();
+```
+
+---
+
+## Custom Instrumentation
+
+### Minimal Example
+
+```csharp
+var transaction = SentrySdk.StartTransaction("test-transaction", "test-operation");
+
+var span = transaction.StartChild("test-child-operation");
+// ... do work ...
+span.Finish();
+
+transaction.Finish(); // sends everything to Sentry
+```
+
+### Real-World Example: Checkout Flow
+
+```csharp
+public async Task PerformCheckoutAsync()
+{
+    var transaction = SentrySdk.StartTransaction("checkout", "perform-checkout");
+
+    // Set on scope so that:
+    // 1. Errors during this transaction are linked to it
+    // 2. Auto-instrumentation (HTTP, EF Core) attaches child spans to it
+    SentrySdk.ConfigureScope(scope => scope.Transaction = transaction);
+
+    // Validate cart
+    var validationSpan = transaction.StartChild("validation", "validating shopping cart");
+    try
+    {
+        await ValidateShoppingCartAsync();
+        validationSpan.Finish(SpanStatus.Ok);
+    }
+    catch (Exception ex)
+    {
+        validationSpan.Finish(ex); // auto-maps exception type → SpanStatus
+        transaction.Finish(ex);
+        throw;
+    }
+
+    // Process payment
+    var paymentSpan = transaction.StartChild("payment", "processing payment");
+    await ProcessPaymentAsync();
+    paymentSpan.Finish(SpanStatus.Ok);
+
+    // Send confirmation
+    var emailSpan = transaction.StartChild("email", "sending confirmation email");
+    await SendConfirmationEmailAsync();
+    emailSpan.Finish(SpanStatus.Ok);
+
+    transaction.Finish(SpanStatus.Ok);
+}
+```
+
+### Attaching to an Active Transaction
+
+```csharp
+public async Task DoSomethingAsync()
+{
+    var activeSpan = SentrySdk.GetSpan();
+
+    if (activeSpan == null)
+    {
+        // No transaction in scope — start a new root transaction
+        activeSpan = SentrySdk.StartTransaction("task", "background-job");
+    }
+    else
+    {
+        // Transaction already running — add a child
+        activeSpan = activeSpan.StartChild("subtask");
+    }
+
+    // ... work ...
+    activeSpan.Finish();
+}
+```
+
+### Nested Spans with Data
+
+```csharp
+var transaction = SentrySdk.StartTransaction("data-pipeline", "pipeline");
+
+var fetchSpan = transaction.StartChild("http.client", "fetch raw data");
+    var parseSpan = fetchSpan.StartChild("serialize", "parse JSON response");
+    parseSpan.Finish();
+fetchSpan.Finish();
+
+var processSpan = transaction.StartChild("function", "transform data");
+    var dbSpan = processSpan.StartChild("db.query", "INSERT INTO results");
+    dbSpan.SetData("db.system", "postgresql");
+    dbSpan.SetData("db.statement", "INSERT INTO results (data) VALUES (?)");
+    dbSpan.Finish();
+processSpan.Finish();
+
+transaction.Finish();
+```
+
+### DI-Friendly Pattern (`IHub`)
+
+In ASP.NET Core, inject `IHub` instead of using the static `SentrySdk` API:
+
+```csharp
+public class OrderService
+{
+    private readonly IHub _hub;
+    public OrderService(IHub hub) => _hub = hub;
+
+    public async Task ProcessOrderAsync(int orderId)
+    {
+        var transaction = _hub.StartTransaction("process-order", "task");
+        SentrySdk.ConfigureScope(s => s.Transaction = transaction);
+
+        var span = transaction.StartChild("db.query", $"SELECT * FROM orders WHERE id = {orderId}");
+        try
+        {
+            await FetchOrderAsync(orderId);
+            span.Finish(SpanStatus.Ok);
+            transaction.Finish(SpanStatus.Ok);
+        }
+        catch (Exception ex)
+        {
+            span.Finish(ex);
+            transaction.Finish(ex);
+            throw;
+        }
+    }
+}
+```
+
+---
+
+## Distributed Tracing
+
+### Propagation Headers
+
+Sentry uses two HTTP headers to propagate trace context between services:
+
+| Header         | Format                            | Purpose                                                                                                                                            |
+| -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sentry-trace` | `traceId-spanId-samplingDecision` | Links spans across services into one trace                                                                                                         |
+| `baggage`      | W3C Baggage                       | Carries Dynamic Sampling Context (DSC): `sentry-trace_id`, `sentry-public_key`, `sentry-environment`, `sentry-release`, `sentry-transaction`, etc. |
+
+> **CORS note:** If you have browser frontends, explicitly allowlist `sentry-trace` and
+> `baggage` in your CORS policy — they’re blocked by default as non-simple headers.
+
+### Automatic Propagation (ASP.NET Core)
+
+No configuration needed:
+
+- **Incoming:** `SentryTracingMiddleware` reads `sentry-trace` + `baggage` and calls
+  `ContinueTrace()` automatically
+- **Outgoing:** `SentryHttpMessageHandler` injects `sentry-trace` + `baggage` into all
+  `IHttpClientFactory` requests
+
+### Restrict Which Hosts Receive Trace Headers
+
+By default, headers are injected into **all** outgoing requests.
+Restrict with:
+
+```csharp
+options.TracePropagationTargets = new List<StringOrRegex>
+{
+    "api.mycompany.com",
+    new StringOrRegex(new Regex(@"^https://.*\.mycompany\.com")),
+};
+```
+
+### Manual Propagation — Outgoing
+
+```csharp
+// Read from active transaction
+var sentryTrace = SentrySdk.GetTraceHeader()?.ToString();
+var baggage     = SentrySdk.GetBaggage()?.ToString();
+
+// W3C traceparent (alternative format)
+var traceparent = SentrySdk.GetTraceparentHeader()?.ToString();
+
+// Inject into your request
+request.Headers["sentry-trace"] = sentryTrace;
+request.Headers["baggage"]      = baggage;
+```
+
+### Manual Propagation — Incoming (`ContinueTrace`)
+
+```csharp
+// Service B receives an HTTP request from Service A
+var sentryTraceHeader = httpRequest.Headers["sentry-trace"];
+var baggageHeader     = httpRequest.Headers["baggage"];
+
+// ContinueTrace parses headers and returns a pre-populated TransactionContext
+// with the upstream traceId, parentSpanId, and sampling decision
+var ctx = SentrySdk.ContinueTrace(
+    sentryTraceHeader,
+    baggageHeader,
+    name: "process-incoming-request",
+    operation: "http.server"
+);
+
+var transaction = SentrySdk.StartTransaction(ctx);
+// Now this transaction is part of the same distributed trace as Service A
+```
+
+### Producer / Consumer Queue Example
+
+**Producer:**
+
+```csharp
+var transaction = SentrySdk.StartTransaction("order-submitted", "function");
+
+var publishSpan = transaction.StartChild("queue.publish", "orders");
+publishSpan.SetData("messaging.message.id", messageId);
+publishSpan.SetData("messaging.destination.name", "orders-queue");
+publishSpan.SetData("messaging.message.body.size", Encoding.UTF8.GetByteCount(payload));
+
+// Embed trace context in the message envelope
+var envelope = new MessageEnvelope
+{
+    Payload    = payload,
+    SentryTrace = SentrySdk.GetTraceHeader()?.ToString(),
+    Baggage     = SentrySdk.GetBaggage()?.ToString(),
+};
+
+await queue.PublishAsync("orders-queue", envelope);
+publishSpan.Finish();
+transaction.Finish();
+```
+
+**Consumer:**
+
+```csharp
+var envelope = await queue.ConsumeAsync("orders-queue");
+
+// Link consumer to producer's trace
+var ctx         = SentrySdk.ContinueTrace(envelope.SentryTrace, envelope.Baggage, name: "process-order", operation: "function");
+var transaction = SentrySdk.StartTransaction(ctx);
+
+var processSpan = transaction.StartChild("queue.process", "orders");
+processSpan.SetData("messaging.message.id", envelope.MessageId);
+processSpan.SetData("messaging.destination.name", "orders-queue");
+processSpan.SetData("messaging.message.receive.latency", latencyMs);
+processSpan.SetData("messaging.message.retry.count", retryCount);
+
+try
+{
+    await ProcessOrderAsync(envelope.Payload);
+    processSpan.Finish(SpanStatus.Ok);
+    transaction.Finish(SpanStatus.Ok);
+}
+catch (Exception ex)
+{
+    processSpan.Finish(ex);
+    SentrySdk.CaptureException(ex);
+    transaction.Finish(ex);
+}
+```
+
+---
+
+## OpenTelemetry Integration
+
+Sentry offers two ways to integrate with OpenTelemetry:
+
+1. **OTLP Export (Recommended)** — Send OTel traces directly to Sentry’s OTLP endpoint
+   using standard protocol.
+   Added in 6.5.0.
+2. **Bridge Pattern** — Convert OTel spans to Sentry’s proprietary format via a span
+   processor. Available since 6.1.0.
+
+**Use OTLP Export when:**
+
+- Starting a new OTel integration
+- You want standard OTLP protocol compliance
+- You prefer letting OTel handle all instrumentation
+
+**Use Bridge Pattern when:**
+
+- You need to maintain compatibility with existing integrations
+- You want to mix Sentry’s built-in instrumentations with OTel
+
+---
+
+### Option 1: OTLP Export (Recommended)
+
+> **Added in:** `Sentry` ≥6.5.0, `Sentry.OpenTelemetry.Exporter` ≥6.5.0
+
+Sends OpenTelemetry traces directly to Sentry’s OTLP endpoint using the standard
+OpenTelemetry Protocol.
+This disables Sentry’s built-in tracing instrumentation — all span creation must be done
+via OTel libraries.
+
+#### Install
+
+```bash
+dotnet add package Sentry.OpenTelemetry.Exporter
+```
+
+#### Full ASP.NET Core Setup
+
+```csharp
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Part 1: Configure Sentry with UseOtlp()
+builder.WebHost.UseSentry(options =>
+{
+    options.Dsn = "https://...@o0.ingest.sentry.io/...";
+    options.TracesSampleRate = 1.0;
+    options.UseOtlp(); // ← disables Sentry tracing, enables OTel propagation context
+});
+
+// Part 2: Configure OTel TracerProvider with AddSentryOtlpExporter()
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .AddEntityFrameworkCoreInstrumentation()
+        .AddSentryOtlpExporter(builder.Configuration["Sentry:Dsn"]!) // ← sends spans via OTLP
+    );
+
+var app = builder.Build();
+app.Run();
+```
+
+#### Azure Functions (Isolated Worker)
+
+```csharp
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using OpenTelemetry.Trace;
+
+var host = new HostBuilder()
+    .ConfigureFunctionsWorkerDefaults()
+    .ConfigureLogging(logging =>
+    {
+        logging.AddSentry(options =>
+        {
+            options.Dsn = "https://...@o0.ingest.sentry.io/...";
+            options.TracesSampleRate = 1.0;
+            options.UseOtlp(); // ← required for OTLP mode
+        });
+    })
+    .ConfigureServices(services =>
+    {
+        services.AddOpenTelemetry().WithTracing(builder =>
+        {
+            builder
+                .AddHttpClientInstrumentation()
+                .AddSentryOtlpExporter(Environment.GetEnvironmentVariable("SENTRY_DSN")!);
+        });
+    })
+    .Build();
+
+await host.RunAsync();
+```
+
+#### What `UseOtlp()` Does
+
+- Sets `options.Instrumenter = Instrumenter.OpenTelemetry`
+- Sets `options.DisableSentryTracing = true` — disables `SentryHttpMessageHandler`,
+  `DiagnosticSource` listeners, and EF Core interception
+- Configures `ExternalPropagationContext` to read trace IDs from OTel `Activity`
+
+**Critical:** All tracing must be done via OTel instrumentation libraries.
+Sentry’s built-in span creation (`SentrySdk.StartTransaction()`, auto HTTP/DB spans) is
+disabled.
+
+#### Custom OTLP Endpoint
+
+```csharp
+// Use a custom OTLP collector instead of Sentry's endpoint
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddSentryOtlpExporter(
+            dsnString: builder.Configuration["Sentry:Dsn"]!,
+            collectorUrl: new Uri("https://custom-otel-collector.example.com/v1/traces")
+        )
+    );
+```
+
+#### ⚠️ Exception Capture
+
+OTel’s exception APIs strip exception data before Sentry sees it.
+Use Sentry’s or ILogger’s capture methods:
+
+```csharp
+// ❌ Loses exception details
+activity.RecordException(ex);
+
+// ✅ Use these instead
+_logger.LogError(ex, "Something failed");
+SentrySdk.CaptureException(ex);
+```
+
+---
+
+### Option 2: Bridge Pattern
+
+> **Added in:** `Sentry.OpenTelemetry` ≥3.34.0 (brings in `Sentry` transitively)
+
+Registers a `SentrySpanProcessor` that converts OTel spans to Sentry’s proprietary
+transaction/span format before sending.
+Use when you need compatibility with existing Sentry integrations or want to mix
+instrumentation approaches.
+
+#### Version Requirements
+
+| Package                | Minimum Version |
+| ---------------------- | --------------- |
+| `Sentry.OpenTelemetry` | 3.34.0          |
+| `OpenTelemetry`        | 1.5.0           |
+
+```bash
+dotnet add package Sentry.OpenTelemetry
+```
+
+#### How It Works
+
+The `AddSentry()` extension registers a `SentrySpanProcessor` with the OTel
+`TracerProvider`. Span mapping:
+
+- The **first** OTel `Span` flowing through the processor becomes a Sentry
+  **Transaction**
+- **Child** OTel `Span`s with the same parent become Sentry **child Spans** on that
+  transaction
+- A new top-level OTel `Span` from a different service creates a new Sentry
+  **Transaction**, linked via the same distributed trace
+
+#### Full ASP.NET Core Setup
+
+Two parts are required — both must be configured:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Part 1: Configure Sentry with UseOpenTelemetry()
+builder.WebHost.UseSentry(options =>
+{
+    options.Dsn = "https://...@o0.ingest.sentry.io/...";
+    options.TracesSampleRate = 1.0;
+    options.UseOpenTelemetry(); // ← tells Sentry to use OTel for trace context propagation
+    // Do NOT also configure Sentry's own DiagnosticSource integration —
+    // let OTel instrumentation libraries handle it instead
+});
+
+// Part 2: Register OTel TracerProvider with AddSentry()
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .AddEntityFrameworkCoreInstrumentation()
+        .AddSentry() // ← converts OTel spans to Sentry format
+    );
+
+var app = builder.Build();
+app.Run();
+```
+
+#### ⚠️ Exception Capture
+
+**Do NOT use OTel’s exception APIs** — they strip exception data before Sentry can see
+it:
+
+```csharp
+// ❌ These lose exception details
+activity.RecordException(ex);
+activity.AddException(ex);
+
+// ✅ Use these instead
+_logger.LogError(ex, "Something went wrong"); // ILogger (Sentry captures via logging integration)
+SentrySdk.CaptureException(ex);               // or capture directly
+```
+
+---
+
+## Dynamic Sampling
+
+Sentry’s dynamic sampling uses the **Dynamic Sampling Context (DSC)** carried in
+`baggage` to make consistent sampling decisions across a distributed trace.
+
+### How It Works
+
+1. The **head service** (first in the trace) makes the sampling decision.
+2. The decision is encoded in `baggage` as `sentry-sampled=true|false`.
+3. All downstream services receive `baggage` and honor the upstream decision.
+4. DSC fields: `sentry-trace_id`, `sentry-public_key`, `sentry-sample_rate`,
+   `sentry-sampled`, `sentry-release`, `sentry-environment`, `sentry-transaction`,
+   `sentry-user_segment`.
+
+### `TransactionNameSource` — Critical for Grouping
+
+High-cardinality names (raw URLs) break dynamic sampling grouping.
+Use parameterized routes:
+
+```csharp
+// ❌ Raw URL — creates unbounded unique groups, defeats sampling
+SentrySdk.StartTransaction("/users/12345/orders/9876", "http.server");
+
+// ✅ Parameterized — clean grouping, correct dynamic sampling
+SentrySdk.StartTransaction(new TransactionContext(
+    "/users/{userId}/orders/{orderId}",
+    "http.server",
+    nameSource: TransactionNameSource.Route
+));
+```
+
+| `TransactionNameSource` | Cardinality | Use For                                                 |
+| ----------------------- | ----------- | ------------------------------------------------------- |
+| `Route`                 | Low ✅      | Parameterized route templates (e.g., `GET /users/{id}`) |
+| `Custom`                | Low ✅      | User-defined names (background jobs, tasks)             |
+| `View`                  | Low ✅      | Controller / view class names                           |
+| `Component`             | Medium      | Function / component names                              |
+| `Url`                   | High ❌     | Raw URLs — avoid for dynamic sampling                   |
+| `Task`                  | Low ✅      | Background task names                                   |
+
+---
+
+## Operation Types and Naming Conventions
+
+The `operation` string categorizes and color-codes spans in the Sentry UI. Follow these
+conventions:
+
+| Category        | Operation          | Example Description                     |
+| --------------- | ------------------ | --------------------------------------- |
+| HTTP server     | `http.server`      | `GET /api/users`                        |
+| HTTP client     | `http.client`      | `GET https://api.stripe.com/v1/charges` |
+| DB query        | `db.query`         | `SELECT * FROM orders WHERE id = ?`     |
+| DB connection   | `db.connection`    | —                                       |
+| DB compile      | `db.query.compile` | The LINQ/HQL expression                 |
+| Cache read      | `cache.get`        | The cache key                           |
+| Cache write     | `cache.put`        | The cache key                           |
+| Queue publish   | `queue.publish`    | Queue or topic name                     |
+| Queue consume   | `queue.process`    | Queue or topic name                     |
+| Function        | `function`         | Function or method name                 |
+| Background task | `task`             | Task name                               |
+| Serialization   | `serialize`        | —                                       |
+| Validation      | `validation`       | What is being validated                 |
+| AI inference    | `ai.*`             | Model name                              |
+
+### `Origin` Field
+
+Indicates whether a span was created by auto-instrumentation or by your code:
+
+| Value                      | Source                     |
+| -------------------------- | -------------------------- |
+| `auto.http.aspnetcore`     | ASP.NET Core middleware    |
+| `auto.http.client`         | `SentryHttpMessageHandler` |
+| `auto.db.ef_core_listener` | EF Core DiagnosticSource   |
+| `auto.db.sql_listener`     | SQLClient DiagnosticSource |
+| `manual`                   | User code                  |
+
+---
+
+## Custom Measurements
+
+Attach numeric measurements to transactions (requires `Sentry` ≥3.23.0):
+
+```csharp
+var span = SentrySdk.GetSpan();
+if (span != null)
+{
+    var transaction = span.GetTransaction();
+
+    transaction.SetMeasurement("memory_used",            64,   MeasurementUnit.Information.Megabyte);
+    transaction.SetMeasurement("profile_loading_time",   1.3,  MeasurementUnit.Duration.Second);
+    transaction.SetMeasurement("items_processed",        1500);           // unitless
+    transaction.SetMeasurement("cache_hit_rate",         0.85, MeasurementUnit.Fraction.Ratio);
+}
+```
+
+### `MeasurementUnit` Quick Reference
+
+| Category    | Values                                                                                |
+| ----------- | ------------------------------------------------------------------------------------- |
+| Duration    | `Nanosecond`, `Microsecond`, `Millisecond`, `Second`, `Minute`, `Hour`, `Day`, `Week` |
+| Information | `Bit`, `Byte`, `Kilobyte`/`Kibibyte`, `Megabyte`/`Mebibyte`, `Gigabyte`/`Gibibyte`, … |
+| Fraction    | `Ratio`, `Percent`                                                                    |
+| Unitless    | Omit unit parameter                                                                   |
+
+> **⚠️ Unit consistency:** `("latency", 60, Second)` and `("latency", 3, Minute)` are
+> stored as **separate measurements**, not aggregated.
+> Always use the same unit per measurement name.
+
+---
+
+## `SpanStatus` Reference
+
+```csharp
+SpanStatus.Ok                // success
+SpanStatus.Cancelled         // OperationCanceledException
+SpanStatus.InvalidArgument   // ArgumentException, bad input
+SpanStatus.DeadlineExceeded  // TimeoutException
+SpanStatus.NotFound          // 404
+SpanStatus.PermissionDenied  // UnauthorizedAccessException, 403
+SpanStatus.ResourceExhausted // 429 / out of resources
+SpanStatus.Unimplemented     // NotImplementedException, 501
+SpanStatus.Unavailable       // 503
+SpanStatus.InternalError     // unhandled exception, 500
+SpanStatus.UnknownError      // unknown failure
+SpanStatus.FailedPrecondition // InvalidOperationException
+SpanStatus.Aborted           // conflicting operation
+SpanStatus.DataLoss          // unrecoverable data loss
+```
+
+`span.Finish(exception)` auto-maps exception type → `SpanStatus`. HTTP status codes from
+`SentryHttpMessageHandler` are also mapped automatically (`2xx→Ok`,
+`401→Unauthenticated`, `403→PermissionDenied`, `404→NotFound`, `429→ResourceExhausted`,
+`5xx→InternalError`).
+
+---
+
+## Complete Configuration Reference
+
+```csharp
+SentrySdk.Init(options =>
+{
+    // ── Identity ──────────────────────────────────────────────────────────
+    options.Dsn         = "https://examplePublicKey@o0.ingest.sentry.io/0";
+    options.Environment = "production";
+    options.Release     = "my-app@1.2.3";
+
+    // ── Tracing ───────────────────────────────────────────────────────────
+    options.TracesSampleRate = 0.2;  // 20% uniform rate
+
+    // OR dynamic sampler (takes precedence when set)
+    options.TracesSampler = ctx =>
+    {
+        if (ctx.TransactionContext.Name.Contains("/health")) return 0.0;
+        return 0.1;
+    };
+
+    // Restrict which outbound hosts receive trace headers (default: all)
+    options.TracePropagationTargets = new List<StringOrRegex>
+    {
+        "api.mycompany.internal",
+        new StringOrRegex(new Regex(@"^https://.*\.mycompany\.com")),
+    };
+
+    // ── Auto-instrumentation control ──────────────────────────────────────
+    // options.DisableDiagnosticSourceIntegration(); // opt out of EF Core / SQLClient spans
+
+    // ── OpenTelemetry (optional) ──────────────────────────────────────────
+    // options.UseOpenTelemetry(); // use when routing spans via OTel TracerProvider
+
+    // ── Profiling (Alpha, .NET 8+ only) ───────────────────────────────────
+    // options.ProfilesSampleRate = 0.1;
+    // options.AddProfilingIntegration(TimeSpan.FromMilliseconds(500)); // sync startup
+});
+```
+
+### Key Options Table
+
+| Option                                 | Type                                        | Default           | Purpose                                               |
+| -------------------------------------- | ------------------------------------------- | ----------------- | ----------------------------------------------------- |
+| `TracesSampleRate`                     | `double?`                                   | `null` (disabled) | Uniform sampling rate 0.0–1.0                         |
+| `TracesSampler`                        | `Func<TransactionSamplingContext, double?>` | `null`            | Dynamic sampler; overrides `TracesSampleRate`         |
+| `TracePropagationTargets`              | `IList<StringOrRegex>`                      | `[".*"]` (all)    | Hosts that receive `sentry-trace` + `baggage` headers |
+| `SendDefaultPii`                       | `bool`                                      | `false`           | Include user IP and username in transactions          |
+| `ProfilesSampleRate`                   | `double?`                                   | `null`            | Profiling rate relative to traced transactions        |
+| `UseOpenTelemetry()`                   | method                                      | —                 | Enable OTel-based trace context propagation           |
+| `DisableDiagnosticSourceIntegration()` | method                                      | —                 | Opt out of EF Core / SQLClient auto-spans             |
+
+---
+
+## Quick Reference Cheat Sheet
+
+```csharp
+// ── Start a root transaction ──────────────────────────────────────────────
+var tx = SentrySdk.StartTransaction("name", "operation");
+SentrySdk.ConfigureScope(s => s.Transaction = tx);  // link errors + enable auto-spans
+
+// ── Add child spans ───────────────────────────────────────────────────────
+var span = tx.StartChild("operation", "description");
+span.SetData("key", "value");
+span.Finish(SpanStatus.Ok);
+
+// ── Get the active span from anywhere ────────────────────────────────────
+var active = SentrySdk.GetSpan();
+var child  = active?.StartChild("nested-op");
+child?.Finish();
+
+// ── Access the transaction from a span ───────────────────────────────────
+var txFromSpan = active?.GetTransaction();
+txFromSpan?.SetMeasurement("count", 42, MeasurementUnit.Duration.Millisecond);
+
+// ── Finish variants ───────────────────────────────────────────────────────
+tx.Finish();                          // implicit Ok
+tx.Finish(SpanStatus.InternalError);  // explicit status
+tx.Finish(exception);                 // auto-maps exception → SpanStatus
+
+// ── Distributed tracing: outgoing headers ─────────────────────────────────
+var traceHeader  = SentrySdk.GetTraceHeader()?.ToString();   // "sentry-trace" value
+var baggage      = SentrySdk.GetBaggage()?.ToString();        // "baggage" value
+var traceparent  = SentrySdk.GetTraceparentHeader()?.ToString(); // W3C format
+
+// ── Distributed tracing: incoming headers ─────────────────────────────────
+var ctx    = SentrySdk.ContinueTrace(incomingTraceHeader, incomingBaggageHeader, name: "name", operation: "op");
+var linked = SentrySdk.StartTransaction(ctx);
+```
+
+---
+
+## Troubleshooting
+
+| Issue                                               | Likely Cause                                                                                     | Fix                                                                                                              |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| No transactions appear in Sentry                    | `TracesSampleRate` and `TracesSampler` are both unset                                            | Set `options.TracesSampleRate = 1.0` (or `>0`) during `SentrySdk.Init()`                                         |
+| Transactions appear but have no child spans         | Transaction not set on scope                                                                     | Call `SentrySdk.ConfigureScope(s => s.Transaction = tx)` after starting the transaction                          |
+| Outgoing HTTP spans missing                         | `HttpClient` created manually without `SentryHttpMessageHandler`                                 | Use `IHttpClientFactory`, or wrap with `new HttpClient(new SentryHttpMessageHandler())`                          |
+| EF Core spans missing                               | `Sentry.DiagnosticSource` not installed or version < 3.9.0                                       | Install `Sentry.DiagnosticSource`, or upgrade `Sentry.AspNetCore` to ≥3.9.0                                      |
+| Distributed trace not connected across services     | Missing `ContinueTrace()` on receiving end                                                       | Call `SentrySdk.ContinueTrace(traceHeader, baggageHeader)` and use the returned context to start the transaction |
+| `sentry-trace` header stripped by browser preflight | CORS policy blocks non-simple headers                                                            | Add `sentry-trace` and `baggage` to `Access-Control-Allow-Headers` in your CORS config                           |
+| OTel spans not appearing in Sentry                  | `AddSentry()` missing from `TracerProvider` OR `UseOpenTelemetry()` missing from `SentryOptions` | Both are required: `AddSentry()` in OTel builder AND `options.UseOpenTelemetry()` in Sentry init                 |
+| OTel mode: exceptions captured with no context      | Using `activity.RecordException()` or `activity.AddException()`                                  | Use `SentrySdk.CaptureException(ex)` or `_logger.LogError(ex, ...)` instead                                      |
+| High-cardinality transaction groups                 | Transaction names are raw URLs                                                                   | Use `TransactionNameSource.Route` with parameterized route templates                                             |