@danieljvdm/dev-kit 1.0.1 → 2.0.0

package/skills/sentry/references/sdks/go/metrics.md

@@ -0,0 +1,273 @@
+# Metrics — Sentry Go SDK
+
+> Minimum SDK: `github.com/getsentry/sentry-go` v0.42.0+
+
+## Configuration
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn: os.Getenv("SENTRY_DSN"),
+    // Metrics are enabled by default. Disable with:
+    DisableMetrics: false,
+    // Filter or mutate metrics before sending:
+    BeforeSendMetric: func(metric *sentry.Metric) *sentry.Metric {
+        return metric // return nil to drop
+    },
+})
+```
+
+| Option             | Type                    | Default | Purpose                                    |
+| ------------------ | ----------------------- | ------- | ------------------------------------------ |
+| `DisableMetrics`   | `bool`                  | `false` | Set `true` to disable all metrics emission |
+| `BeforeSendMetric` | `func(*Metric) *Metric` | `nil`   | Mutate or drop individual metrics          |
+
+## Meter API
+
+Create a `Meter` from any context:
+
+```go
+meter := sentry.NewMeter(ctx)
+```
+
+Returns a no-op `Meter` (silently drops all calls) if no client is bound to the hub or
+`DisableMetrics: true`.
+
+### Meter interface
+
+```go
+type Meter interface {
+    Count(name string, count int64, opts ...MeterOption)
+    Gauge(name string, value float64, opts ...MeterOption)
+    Distribution(name string, sample float64, opts ...MeterOption)
+    WithCtx(ctx context.Context) Meter       // returns meter linked to new context/span
+    SetAttributes(attrs ...attribute.Builder) // permanent attributes on all metrics from this meter
+}
+```
+
+> **The Go SDK has exactly three metric types: `Count`, `Gauge`, `Distribution`. Sets
+> and timing helpers are not implemented.**
+
+## Code Examples
+
+### Basic metrics
+
+```go
+import (
+    "context"
+    "time"
+    "github.com/getsentry/sentry-go"
+    "github.com/getsentry/sentry-go/attribute"
+)
+
+func main() {
+    sentry.Init(sentry.ClientOptions{Dsn: os.Getenv("SENTRY_DSN")})
+    defer sentry.Flush(2 * time.Second)
+
+    meter := sentry.NewMeter(context.Background())
+
+    // Counter — integer increments
+    meter.Count("emails.sent", 3,
+        sentry.WithAttributes(
+            attribute.String("provider", "sendgrid"),
+            attribute.Bool("transactional", true),
+        ),
+    )
+
+    // Gauge — current snapshot value
+    meter.Gauge("queue.depth", 142.0,
+        sentry.WithAttributes(
+            attribute.String("queue.name", "orders"),
+        ),
+    )
+
+    // Distribution — histogram / percentile-friendly samples
+    meter.Distribution("api.response_time", 187.5,
+        sentry.WithUnit(sentry.UnitMillisecond),
+        sentry.WithAttributes(
+            attribute.String("endpoint", "/checkout"),
+            attribute.String("method", "POST"),
+        ),
+    )
+}
+```
+
+### Permanent meter attributes
+
+```go
+meter := sentry.NewMeter(context.Background())
+meter.SetAttributes(
+    attribute.String("service", "payment-api"),
+    attribute.String("region", "us-east-1"),
+)
+
+// All metrics from this meter include service and region
+meter.Count("orders.created", 1)
+meter.Gauge("cpu.usage", 0.73, sentry.WithUnit(sentry.UnitRatio))
+```
+
+### Trace-linked metrics
+
+Associate metrics with the current request’s trace span using `WithCtx`:
+
+```go
+http.HandleFunc("/checkout", func(w http.ResponseWriter, r *http.Request) {
+    // meter.WithCtx links metrics to the active span in r.Context()
+    meter.WithCtx(r.Context()).Count("checkout.attempts", 1,
+        sentry.WithAttributes(
+            attribute.String("method", r.Method),
+        ),
+    )
+    // ... handler logic
+})
+```
+
+### Timing a operation with Distribution
+
+There is no built-in timer — measure elapsed time manually:
+
+```go
+func processOrder(ctx context.Context, orderID string) error {
+    start := time.Now()
+
+    err := doWork(ctx, orderID)
+
+    elapsed := float64(time.Since(start).Milliseconds())
+    meter.WithCtx(ctx).Distribution("order.processing_time", elapsed,
+        sentry.WithUnit(sentry.UnitMillisecond),
+        sentry.WithAttributes(
+            attribute.String("order.id", orderID),
+            attribute.Bool("success", err == nil),
+        ),
+    )
+    return err
+}
+```
+
+### Filtering metrics with BeforeSendMetric
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn: os.Getenv("SENTRY_DSN"),
+    BeforeSendMetric: func(m *sentry.Metric) *sentry.Metric {
+        // Drop sub-millisecond distributions (noise)
+        if m.Type == sentry.MetricTypeDistribution {
+            if v, ok := m.Value.Float64(); ok && v < 1.0 {
+                return nil
+            }
+        }
+        // Drop metrics from test environment
+        if env, ok := m.Attributes["sentry.environment"]; ok && env.String() == "test" {
+            return nil
+        }
+        return m
+    },
+})
+```
+
+### Scope override
+
+Override per-metric user/environment context without changing the global scope:
+
+```go
+customScope := sentry.NewScope()
+customScope.SetUser(sentry.User{ID: "user-42"})
+
+meter.Gauge("memory.usage", 512.0,
+    sentry.WithUnit(sentry.UnitMebibyte),
+    sentry.WithScopeOverride(customScope),
+)
+```
+
+## MeterOption Reference
+
+```go
+sentry.WithUnit(unit string)                    // set measurement unit
+sentry.WithAttributes(attrs ...attribute.Builder) // per-call attributes
+sentry.WithScopeOverride(scope *sentry.Scope)   // override scope for this metric
+```
+
+## Unit Constants
+
+**Duration:**
+
+| Constant          | Value           |
+| ----------------- | --------------- |
+| `UnitNanosecond`  | `"nanosecond"`  |
+| `UnitMicrosecond` | `"microsecond"` |
+| `UnitMillisecond` | `"millisecond"` |
+| `UnitSecond`      | `"second"`      |
+| `UnitMinute`      | `"minute"`      |
+| `UnitHour`        | `"hour"`        |
+| `UnitDay`         | `"day"`         |
+| `UnitWeek`        | `"week"`        |
+
+**Information:**
+
+| Constant       | Value        |
+| -------------- | ------------ |
+| `UnitByte`     | `"byte"`     |
+| `UnitKilobyte` | `"kilobyte"` |
+| `UnitMegabyte` | `"megabyte"` |
+| `UnitGigabyte` | `"gigabyte"` |
+| `UnitMebibyte` | `"mebibyte"` |
+| `UnitGibibyte` | `"gibibyte"` |
+
+**Fraction:**
+
+| Constant      | Value       |
+| ------------- | ----------- |
+| `UnitRatio`   | `"ratio"`   |
+| `UnitPercent` | `"percent"` |
+
+## Attribute Package
+
+```go
+import "github.com/getsentry/sentry-go/attribute"
+
+attribute.String(key, value string) Builder
+attribute.Int(key string, value int) Builder
+attribute.Int64(key string, value int64) Builder
+attribute.Float64(key string, v float64) Builder
+attribute.Bool(key string, v bool) Builder
+```
+
+## Auto-Attached Attributes
+
+| Attribute                      | Source                                        |
+| ------------------------------ | --------------------------------------------- |
+| `sentry.release`               | `ClientOptions.Release`                       |
+| `sentry.environment`           | `ClientOptions.Environment`                   |
+| `sentry.server.address`        | `ClientOptions.ServerName` or `os.Hostname()` |
+| `sentry.sdk.name` / `.version` | SDK identifier                                |
+
+## Metric Type Reference
+
+| Method         | Value type | Use for                                                            |
+| -------------- | ---------- | ------------------------------------------------------------------ |
+| `Count`        | `int64`    | Incrementing counters (events, errors, requests)                   |
+| `Gauge`        | `float64`  | Current state snapshot (queue depth, memory, connections)          |
+| `Distribution` | `float64`  | Variable measurements supporting percentiles (latency, file sizes) |
+
+Note: `Count` takes `int64`, not `int`. `IntervalSchedule` also takes `int64`.
+
+## Best Practices
+
+- Use `Count` for events that accumulate (requests served, emails sent, errors thrown)
+- Use `Gauge` for values that represent current state (queue depth, active connections,
+  cache size)
+- Use `Distribution` for latency and sizes — it enables P50/P95/P99 analysis
+- Keep metric names lowercase, dot-separated (`api.response_time`, `queue.depth`)
+- Avoid high-cardinality tag values (user IDs, request IDs) — prefer categorical values
+- Call `meter.SetAttributes()` once with service-level tags rather than repeating them
+  on every call
+- Use `meter.WithCtx(ctx)` inside HTTP handlers to link metrics to the active trace span
+
+## Troubleshooting
+
+| Issue                     | Solution                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------- |
+| Metrics not appearing     | Check `DisableMetrics` is not `true`; verify `sentry.Flush()` is called                  |
+| `NewMeter` returns no-op  | No client bound to hub; check `sentry.Init` was called                                   |
+| `Count` type error        | `count` parameter is `int64`, not `int` — use explicit `int64(n)` cast                   |
+| Missing attributes        | Use `meter.SetAttributes()` for permanent attributes; they apply to all subsequent calls |
+| High-cardinality warnings | Avoid using dynamic values (user IDs, UUIDs) as tag values                               |

package/skills/sentry/references/sdks/go/profiling.md

@@ -0,0 +1,46 @@
+# Profiling — Sentry Go SDK
+
+> **⚠️ Profiling is not available for Go.**
+>
+> Profiling support was added in v0.22.0 as an alpha feature and **removed in v0.31.0**
+> (breaking change). As of v0.43.0, `ProfilesSampleRate` does not exist in
+> `ClientOptions` and the field will not compile.
+
+## Current Status
+
+The Sentry Go SDK **does not support** transaction-based or continuous profiling.
+The `/platforms/go/profiling/` documentation page returns 404.
+
+```go
+// ❌ This does NOT compile on v0.31.0+
+sentry.Init(sentry.ClientOptions{
+    EnableTracing:      true,
+    TracesSampleRate:   1.0,
+    ProfilesSampleRate: 1.0,  // unknown field — compile error
+})
+```
+
+## Alternatives
+
+For Go application profiling, use these standard approaches independently of Sentry:
+
+**pprof (stdlib):**
+
+```go
+import _ "net/http/pprof"
+
+// Exposes /debug/pprof/ on your HTTP server
+http.ListenAndServe(":6060", nil)
+```
+
+**Continuous profiling services:**
+
+- [Pyroscope](https://pyroscope.io/) — open-source continuous profiling
+- [Google Cloud Profiler](https://cloud.google.com/profiler)
+- [Datadog Continuous Profiler](https://docs.datadoghq.com/profiler/)
+
+## Check for Future Support
+
+Monitor the [sentry-go releases](https://github.com/getsentry/sentry-go/releases) and
+[docs.sentry.io/platforms/go/](https://docs.sentry.io/platforms/go/) for profiling to be
+re-introduced.

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

@@ -0,0 +1,366 @@
+# Tracing — Sentry Go SDK
+
+> Minimum SDK: `github.com/getsentry/sentry-go` v0.9.0+
+
+## Configuration
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn:              os.Getenv("SENTRY_DSN"),
+    EnableTracing:    true,      // REQUIRED — tracing is off by default
+    TracesSampleRate: 1.0,       // start at 1.0 for dev; lower in production
+})
+```
+
+Key tracing fields in `ClientOptions`:
+
+| Option                    | Type            | Default   | Purpose                                                       |
+| ------------------------- | --------------- | --------- | ------------------------------------------------------------- |
+| `EnableTracing`           | `bool`          | `false`   | Must be `true` to enable tracing                              |
+| `TracesSampleRate`        | `float64`       | `0.0`     | Uniform sample rate [0.0–1.0]                                 |
+| `TracesSampler`           | `TracesSampler` | `nil`     | Custom per-transaction sampling; overrides `TracesSampleRate` |
+| `MaxSpans`                | `int`           | `1000`    | Max child spans per transaction                               |
+| `TracePropagationTargets` | `[]string`      | `nil`     | URLs to inject trace headers into (nil = all)                 |
+| `PropagateTraceparent`    | `bool`          | `false`   | Also propagate W3C `traceparent` header                       |
+| `TraceIgnoreStatusCodes`  | `[][]int`       | `[[404]]` | HTTP codes that skip trace creation                           |
+| `BeforeSendTransaction`   | `func`          | `nil`     | Mutate or drop transaction events                             |
+
+## Code Examples
+
+### Custom sampler
+
+Use `TracesSampler` instead of `TracesSampleRate` for per-transaction control.
+Setting both — sampler wins.
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn:          os.Getenv("SENTRY_DSN"),
+    EnableTracing: true,
+    TracesSampler: sentry.TracesSampler(func(ctx sentry.SamplingContext) float64 {
+        switch ctx.Span.Name {
+        case "GET /healthz", "GET /metrics":
+            return 0.0  // never sample
+        case "POST /checkout":
+            return 1.0  // always sample
+        default:
+            return 0.1  // 10% of everything else
+        }
+    }),
+})
+```
+
+`SamplingContext` fields:
+
+- `ctx.Span` — current span (always non-nil)
+- `ctx.Parent` — parent span (nil for root transactions)
+
+### Manual transactions and spans
+
+```go
+// Start a root transaction
+tx := sentry.StartTransaction(ctx, "process-order",
+    sentry.WithOpName("task"),
+    sentry.WithTransactionSource(sentry.SourceCustom),
+)
+defer tx.Finish()
+
+// Start a child span — pass tx.Context() to nest under the transaction
+dbSpan := sentry.StartSpan(tx.Context(), "db.query")
+dbSpan.Description = "INSERT INTO orders (user_id, total) VALUES (?, ?)"
+dbSpan.SetData("db.system", "postgresql")
+dbSpan.SetData("db.rows_affected", 1)
+defer dbSpan.Finish()
+
+// Alternative: StartChild on the parent span directly
+cacheSpan := tx.StartChild("cache.get",
+    sentry.WithDescription("get:user:42"),
+)
+defer cacheSpan.Finish()
+```
+
+### HTTP handler with manual transaction
+
+```go
+http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
+    hub := sentry.CurrentHub().Clone()
+    ctx := sentry.SetHubOnContext(r.Context(), hub)
+
+    tx := sentry.StartTransaction(ctx,
+        fmt.Sprintf("%s %s", r.Method, r.URL.Path),
+        sentry.WithOpName("http.server"),
+        sentry.ContinueFromRequest(r),           // link to incoming distributed trace
+        sentry.WithTransactionSource(sentry.SourceURL),
+    )
+    defer tx.Finish()
+
+    users, err := fetchUsers(tx.Context())
+    if err != nil {
+        hub.CaptureException(err)
+        http.Error(w, "internal error", 500)
+        return
+    }
+    fmt.Fprintf(w, "%d users", len(users))
+})
+
+func fetchUsers(ctx context.Context) ([]string, error) {
+    span := sentry.StartSpan(ctx, "db.query")
+    span.Description = "SELECT id, name FROM users"
+    span.SetData("db.system", "postgresql")
+    defer span.Finish()
+
+    time.Sleep(10 * time.Millisecond)
+    span.Status = sentry.SpanStatusOK
+    return []string{"alice", "bob"}, nil
+}
+```
+
+### Setting span status and data
+
+```go
+span := sentry.StartSpan(ctx, "http.client")
+span.Description = "GET https://api.stripe.com/v1/charges"
+span.SetData("http.request.method", "GET")
+span.SetData("server.address", "api.stripe.com")
+
+req, _ := http.NewRequestWithContext(span.Context(), "GET", "https://api.stripe.com/v1/charges", nil)
+resp, err := http.DefaultClient.Do(req)
+if err != nil {
+    span.Status = sentry.SpanStatusInternalError
+} else {
+    span.Status = sentry.HTTPtoSpanStatus(resp.StatusCode)
+    span.SetData("http.response.status_code", resp.StatusCode)
+}
+defer span.Finish()
+```
+
+> `span.Status` is set **directly** — there is no `SetStatus()` method.
+
+### Retrieving active transaction or span from context
+
+```go
+// Root transaction
+tx := sentry.TransactionFromContext(ctx)
+if tx != nil {
+    tx.SetTag("user_id", "42")
+    tx.Name = "custom-name"
+}
+
+// Innermost span (may be a child)
+span := sentry.SpanFromContext(ctx)
+span.SetData("result_count", 47)
+```
+
+## Framework Middleware
+
+All framework middlewares automatically start a root transaction per request and
+continue incoming distributed traces.
+
+| Framework  | Import            | Middleware call                    | Transaction source |
+| ---------- | ----------------- | ---------------------------------- | ------------------ |
+| `net/http` | `sentry-go/http`  | `sentryhttp.New(opts).Handle(mux)` | `SourceURL`        |
+| Gin        | `sentry-go/gin`   | `router.Use(sentrygin.New(opts))`  | `SourceRoute`      |
+| Echo       | `sentry-go/echo`  | `e.Use(sentryecho.New(opts))`      | `SourceRoute`      |
+| Fiber      | `sentry-go/fiber` | `app.Use(sentryfiber.New(opts))`   | `SourceURL`        |
+| Iris       | `sentry-go/iris`  | `app.Use(sentryiris.New(opts))`    | `SourceRoute`      |
+
+Accessing the current transaction in a framework handler:
+
+```go
+// net/http — use the standard context
+tx := sentry.TransactionFromContext(r.Context())
+
+// Gin
+tx := sentrygin.GetSpanFromContext(c)
+
+// Echo
+tx := sentryecho.GetSpanFromContext(c)
+
+// Fiber
+tx := sentryfiber.GetSpanFromContext(c)
+
+// Iris
+tx := sentryiris.GetSpanFromContext(c)
+```
+
+Adding a child span in a Gin handler:
+
+```go
+router.GET("/users/:id", func(c *gin.Context) {
+    tx := sentrygin.GetSpanFromContext(c)
+
+    dbSpan := sentry.StartSpan(tx.Context(), "db.query")
+    dbSpan.Description = "SELECT * FROM users WHERE id = ?"
+    defer dbSpan.Finish()
+
+    // handler logic...
+})
+```
+
+## Distributed Tracing
+
+Sentry propagates two headers:
+
+| Header         | Constant                     | Purpose                     |
+| -------------- | ---------------------------- | --------------------------- |
+| `sentry-trace` | `sentry.SentryTraceHeader`   | Links spans across services |
+| `baggage`      | `sentry.SentryBaggageHeader` | Dynamic Sampling Context    |
+
+**Consuming an incoming trace (downstream service):**
+
+```go
+// ContinueFromRequest reads both sentry-trace and baggage headers automatically
+tx := sentry.StartTransaction(ctx, "GET /api/check",
+    sentry.WithOpName("http.server"),
+    sentry.ContinueFromRequest(r),
+    sentry.WithTransactionSource(sentry.SourceRoute),
+)
+defer tx.Finish()
+```
+
+**Propagating to an outgoing request (upstream service):**
+
+```go
+func callDownstream(ctx context.Context, url string) {
+    hub := sentry.GetHubFromContext(ctx)
+
+    req, _ := http.NewRequest("GET", url, nil)
+    req.Header.Set(sentry.SentryTraceHeader, hub.GetTraceparent())
+    req.Header.Set(sentry.SentryBaggageHeader, hub.GetBaggage())
+
+    http.DefaultClient.Do(req)
+}
+```
+
+**Hub header methods:**
+
+```go
+hub.GetTraceparent()    // sentry-trace format: "traceID-spanID-sampled"
+hub.GetTraceparentW3C() // W3C format: "00-traceID-spanID-01"
+hub.GetBaggage()        // "sentry-trace_id=...,sentry-environment=production,..."
+```
+
+Both `sentry-trace` AND `baggage` headers must be propagated for correct Dynamic
+Sampling Context.
+
+### OpenTelemetry bridge
+
+For projects already using OpenTelemetry, forward OTel spans to Sentry without changing
+instrumentation:
+
+```go
+import (
+    sdktrace "go.opentelemetry.io/otel/sdk/trace"
+    sentryotel "github.com/getsentry/sentry-go/otel"
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/propagation"
+)
+
+sentry.Init(sentry.ClientOptions{
+    Dsn:              os.Getenv("SENTRY_DSN"),
+    EnableTracing:    true,
+    TracesSampleRate: 1.0,
+})
+
+tp := sdktrace.NewTracerProvider(
+    sdktrace.WithSpanProcessor(sentryotel.NewSentrySpanProcessor()),
+)
+otel.SetTracerProvider(tp)
+otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+    propagation.TraceContext{},
+    propagation.Baggage{},
+    sentryotel.NewSentryPropagator(),
+))
+```
+
+When using OTel, pass the OTel context explicitly when capturing errors — global
+`sentry.CaptureException` does not auto-link:
+
+```go
+hub := sentry.CurrentHub()
+hub.Client().CaptureException(
+    err,
+    &sentry.EventHint{Context: otelCtx},
+    hub.Scope(),
+)
+```
+
+## SpanOption Reference
+
+```go
+sentry.WithOpName("http.server")                 // sets span.Op
+sentry.WithDescription("SELECT * FROM users")    // sets span.Description
+sentry.WithTransactionName("checkout")           // sets root span name
+sentry.WithTransactionSource(sentry.SourceRoute) // transaction naming source
+sentry.WithSpanSampled(sentry.SampledTrue)       // force-sample this span
+sentry.ContinueFromRequest(r *http.Request)      // read sentry-trace + baggage from request
+sentry.ContinueFromHeaders(trace, baggage string)// pass raw header strings
+sentry.ContinueTrace(hub, traceparent, baggage)  // hub-aware form
+```
+
+## TransactionSource Constants
+
+| Constant       | Value      | Use when …                                                |
+| -------------- | ---------- | --------------------------------------------------------- |
+| `SourceURL`    | `"url"`    | Raw URL path (low-cardinality risk)                       |
+| `SourceRoute`  | `"route"`  | Parameterised template, e.g. `/users/:id` — **preferred** |
+| `SourceView`   | `"view"`   | View/controller name                                      |
+| `SourceCustom` | `"custom"` | Manually set name                                         |
+| `SourceTask`   | `"task"`   | Background task name                                      |
+
+Use `SourceRoute` with parameterised paths to prevent high-cardinality grouping in
+Sentry’s Performance UI.
+
+## SpanStatus Constants
+
+Set directly: `span.Status = sentry.SpanStatusOK`
+
+| Constant                     | When to use            |
+| ---------------------------- | ---------------------- |
+| `SpanStatusOK`               | Success                |
+| `SpanStatusInternalError`    | Unhandled server error |
+| `SpanStatusNotFound`         | Resource not found     |
+| `SpanStatusPermissionDenied` | Auth failure           |
+| `SpanStatusDeadlineExceeded` | Timeout                |
+| `SpanStatusInvalidArgument`  | Bad input              |
+| `SpanStatusUnavailable`      | Service unavailable    |
+
+Or derive from HTTP response: `span.Status = sentry.HTTPtoSpanStatus(resp.StatusCode)`
+
+## Common Span Op Values
+
+| Op                                | Usage                           |
+| --------------------------------- | ------------------------------- |
+| `http.server`                     | Incoming HTTP requests          |
+| `http.client`                     | Outgoing HTTP calls             |
+| `db.query`                        | SQL SELECT/INSERT/UPDATE/DELETE |
+| `db`                              | Generic database operation      |
+| `cache.get` / `cache.set`         | Cache reads/writes              |
+| `queue.publish` / `queue.process` | Message queues                  |
+| `function`                        | Generic function call           |
+| `task`                            | Background job                  |
+| `grpc.server` / `grpc.client`     | gRPC spans                      |
+
+## Best Practices
+
+- Set `EnableTracing: true` explicitly — it defaults to `false`
+- Use `TracesSampler` (not `TracesSampleRate`) for any environment-specific or
+  route-specific sampling logic
+- Always `defer span.Finish()` — unfinished spans are silently dropped
+- Use `SourceRoute` with parameterised route templates to avoid high-cardinality
+  transaction names
+- Use `ContinueFromRequest(r)` in every HTTP handler to preserve distributed traces
+- Propagate both `sentry-trace` AND `baggage` headers on outgoing requests
+- Don’t set `MaxSpans` below the number of expected child spans in your largest
+  transactions
+
+## Troubleshooting
+
+| Issue                              | Solution                                                                            |
+| ---------------------------------- | ----------------------------------------------------------------------------------- |
+| No transactions appearing          | Ensure `EnableTracing: true` and `TracesSampleRate > 0`                             |
+| Spans missing from transaction     | Ensure `defer span.Finish()` is called on every span                                |
+| High-cardinality transaction names | Use `WithTransactionSource(SourceRoute)` with parameterised route templates         |
+| Distributed trace not linked       | Propagate both `sentry-trace` and `baggage` headers; use `ContinueFromRequest`      |
+| Health checks polluting data       | Use `TracesSampler` to return `0.0` for health endpoints                            |
+| Too many spans                     | Lower `MaxSpans`; coalesce high-frequency child spans (e.g., N+1 DB calls)          |
+| OTel errors not linked to trace    | Pass OTel `ctx` via `EventHint.Context`; don’t use global `sentry.CaptureException` |