@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,270 @@
+# Crons — Sentry Go SDK
+
+> Minimum SDK: `github.com/getsentry/sentry-go` v0.18.0+
+
+Sentry Cron Monitoring detects two failure modes:
+
+- **Missed jobs** — the job never ran (schedule was skipped)
+- **Timed-out jobs** — the job started but ran too long
+
+## Configuration
+
+No extra `ClientOptions` are required beyond a valid DSN:
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn: os.Getenv("SENTRY_DSN"),
+})
+defer sentry.Flush(2 * time.Second)
+```
+
+> Check-ins are async by default — always `defer sentry.Flush()` before program exit.
+
+## Core Types
+
+### `CheckIn`
+
+```go
+type CheckIn struct {
+    ID          EventID       // leave zero on start; use *id from start call on completion
+    MonitorSlug string        // slug of the monitor in Sentry
+    Status      CheckInStatus // in_progress | ok | error
+    Duration    time.Duration // optional; set on final check-in
+}
+```
+
+### `CheckInStatus` constants
+
+```go
+sentry.CheckInStatusInProgress // "in_progress" — job started
+sentry.CheckInStatusOK         // "ok"           — job completed successfully
+sentry.CheckInStatusError      // "error"         — job failed
+```
+
+### `MonitorConfig`
+
+```go
+type MonitorConfig struct {
+    Schedule              MonitorSchedule     // when the job should run
+    CheckInMargin         int64               // minutes of grace period before "missed"
+    MaxRuntime            int64               // minutes before in-progress job times out
+    Timezone              string              // tz database name, e.g. "America/New_York"
+    FailureIssueThreshold int64               // consecutive failures before creating an issue
+    RecoveryThreshold     int64               // consecutive successes before auto-resolving
+}
+```
+
+### Schedule constructors
+
+```go
+// Standard 5-field cron expression
+sentry.CrontabSchedule("*/10 * * * *")
+
+// Interval-based
+sentry.IntervalSchedule(1, sentry.MonitorScheduleUnitHour)
+```
+
+`MonitorScheduleUnit` constants: `MonitorScheduleUnitMinute`, `MonitorScheduleUnitHour`,
+`MonitorScheduleUnitDay`, `MonitorScheduleUnitWeek`, `MonitorScheduleUnitMonth`,
+`MonitorScheduleUnitYear`.
+
+> `IntervalSchedule` takes `int64`, not `int`.
+
+## Code Examples
+
+### Check-in pattern (recommended)
+
+Sends both a start and a completion check-in.
+Detects **missed** and **timed-out** jobs.
+
+```go
+func runHourlyReport() error {
+    monitorConfig := &sentry.MonitorConfig{
+        Schedule:              sentry.CrontabSchedule("0 * * * *"),
+        MaxRuntime:            5,  // alert if still running after 5 minutes
+        CheckInMargin:         2,  // allow 2 minutes late before "missed"
+        FailureIssueThreshold: 2,  // create issue after 2 consecutive failures
+        RecoveryThreshold:     1,  // auto-resolve after 1 success
+        Timezone:              "America/New_York",
+    }
+
+    // Send in_progress — pass MonitorConfig here (only needed on first call)
+    checkinID := sentry.CaptureCheckIn(
+        &sentry.CheckIn{
+            MonitorSlug: "hourly-report",
+            Status:      sentry.CheckInStatusInProgress,
+        },
+        monitorConfig,
+    )
+
+    err := generateReport()
+
+    // Send ok or error — dereference the *EventID returned by start
+    status := sentry.CheckInStatusOK
+    if err != nil {
+        status = sentry.CheckInStatusError
+    }
+    sentry.CaptureCheckIn(
+        &sentry.CheckIn{
+            ID:          *checkinID, // dereference *EventID
+            MonitorSlug: "hourly-report",
+            Status:      status,
+        },
+        nil, // no config needed on completion
+    )
+
+    return err
+}
+```
+
+### Heartbeat pattern
+
+Sends only a completion check-in.
+Detects **missed** jobs only (no timeout detection).
+
+```go
+func runDailyCleanup() {
+    start := time.Now()
+
+    cleanupOldRecords()
+
+    sentry.CaptureCheckIn(
+        &sentry.CheckIn{
+            MonitorSlug: "daily-cleanup",
+            Status:      sentry.CheckInStatusOK,
+            Duration:    time.Since(start),
+        },
+        &sentry.MonitorConfig{
+            Schedule: sentry.CrontabSchedule("0 0 * * *"), // midnight daily
+        },
+    )
+}
+```
+
+### Error handling in jobs
+
+```go
+func runSyncJob(ctx context.Context) {
+    id := sentry.CaptureCheckIn(
+        &sentry.CheckIn{MonitorSlug: "data-sync", Status: sentry.CheckInStatusInProgress},
+        &sentry.MonitorConfig{
+            Schedule:   sentry.IntervalSchedule(10, sentry.MonitorScheduleUnitMinute),
+            MaxRuntime: 2,
+        },
+    )
+
+    err := syncData(ctx)
+    if err != nil {
+        // Capture the error AND complete the check-in as error
+        sentry.CaptureException(err)
+        sentry.CaptureCheckIn(
+            &sentry.CheckIn{ID: *id, MonitorSlug: "data-sync", Status: sentry.CheckInStatusError},
+            nil,
+        )
+        return
+    }
+
+    sentry.CaptureCheckIn(
+        &sentry.CheckIn{ID: *id, MonitorSlug: "data-sync", Status: sentry.CheckInStatusOK},
+        nil,
+    )
+}
+```
+
+### Integration with robfig/cron
+
+The SDK provides no built-in cron library wrappers — wrap manually:
+
+```go
+import "github.com/robfig/cron/v3"
+
+c := cron.New()
+c.AddFunc("@every 1h", func() {
+    id := sentry.CaptureCheckIn(
+        &sentry.CheckIn{
+            MonitorSlug: "hourly-job",
+            Status:      sentry.CheckInStatusInProgress,
+        },
+        &sentry.MonitorConfig{
+            Schedule:      sentry.CrontabSchedule("0 * * * *"),
+            MaxRuntime:    5,
+            CheckInMargin: 2,
+        },
+    )
+
+    err := doWork()
+
+    status := sentry.CheckInStatusOK
+    if err != nil {
+        status = sentry.CheckInStatusError
+    }
+    sentry.CaptureCheckIn(
+        &sentry.CheckIn{ID: *id, MonitorSlug: "hourly-job", Status: status},
+        nil,
+    )
+})
+c.Start()
+defer c.Stop()
+```
+
+### Linking errors to the monitor
+
+```go
+sentry.ConfigureScope(func(scope *sentry.Scope) {
+    scope.SetContext("monitor", sentry.Context{"slug": "my-monitor-slug"})
+})
+// Errors captured in this scope will be linked to the monitor in Sentry
+```
+
+## CaptureCheckIn API
+
+```go
+// Package-level (uses CurrentHub)
+func CaptureCheckIn(checkIn *CheckIn, monitorConfig *MonitorConfig) *EventID
+
+// Hub method
+func (hub *Hub) CaptureCheckIn(checkIn *CheckIn, monitorConfig *MonitorConfig) *EventID
+```
+
+Both return `*EventID`. Always dereference with `*id` when passing to the completion
+call. Returns `nil` if no client is bound — guard with `if id != nil`.
+
+## MonitorConfig Guidance
+
+| Field                   | Recommended value                         | Notes                              |
+| ----------------------- | ----------------------------------------- | ---------------------------------- |
+| `Schedule`              | Match your actual cron expression         | Required                           |
+| `CheckInMargin`         | 1–5 min for fast jobs; 10–30 min for slow | Grace period before “missed” alert |
+| `MaxRuntime`            | 2–3× expected runtime                     | Triggers timeout alert             |
+| `Timezone`              | e.g., `"America/New_York"`                | Defaults to UTC if unset           |
+| `FailureIssueThreshold` | `2`                                       | Avoid noise from one-off failures  |
+| `RecoveryThreshold`     | `1`                                       | Auto-resolve on first success      |
+
+Pass `MonitorConfig` on the **start** check-in only; pass `nil` on the completion call.
+
+## Rate Limits
+
+Sentry limits check-ins to **6 per minute per monitor + environment combination**. For
+jobs running more frequently than every 10 seconds, consider sampling.
+
+## Best Practices
+
+- Always send both a start (`InProgress`) and a completion (`OK`/`Error`) check-in —
+  this enables timeout detection
+- Use `defer sentry.Flush(2 * time.Second)` in `main()` — check-ins are queued async
+- Set `MaxRuntime` to roughly 2–3× your expected job duration
+- Set `FailureIssueThreshold: 2` to avoid noisy alerts from transient failures
+- Create the monitor in the Sentry UI first, then use its slug — or let the SDK
+  auto-create it on first check-in
+- Don’t reuse the same `MonitorSlug` for different jobs
+
+## Troubleshooting
+
+| Issue                                 | Solution                                                                     |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| Check-ins not appearing               | Check DSN; ensure `sentry.Flush()` is called; set `Debug: true`              |
+| Monitor shows “missed” unexpectedly   | Increase `CheckInMargin`; ensure `InProgress` is sent before work starts     |
+| Monitor shows “timeout”               | Increase `MaxRuntime`; check for job hangs                                   |
+| Nil pointer on `*checkinID`           | `CaptureCheckIn` returns `nil` if no client — check `sentry.Init` was called |
+| Duplicate issues for the same failure | Set `FailureIssueThreshold: 2` to batch consecutive failures                 |
+| Check-ins rate limited                | Reduce frequency; batch work; check Sentry plan limits                       |

package/skills/sentry/references/sdks/go/error-monitoring.md

@@ -0,0 +1,361 @@
+# Error Monitoring — Sentry Go SDK
+
+> Minimum SDK: `github.com/getsentry/sentry-go` v0.9.0+
+
+## Configuration
+
+Key `ClientOptions` fields for error monitoring:
+
+| Option             | Type                                             | Default | Purpose                                         |
+| ------------------ | ------------------------------------------------ | ------- | ----------------------------------------------- |
+| `Dsn`              | `string`                                         | `""`    | SDK disabled if empty                           |
+| `AttachStacktrace` | `bool`                                           | `false` | Stack traces on `CaptureMessage` calls          |
+| `SendDefaultPII`   | `bool`                                           | `false` | Include IP, request headers                     |
+| `SampleRate`       | `float64`                                        | `1.0`   | Error event sample rate (0.0 treated as 1.0)    |
+| `MaxBreadcrumbs`   | `int`                                            | `100`   | Max breadcrumbs per event (negative = disabled) |
+| `MaxErrorDepth`    | `int`                                            | `100`   | Max depth for unwrapping error chains           |
+| `IgnoreErrors`     | `[]string`                                       | `nil`   | Regex patterns; matched errors are dropped      |
+| `BeforeSend`       | `func(*Event, *EventHint) *Event`                | `nil`   | Mutate or drop error events before sending      |
+| `BeforeBreadcrumb` | `func(*Breadcrumb, *BreadcrumbHint) *Breadcrumb` | `nil`   | Mutate or drop breadcrumbs                      |
+
+## Code Examples
+
+### Basic setup
+
+```go
+import (
+    "log"
+    "os"
+    "time"
+    "github.com/getsentry/sentry-go"
+)
+
+func main() {
+    err := sentry.Init(sentry.ClientOptions{
+        Dsn:              os.Getenv("SENTRY_DSN"),
+        Environment:      os.Getenv("SENTRY_ENVIRONMENT"),
+        Release:          release, // inject via -ldflags
+        AttachStacktrace: true,
+        SendDefaultPII:   true,
+    })
+    if err != nil {
+        log.Fatalf("sentry.Init: %s", err)
+    }
+    defer sentry.Flush(2 * time.Second)
+}
+```
+
+### Capturing errors and messages
+
+```go
+// Error (any value implementing error interface) — unwraps full chain
+sentry.CaptureException(err)
+
+// Plain message (use AttachStacktrace: true for stack traces)
+sentry.CaptureMessage("queue depth exceeded threshold")
+
+// Fully manual event
+sentry.CaptureEvent(&sentry.Event{
+    Message: "payment gateway timeout",
+    Level:   sentry.LevelError,
+    Tags:    map[string]string{"gateway": "stripe"},
+    Fingerprint: []string{"payment-gateway", "timeout"},
+})
+```
+
+### Panic recovery
+
+```go
+// Simplest — defer in any function
+func riskyOperation() {
+    defer sentry.Recover()
+    panic("something catastrophic")
+}
+
+// With context — makes context available in BeforeSend via hint.Context
+func handleRequest(ctx context.Context) {
+    defer sentry.RecoverWithContext(ctx)
+    processRequest()
+}
+
+// Manual — needed when you must flush before process exit
+func main() {
+    defer func() {
+        if err := recover(); err != nil {
+            sentry.CurrentHub().Recover(err)
+            sentry.Flush(5 * time.Second)
+        }
+    }()
+}
+
+// HTTP middleware recovery pattern
+func SentryMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        defer func() {
+            if err := recover(); err != nil {
+                sentry.CurrentHub().Recover(err)
+                sentry.Flush(2 * time.Second)
+                http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+            }
+        }()
+        next.ServeHTTP(w, r)
+    })
+}
+```
+
+### Hub and scope — context enrichment
+
+```go
+// ConfigureScope — persistent modification of the current scope
+sentry.ConfigureScope(func(scope *sentry.Scope) {
+    scope.SetUser(sentry.User{
+        ID:    "user-42",
+        Email: "user@example.com",
+    })
+    scope.SetTag("region", "us-east-1")
+    scope.SetContext("request_metadata", map[string]interface{}{
+        "trace_id":   traceID,
+        "account_id": accountID,
+    })
+})
+
+// WithScope — isolated temporary scope; changes are discarded after the callback
+sentry.WithScope(func(scope *sentry.Scope) {
+    scope.SetTag("component", "checkout")
+    scope.SetLevel(sentry.LevelWarning)
+    sentry.CaptureException(err)
+})
+// ← scope changes above do NOT affect subsequent events
+```
+
+### Hub cloning for goroutines
+
+```go
+// ALWAYS clone the hub before spawning goroutines — global hub is not goroutine-safe
+go func(hub *sentry.Hub) {
+    hub.ConfigureScope(func(scope *sentry.Scope) {
+        scope.SetTag("worker_id", "w-1")
+    })
+    hub.CaptureException(err)
+}(sentry.CurrentHub().Clone())
+```
+
+### Breadcrumbs
+
+```go
+sentry.AddBreadcrumb(&sentry.Breadcrumb{
+    Category: "auth",
+    Message:  "user authenticated",
+    Level:    sentry.LevelInfo,
+})
+
+sentry.AddBreadcrumb(&sentry.Breadcrumb{
+    Type:     "http",
+    Category: "http",
+    Data: map[string]interface{}{
+        "url":         "https://api.example.com/orders",
+        "method":      "POST",
+        "status_code": 503,
+    },
+    Level: sentry.LevelError,
+})
+```
+
+### Error wrapping and chains
+
+The SDK automatically traverses the full error chain from `CaptureException`. Each error
+becomes a separate exception entry in Sentry.
+
+```go
+// %w wrapping — both errors captured; dbErr shown as root cause
+dbErr := errors.New("connection refused")
+appErr := fmt.Errorf("failed to load user %d: %w", userID, dbErr)
+sentry.CaptureException(appErr)
+
+// errors.Join (Go 1.20+) — captured as Sentry exception group
+combined := errors.Join(errors.New("email invalid"), errors.New("token expired"))
+sentry.CaptureException(combined)
+```
+
+| Wrapping pattern        | Interface          | Mechanism   |
+| ----------------------- | ------------------ | ----------- |
+| `fmt.Errorf("%w", err)` | `Unwrap() error`   | `"unwrap"`  |
+| `errors.Join(...)`      | `Unwrap() []error` | `"chained"` |
+| `pkg/errors`            | `Cause() error`    | `"cause"`   |
+
+Limit chain depth with `MaxErrorDepth` (default 100).
+
+### BeforeSend hook
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn: os.Getenv("SENTRY_DSN"),
+    BeforeSend: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+        // Drop events from health check endpoints
+        if event.Request != nil && strings.HasPrefix(event.Request.URL, "/health") {
+            return nil // discard
+        }
+        // Scrub PII
+        event.User.Email = ""
+        event.User.IPAddress = ""
+        // Enrich from original exception type
+        if dbErr, ok := hint.OriginalException.(*DatabaseError); ok {
+            event.Tags["db.table"] = dbErr.Table
+        }
+        // Access context set by RecoverWithContext
+        if hint.Context != nil {
+            if reqID, ok := hint.Context.Value(RequestIDKey).(string); ok {
+                event.Tags["request_id"] = reqID
+            }
+        }
+        return event
+    },
+    // BeforeSend is NOT called for transaction events — use BeforeSendTransaction for those
+    BeforeSendTransaction: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+        if event.Transaction == "GET /healthz" {
+            return nil
+        }
+        return event
+    },
+})
+```
+
+### Event processors
+
+```go
+// Scope-level (per-request enrichment — preferred)
+sentry.ConfigureScope(func(scope *sentry.Scope) {
+    scope.AddEventProcessor(func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+        event.Tags["request_id"] = r.Header.Get("X-Request-ID")
+        event.Tags["tenant_id"]  = r.Header.Get("X-Tenant-ID")
+        return event
+    })
+})
+
+// Client-level (all events from this client)
+client, _ := sentry.NewClient(sentry.ClientOptions{Dsn: os.Getenv("SENTRY_DSN")})
+client.AddEventProcessor(func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+    event.Tags["build_sha"] = os.Getenv("GIT_SHA")
+    return event
+})
+```
+
+Processor execution order: scope processors (LIFO) → client processors → `BeforeSend`.
+
+### Fingerprinting and custom grouping
+
+```go
+// One-off — override grouping for a specific error type
+sentry.WithScope(func(scope *sentry.Scope) {
+    scope.SetFingerprint([]string{"database-connection-error"})
+    sentry.CaptureException(err)
+})
+
+// Extend default grouping (keeps stack trace + adds discriminators)
+BeforeSend: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+    if rpcErr, ok := hint.OriginalException.(MyRPCError); ok {
+        event.Fingerprint = []string{
+            "{{ default }}",
+            rpcErr.FunctionName(),
+            strconv.Itoa(rpcErr.ErrorCode()),
+        }
+    }
+    return event
+},
+```
+
+### Flush patterns
+
+```go
+// Recommended: defer in main()
+defer sentry.Flush(2 * time.Second)
+
+// os.Exit() bypasses defer — call explicitly
+sentry.Flush(2 * time.Second)
+os.Exit(1)
+
+// Context-based
+ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+defer cancel()
+sentry.FlushWithContext(ctx)
+
+// Synchronous transport (no flush needed — every send blocks)
+transport := sentry.NewHTTPSyncTransport()
+transport.Timeout = 3 * time.Second
+sentry.Init(sentry.ClientOptions{Dsn: "...", Transport: transport})
+```
+
+## Scope API Reference
+
+```go
+scope.SetUser(sentry.User{ID: "42", Email: "user@example.com"})
+scope.SetTag("key", "value")
+scope.SetTags(map[string]string{"k": "v"})
+scope.SetContext("key", map[string]interface{}{"field": "value"})
+scope.SetLevel(sentry.LevelError)      // "debug" | "info" | "warning" | "error" | "fatal"
+scope.SetRequest(r *http.Request)
+scope.SetFingerprint([]string{"my-group"})
+scope.AddBreadcrumb(bc, limit)
+scope.ClearBreadcrumbs()
+scope.AddEventProcessor(func(*sentry.Event, *sentry.EventHint) *sentry.Event)
+scope.Clear()
+scope.Clone() *sentry.Scope
+
+// Attributes — attach typed key-value pairs to logs and metrics
+scope.SetAttributes(attribute.String("key", "value"), attribute.Int("count", 42))
+scope.RemoveAttribute("key")
+
+// Removed in sentry-go v0.34.0 — do not use
+// scope.SetExtra("key", value)           // REMOVED — use SetTag / SetContext or SetAttributes
+// scope.SetExtras(map[string]interface{}{})  // REMOVED
+// scope.RemoveExtra("key")               // REMOVED — use RemoveTag / RemoveContext or RemoveAttribute
+```
+
+**Migration from removed Extra APIs (removed in v0.34.0):**
+
+```go
+// Before (removed)
+scope.SetExtra("key.string", "str")
+scope.SetExtra("key.int", 42)
+
+// After — for error events, use tags and contexts:
+scope.SetTag("key.string", "str")
+scope.SetContext("my_data", sentry.Context{"key.int": 42})
+
+// After — for logs and metrics, use attributes:
+scope.SetAttributes(
+    attribute.String("key.string", "str"),
+    attribute.Int("key.int", 42),
+)
+scope.RemoveAttribute("key.string") // replaces RemoveExtra
+```
+
+## Best Practices
+
+- Call `sentry.Init()` once in `main()`, before any goroutines or handlers start
+- Always check the error returned by `sentry.Init()`
+- Always `defer sentry.Flush(2 * time.Second)` in `main()`; call it explicitly before
+  `os.Exit()`
+- Clone the hub before passing it to goroutines: `hub := sentry.CurrentHub().Clone()`
+- Use `WithScope` for one-off context; use `ConfigureScope` for persistent session
+  context
+- Use `SetTag` or `SetContext` for error event data —
+  `SetExtra`/`SetExtras`/`RemoveExtra` were **removed in v0.34.0** and no longer compile
+- Use `SetAttributes` / `RemoveAttribute` to attach typed key-value pairs to logs and
+  metrics (attributes do not appear on error events)
+- Use `BeforeSend` to strip PII — never send raw email/IP unless `SendDefaultPII: true`
+  is intentional
+- Set `MaxErrorDepth` to a sensible value (5–10) for deeply wrapped error chains
+
+## Troubleshooting
+
+| Issue                                  | Solution                                                                       |
+| -------------------------------------- | ------------------------------------------------------------------------------ |
+| Events not appearing                   | Set `Debug: true`; verify DSN; ensure `sentry.Flush()` is called               |
+| Missing stack traces on messages       | Set `AttachStacktrace: true` in `ClientOptions`                                |
+| Goroutine events missing scope data    | Clone hub before goroutine: `sentry.CurrentHub().Clone()`                      |
+| Panics not captured                    | Register framework middleware before handlers; or add `defer sentry.Recover()` |
+| `defer sentry.Flush` not running       | `os.Exit()` skips defers — call `sentry.Flush()` explicitly                    |
+| `SampleRate: 0.0` still sending        | `0.0` is treated as `1.0`; to drop all, set `Dsn: ""`                          |
+| Error chain shows only top error       | Check `MaxErrorDepth`; ensure errors use `%w` or implement `Unwrap()`          |
+| BeforeSend not called for transactions | Use `BeforeSendTransaction` for transaction/performance events                 |