@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,324 @@
+# Sentry Go SDK
+
+Opinionated wizard that scans your Go project and guides you through complete Sentry
+setup.
+
+> **Note:** SDK versions and APIs below reflect Sentry docs at time of writing
+> (sentry-go v0.43.0+). As of v0.33.0+, the SDK requires **Go 1.25 or later** (supports
+> the two most recent Go major versions).
+> Always verify against
+> [docs.sentry.io/platforms/go/](https://docs.sentry.io/platforms/go/) before
+> implementing.
+
+---
+
+## Phase 1: Detect
+
+Run these commands to understand the project before making any recommendations:
+
+```bash
+# Check existing Sentry dependency
+grep -i sentry go.mod 2>/dev/null
+
+# Detect web framework
+grep -E "gin-gonic/gin|labstack/echo|gofiber/fiber|valyala/fasthttp|kataras/iris|urfave/negroni" go.mod 2>/dev/null
+
+# Detect gRPC
+grep "google.golang.org/grpc" go.mod 2>/dev/null
+
+# Detect logging libraries
+grep -E "sirupsen/logrus|go.uber.org/zap|rs/zerolog|log/slog" go.mod go.sum 2>/dev/null
+
+# Detect cron / scheduler patterns
+grep -E "robfig/cron|go-co-op/gocron|jasonlvhit/gocron" go.mod 2>/dev/null
+
+# Detect OpenTelemetry usage
+grep "go.opentelemetry.io" go.mod 2>/dev/null
+
+# Check for companion frontend
+ls frontend/ web/ client/ ui/ 2>/dev/null
+```
+
+**What to note:**
+
+- Is `sentry-go` already in `go.mod`? If yes, skip to Phase 2 (configure features).
+- Which framework is used?
+  (Determines which sub-package and middleware to install.)
+- Which logging library?
+  (Enables automatic log capture.)
+- Are cron/scheduler patterns present?
+  (Triggers Crons recommendation.)
+- Is there a companion frontend directory?
+  (Triggers Phase 4 cross-link.)
+
+---
+
+## Phase 2: Recommend
+
+Based on what you found, present a concrete recommendation.
+Don’t ask open-ended questions — lead with a proposal:
+
+**Recommended (core coverage):**
+
+- ✅ **Error Monitoring** — always; captures panics and unhandled errors
+- ✅ **Tracing** — if HTTP handlers, gRPC, or DB calls are detected
+- ✅ **Logging** — if logrus, zap, zerolog, or slog is detected
+
+**Optional (enhanced observability):**
+
+- ⚡ **Metrics** — custom counters and gauges for business KPIs / SLOs
+- ⚡ **Crons** — detect silent failures in scheduled jobs
+- ⚠️ **Profiling** — removed in sentry-go v0.31.0; see `./profiling.md` for alternatives
+
+**Recommendation logic:**
+
+| Feature          | Recommend when …                                                   |
+| ---------------- | ------------------------------------------------------------------ |
+| Error Monitoring | **Always** — non-negotiable baseline                               |
+| Tracing          | `net/http`, gin, echo, fiber, gRPC, or DB calls detected           |
+| Logging          | logrus, zap, zerolog, or `log/slog` imports detected               |
+| Metrics          | Business events, SLO tracking, or counters needed                  |
+| Crons            | `robfig/cron`, `gocron`, or scheduled job patterns detected        |
+| Profiling        | ⚠️ **Removed in v0.31.0** — do not recommend; see `./profiling.md` |
+
+Propose: _“I recommend setting up Error Monitoring + Tracing [+ Logging if applicable].
+Want me to also add Metrics or Crons?”_
+
+---
+
+## Phase 3: Guide
+
+### Install
+
+```bash
+# Core SDK (always required)
+go get github.com/getsentry/sentry-go
+
+# Framework sub-package — install only what matches detected framework:
+go get github.com/getsentry/sentry-go/http      # net/http
+go get github.com/getsentry/sentry-go/gin       # Gin
+go get github.com/getsentry/sentry-go/echo      # Echo
+go get github.com/getsentry/sentry-go/fiber     # Fiber
+go get github.com/getsentry/sentry-go/fasthttp  # FastHTTP
+
+# Logging sub-packages — install only what matches detected logging lib:
+go get github.com/getsentry/sentry-go/logrus    # Logrus
+go get github.com/getsentry/sentry-go/slog      # slog (stdlib, Go 1.21+)
+go get github.com/getsentry/sentry-go/zap       # Zap
+go get github.com/getsentry/sentry-go/zerolog   # Zerolog
+
+# gRPC interceptors (only if google.golang.org/grpc is detected):
+go get github.com/getsentry/sentry-go/grpc
+
+# OpenTelemetry bridge (only if OTel is already in use):
+go get github.com/getsentry/sentry-go/otel
+```
+
+### Quick Start — Recommended Init
+
+Add to `main()` before any other code.
+This config enables the most features with sensible defaults:
+
+```go
+import (
+    "log"
+    "os"
+    "time"
+    "github.com/getsentry/sentry-go"
+)
+
+err := sentry.Init(sentry.ClientOptions{
+    Dsn:              os.Getenv("SENTRY_DSN"),
+    Environment:      os.Getenv("SENTRY_ENVIRONMENT"), // "production", "staging", etc.
+    Release:          release,                          // inject via -ldflags at build time
+    SendDefaultPII:   true,
+    AttachStacktrace: true,
+
+    // Tracing (adjust sample rate for production)
+    EnableTracing:    true,
+    TracesSampleRate: 1.0, // lower to 0.1–0.2 in high-traffic production
+
+    // Logs
+    EnableLogs: true,
+})
+if err != nil {
+    log.Fatalf("sentry.Init: %s", err)
+}
+defer sentry.Flush(2 * time.Second)
+```
+
+**Injecting `Release` at build time (recommended):**
+
+```go
+var release string // set by -ldflags
+
+// go build -ldflags="-X main.release=my-app@$(git describe --tags)"
+```
+
+### Framework Middleware
+
+After `sentry.Init`, register the Sentry middleware for your framework:
+
+| Framework  | Import path              | Middleware call                      | `Repanic` | `WaitForDelivery` |
+| ---------- | ------------------------ | ------------------------------------ | --------- | ----------------- |
+| `net/http` | `.../sentry-go/http`     | `sentryhttp.New(opts).Handle(h)`     | `true`    | `false`           |
+| Gin        | `.../sentry-go/gin`      | `router.Use(sentrygin.New(opts))`    | `true`    | `false`           |
+| Echo       | `.../sentry-go/echo`     | `e.Use(sentryecho.New(opts))`        | `true`    | `false`           |
+| Fiber      | `.../sentry-go/fiber`    | `app.Use(sentryfiber.New(opts))`     | `false`   | `true`            |
+| FastHTTP   | `.../sentry-go/fasthttp` | `sentryfasthttp.New(opts).Handle(h)` | `false`   | `true`            |
+| Iris       | `.../sentry-go/iris`     | `app.Use(sentryiris.New(opts))`      | `true`    | `false`           |
+| Negroni    | `.../sentry-go/negroni`  | `n.Use(sentrynegroni.New(opts))`     | `true`    | `false`           |
+
+> **Note:** Fiber and FastHTTP are built on `valyala/fasthttp` which has no built-in
+> recovery. Use `Repanic: false, WaitForDelivery: true` for those.
+
+**Hub access in handlers:**
+
+```go
+// net/http, Negroni:
+hub := sentry.GetHubFromContext(r.Context())
+
+// Gin:
+hub := sentrygin.GetHubFromContext(c)
+
+// Echo:
+hub := sentryecho.GetHubFromContext(c)
+
+// Fiber:
+hub := sentryfiber.GetHubFromContext(c)
+```
+
+### gRPC Integration
+
+For gRPC servers and clients, use the `sentrygrpc` interceptors instead:
+
+```go
+import sentrygrpc "github.com/getsentry/sentry-go/grpc"
+
+// Server: register interceptors when creating the gRPC server
+server := grpc.NewServer(
+    grpc.UnaryInterceptor(sentrygrpc.UnaryServerInterceptor()),
+    grpc.StreamInterceptor(sentrygrpc.StreamServerInterceptor()),
+)
+
+// Client: register interceptors when dialing
+conn, err := grpc.NewClient(
+    address,
+    grpc.WithUnaryInterceptor(sentrygrpc.UnaryClientInterceptor()),
+    grpc.WithStreamInterceptor(sentrygrpc.StreamClientInterceptor()),
+)
+
+// Hub access inside a gRPC handler:
+hub := sentry.GetHubFromContext(ctx)
+```
+
+### For Each Agreed Feature
+
+Walk through features one at a time.
+Load the reference file for each, follow its steps, and verify before moving to the
+next:
+
+| Feature          | Reference file          | Load when …                                                                                                   |
+| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Error Monitoring | `./error-monitoring.md` | Always (baseline)                                                                                             |
+| Tracing          | `./tracing.md`          | HTTP handlers / distributed tracing                                                                           |
+| Profiling        | `./profiling.md`        | ⚠️ Not available — removed in v0.31.0; do not set up. Read the file only for pprof / third-party alternatives |
+| Logging          | `./logging.md`          | logrus / zap / zerolog / slog detected                                                                        |
+| Metrics          | `./metrics.md`          | Business KPIs / SLO tracking                                                                                  |
+| Crons            | `./crons.md`            | Scheduler / cron job patterns detected                                                                        |
+
+For each feature: `Read ./<feature>.md`, follow steps exactly, verify it works.
+
+---
+
+## Configuration Reference
+
+### Key `ClientOptions` Fields
+
+| Option                  | Type            | Default | Purpose                                          |
+| ----------------------- | --------------- | ------- | ------------------------------------------------ |
+| `Dsn`                   | `string`        | `""`    | SDK disabled if empty; env: `SENTRY_DSN`         |
+| `Environment`           | `string`        | `""`    | e.g., `"production"`; env: `SENTRY_ENVIRONMENT`  |
+| `Release`               | `string`        | `""`    | e.g., `"my-app@1.0.0"`; env: `SENTRY_RELEASE`    |
+| `SendDefaultPII`        | `bool`          | `false` | Include IP, request headers                      |
+| `AttachStacktrace`      | `bool`          | `false` | Stack traces on `CaptureMessage` calls           |
+| `SampleRate`            | `float64`       | `1.0`   | Error event sample rate (0.0 treated as 1.0)     |
+| `EnableTracing`         | `bool`          | `false` | Enable performance tracing                       |
+| `TracesSampleRate`      | `float64`       | `0.0`   | Transaction sample rate                          |
+| `TracesSampler`         | `TracesSampler` | `nil`   | Custom per-transaction sampling (overrides rate) |
+| `EnableLogs`            | `bool`          | `false` | Enable Sentry Logs feature                       |
+| `MaxBreadcrumbs`        | `int`           | `100`   | Max breadcrumbs per event                        |
+| `MaxErrorDepth`         | `int`           | `100`   | Max depth for unwrapping error chains            |
+| `Debug`                 | `bool`          | `false` | Verbose SDK debug output                         |
+| `BeforeSend`            | `func`          | `nil`   | Hook to mutate/drop error events                 |
+| `BeforeSendTransaction` | `func`          | `nil`   | Hook to mutate/drop transaction events           |
+| `IgnoreErrors`          | `[]string`      | `nil`   | Regex patterns for errors to drop                |
+| `IgnoreTransactions`    | `[]string`      | `nil`   | Regex patterns for transactions to drop          |
+
+### Environment Variables
+
+| Variable                     | Maps to                    | Purpose                            |
+| ---------------------------- | -------------------------- | ---------------------------------- |
+| `SENTRY_DSN`                 | `Dsn`                      | Data Source Name                   |
+| `SENTRY_RELEASE`             | `Release`                  | App version (e.g., `my-app@1.0.0`) |
+| `SENTRY_ENVIRONMENT`         | `Environment`              | Deployment environment             |
+| `HTTP_PROXY` / `HTTPS_PROXY` | `HTTPProxy` / `HTTPSProxy` | Outbound proxy                     |
+
+Options set in `ClientOptions` **override** environment variables.
+
+---
+
+## Verification
+
+Test that Sentry is receiving events:
+
+```go
+// In a handler or test — triggers a real error event:
+sentry.CaptureMessage("Sentry Go SDK test")
+
+// Or trigger a captured panic (with recovery middleware in place):
+panic("sentry test panic")
+```
+
+Check the Sentry dashboard within a few seconds.
+If nothing appears:
+
+1. Set `Debug: true` in `ClientOptions` — prints SDK internals to stdout
+2. Verify the DSN is correct and the project exists
+3. Ensure `sentry.Flush(2 * time.Second)` is called (events are async by default)
+
+---
+
+## Phase 4: Cross-Link
+
+After completing Go setup, check for a companion frontend missing Sentry coverage:
+
+```bash
+ls frontend/ web/ client/ ui/ 2>/dev/null
+cat frontend/package.json web/package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'
+```
+
+If a frontend directory exists without Sentry configured, suggest the matching skill:
+
+| Frontend detected  | Suggest skill                                                                                                                      |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| React / Next.js    | [`react`](../react/index.md)                                                                                                       |
+| Svelte / SvelteKit | [`svelte`](../svelte/index.md)                                                                                                     |
+| Vue                | Use `@sentry/vue` — see [docs.sentry.io/platforms/javascript/guides/vue/](https://docs.sentry.io/platforms/javascript/guides/vue/) |
+| Other JS/TS        | [`react`](../react/index.md) (covers generic browser JS patterns)                                                                  |
+
+---
+
+## Troubleshooting
+
+| Issue                                | Solution                                                                                      |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| Events not appearing                 | Set `Debug: true`, check DSN, verify `sentry.Flush()` is called                               |
+| `sentry.Init` returns error          | Malformed DSN — check format: `https://<key>@o<org>.ingest.sentry.io/<project>`               |
+| Panics not captured                  | Ensure framework middleware is registered before handlers                                     |
+| `defer sentry.Flush` not running     | `os.Exit()` skips `defer` — call `sentry.Flush()` explicitly before `os.Exit()`               |
+| Missing stack traces                 | Set `AttachStacktrace: true` for `CaptureMessage`; works automatically for `CaptureException` |
+| Goroutine events missing context     | Clone hub before spawning goroutine: `hub := sentry.CurrentHub().Clone()`                     |
+| Too many transactions                | Lower `TracesSampleRate` or use `TracesSampler` to drop health checks / metrics endpoints     |
+| Fiber/FastHTTP not recovering        | Use `Repanic: false, WaitForDelivery: true` for fasthttp-based frameworks                     |
+| `SampleRate: 0.0` sending all events | `0.0` is treated as `1.0`; to drop all, set `Dsn: ""` instead                                 |

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

@@ -0,0 +1,354 @@
+# Logging — Sentry Go SDK
+
+> Minimum SDK: `github.com/getsentry/sentry-go` v0.33.0+\
+> Minimum SDK for zap integration: v0.43.0+
+
+## Configuration
+
+Enable Sentry Logs in `sentry.Init`:
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn:        os.Getenv("SENTRY_DSN"),
+    EnableLogs: true, // REQUIRED — logs are off by default
+})
+```
+
+| Option          | Type              | Default | Purpose                                   |
+| --------------- | ----------------- | ------- | ----------------------------------------- |
+| `EnableLogs`    | `bool`            | `false` | Enable Sentry Logs feature                |
+| `BeforeSendLog` | `func(*Log) *Log` | `nil`   | Mutate or drop log entries before sending |
+
+> If `EnableLogs` is `false`, `sentry.NewLogger(ctx)` returns a **no-op logger** — all
+> calls are silently discarded.
+
+## Code Examples
+
+### Native Sentry logger
+
+```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"),
+        EnableLogs: true,
+    })
+    defer sentry.Flush(2 * time.Second)
+
+    ctx := context.Background()
+    logger := sentry.NewLogger(ctx)
+
+    // Basic logging
+    logger.Info().Emit("server started")
+    logger.Warn().Emitf("queue depth: %d", 42)
+    logger.Error().Emit("database connection lost")
+
+    // Per-entry attributes (chained, non-persistent)
+    logger.Info().
+        String("request.id", "abc-123").
+        Int("status.code", 200).
+        Bool("cache.hit", true).
+        Float64("latency.ms", 12.3).
+        Emitf("request completed: %s", r.URL.Path)
+
+    // Permanent logger-level attributes (all subsequent entries include these)
+    logger.SetAttributes(
+        attribute.String("service", "payment-api"),
+        attribute.String("version", "2.1.0"),
+    )
+
+    // Switch context on a single entry (for trace correlation)
+    logger.Info().WithCtx(requestCtx).Emit("handling request")
+}
+```
+
+### Log levels
+
+| Method            | OTel Severity | Use for                              |
+| ----------------- | ------------- | ------------------------------------ |
+| `logger.Trace()`  | 1             | Very detailed debugging              |
+| `logger.Debug()`  | 5             | Development debugging                |
+| `logger.Info()`   | 9             | Informational events                 |
+| `logger.Warn()`   | 13            | Warnings, recoverable issues         |
+| `logger.Error()`  | 17            | Errors requiring attention           |
+| `logger.Fatal()`  | 21            | Fatal — logs then calls `os.Exit(1)` |
+| `logger.Panic()`  | 21            | Fatal — logs then panics             |
+| `logger.LFatal()` | 21            | Logs at fatal level without exiting  |
+
+### BeforeSendLog — filtering logs
+
+```go
+sentry.Init(sentry.ClientOptions{
+    Dsn:        os.Getenv("SENTRY_DSN"),
+    EnableLogs: true,
+    BeforeSendLog: func(log *sentry.Log) *sentry.Log {
+        // Drop trace and debug logs
+        if log.Severity <= sentry.LogSeverityDebug {
+            return nil
+        }
+        // Drop logs from noisy subsystem
+        if v, ok := log.Attributes["service"]; ok && v.String() == "health-checker" {
+            return nil
+        }
+        return log
+    },
+})
+```
+
+`sentry.Log` struct fields: `Timestamp`, `TraceID`, `SpanID`, `Level`, `Severity` (int),
+`Body`, `Attributes`.
+
+### Auto-attached attributes
+
+The SDK automatically appends these to every log entry:
+
+| Attribute                            | Source                                        |
+| ------------------------------------ | --------------------------------------------- |
+| `sentry.release`                     | `ClientOptions.Release`                       |
+| `sentry.environment`                 | `ClientOptions.Environment`                   |
+| `sentry.server.address`              | `ClientOptions.ServerName` or `os.Hostname()` |
+| `sentry.sdk.name` / `.version`       | SDK identifier                                |
+| `sentry.message.template`            | Set when `Emitf()` is used                    |
+| `sentry.message.parameters.0`, `.1`… | Parameters passed to `Emitf()`                |
+| `user.id`, `user.name`, `user.email` | Set if user is in scope                       |
+
+## Logging Integrations
+
+### Logrus
+
+```bash
+go get github.com/getsentry/sentry-go/logrus
+```
+
+Two hook modes — use them independently or together:
+
+```go
+import (
+    "github.com/sirupsen/logrus"
+    "github.com/getsentry/sentry-go"
+    sentrylogrus "github.com/getsentry/sentry-go/logrus"
+)
+
+logger := logrus.New()
+
+// Log hook: sends logrus entries as Sentry Log entries (requires EnableLogs: true)
+logHook, _ := sentrylogrus.NewLogHook(
+    []logrus.Level{logrus.InfoLevel, logrus.WarnLevel},
+    sentry.ClientOptions{Dsn: os.Getenv("SENTRY_DSN"), EnableLogs: true},
+)
+defer logHook.Flush(5 * time.Second)
+
+// Event hook: sends logrus entries as Sentry Events (issues/errors)
+eventHook, _ := sentrylogrus.NewEventHook(
+    []logrus.Level{logrus.ErrorLevel, logrus.FatalLevel, logrus.PanicLevel},
+    sentry.ClientOptions{Dsn: os.Getenv("SENTRY_DSN")},
+)
+defer eventHook.Flush(5 * time.Second)
+
+logger.AddHook(logHook)
+logger.AddHook(eventHook)
+
+// Flush before os.Exit on logger.Fatal()
+logrus.RegisterExitHandler(func() {
+    logHook.Flush(5 * time.Second)
+    eventHook.Flush(5 * time.Second)
+})
+
+logger.Info("service started")
+logger.WithField("user", sentry.User{ID: "u1"}).Error("payment failed")
+```
+
+**Logrus level mapping:**
+
+| Logrus level | Sentry level |
+| ------------ | ------------ |
+| Trace, Debug | `debug`      |
+| Info         | `info`       |
+| Warn         | `warning`    |
+| Error        | `error`      |
+| Fatal, Panic | `fatal`      |
+
+**Special field names** (auto-mapped to Sentry metadata):
+
+| Field           | Type            | Maps to              |
+| --------------- | --------------- | -------------------- |
+| `"request"`     | `*http.Request` | `sentry.Request`     |
+| `"user"`        | `sentry.User`   | scope user           |
+| `"transaction"` | `string`        | event transaction ID |
+| `"fingerprint"` | `[]string`      | event fingerprint    |
+
+### slog (Go 1.21+)
+
+```bash
+go get github.com/getsentry/sentry-go/slog
+```
+
+```go
+import (
+    "context"
+    "log/slog"
+    "github.com/getsentry/sentry-go"
+    sentryslog "github.com/getsentry/sentry-go/slog"
+)
+
+sentry.Init(sentry.ClientOptions{
+    Dsn:        os.Getenv("SENTRY_DSN"),
+    EnableLogs: true,
+})
+defer sentry.Flush(5 * time.Second)
+
+ctx := context.Background()
+handler := sentryslog.Option{
+    // These levels are sent as Sentry Events (issues)
+    EventLevel: []slog.Level{slog.LevelError, sentryslog.LevelFatal},
+    // These levels are sent as Sentry Log entries
+    LogLevel: []slog.Level{slog.LevelInfo, slog.LevelWarn, slog.LevelError},
+    AddSource: true, // include file:line in events
+}.NewSentryHandler(ctx)
+
+logger := slog.New(handler)
+logger.Info("server started", "port", 8080)
+logger.Warn("rate limit approaching", "requests", 950)
+logger.Error("database connection failed", "host", "db.example.com")
+```
+
+**slog level mapping:**
+
+| slog.Level range      | Sentry method |
+| --------------------- | ------------- |
+| `< -4`                | `Trace`       |
+| `-4` to `-1`          | `Debug`       |
+| `0` to `3`            | `Info`        |
+| `4` to `7`            | `Warn`        |
+| `8` to `11`           | `Error`       |
+| `≥ 12` (`LevelFatal`) | `Fatal`       |
+
+`sentryslog.LevelFatal` is defined as `slog.Level(12)`.
+
+### zerolog
+
+```bash
+go get github.com/getsentry/sentry-go/zerolog
+```
+
+> **Note:** The zerolog integration sends as **Sentry Events** (issues), not Sentry Log
+> entries. It does not support structured logs.
+
+```go
+import (
+    "github.com/rs/zerolog"
+    "github.com/getsentry/sentry-go"
+    sentryzerolog "github.com/getsentry/sentry-go/zerolog"
+)
+
+writer, _ := sentryzerolog.New(sentryzerolog.Config{
+    ClientOptions: sentry.ClientOptions{Dsn: os.Getenv("SENTRY_DSN")},
+    Options: sentryzerolog.Options{
+        Levels:          []zerolog.Level{zerolog.ErrorLevel, zerolog.FatalLevel},
+        WithBreadcrumbs: true,  // non-error logs become breadcrumbs
+        FlushTimeout:    3 * time.Second,
+    },
+})
+defer writer.Close()
+
+logger := zerolog.New(writer).With().Timestamp().Logger()
+logger.Info().Msg("breadcrumb only")
+logger.Error().Str("user", "u1").Msg("captured as Sentry event")
+```
+
+**Special field names** (same as logrus, auto-mapped): `"request"` → `*http.Request`,
+`"user"` → `sentry.User`, `"transaction"` → string, `"fingerprint"` → `[]string`
+
+### zap (v0.43.0+)
+
+```bash
+go get github.com/getsentry/sentry-go/zap
+```
+
+```go
+import (
+    "context"
+    "github.com/getsentry/sentry-go"
+    sentryzap "github.com/getsentry/sentry-go/zap"
+    "go.uber.org/zap"
+    "go.uber.org/zap/zapcore"
+    "os"
+)
+
+sentry.Init(sentry.ClientOptions{
+    Dsn:        os.Getenv("SENTRY_DSN"),
+    EnableLogs: true,
+})
+defer sentry.Flush(2 * time.Second)
+
+ctx := context.Background()
+sentryCore := sentryzap.NewSentryCore(ctx, sentryzap.Option{
+    Level:     []zapcore.Level{zapcore.InfoLevel, zapcore.WarnLevel, zapcore.ErrorLevel},
+    AddCaller: true,
+})
+
+// Tee with console output
+consoleCore := zapcore.NewCore(
+    zapcore.NewConsoleEncoder(zap.NewProductionEncoderConfig()),
+    zapcore.AddSync(os.Stdout),
+    zapcore.DebugLevel,
+)
+logger := zap.New(zapcore.NewTee(consoleCore, sentryCore), zap.AddCaller())
+
+// Attach trace context to log entries
+span := sentry.StartSpan(ctx, "my-operation")
+defer span.Finish()
+logger.With(sentryzap.Context(span.Context())).Info("within span",
+    zap.String("version", "1.0"),
+    zap.Float64("cpu", 0.42),
+)
+```
+
+**zap level mapping:**
+
+| zap level     | Sentry method                                |
+| ------------- | -------------------------------------------- |
+| Debug         | `Debug`                                      |
+| Info          | `Info`                                       |
+| Warn          | `Warn`                                       |
+| Error, DPanic | `Error`                                      |
+| Panic, Fatal  | `LFatal` (zap handles the actual exit/panic) |
+
+## Integration Comparison
+
+| Library             | Package             | Sends as                    | `EnableLogs` required |
+| ------------------- | ------------------- | --------------------------- | --------------------- |
+| Native              | `sentry-go`         | Sentry Logs                 | ✅ Yes                |
+| logrus (log hook)   | `sentry-go/logrus`  | Sentry Logs                 | ✅ Yes                |
+| logrus (event hook) | `sentry-go/logrus`  | Sentry Events               | ❌ No                 |
+| slog                | `sentry-go/slog`    | Both (configurable)         | ✅ For logs           |
+| zerolog             | `sentry-go/zerolog` | Sentry Events + Breadcrumbs | ❌ No                 |
+| zap                 | `sentry-go/zap`     | Sentry Logs                 | ✅ Yes                |
+
+## Best Practices
+
+- Enable both a log hook and an event hook for logrus — logs for visibility, events for
+  alerting
+- For slog, configure `EventLevel` to `[slog.LevelError, LevelFatal]` and `LogLevel` for
+  the rest
+- Call `hook.Flush()` (logrus) or `writer.Close()` (zerolog) before program exit
+- Use `WithCtx(requestCtx)` on log entries inside HTTP handlers for trace correlation
+- Set `sentry.LogSeverityInfo` as the minimum in `BeforeSendLog` to avoid sending noisy
+  debug logs
+
+## Troubleshooting
+
+| Issue                         | Solution                                                              |
+| ----------------------------- | --------------------------------------------------------------------- |
+| Logs not appearing in Sentry  | Ensure `EnableLogs: true` in `ClientOptions`                          |
+| `NewLogger` returns no-op     | `EnableLogs` is false or no client is bound to the hub                |
+| Logrus `Fatal` not flushing   | Register `logrus.RegisterExitHandler` to flush hooks before exit      |
+| zerolog entries not appearing | zerolog sends Events, not Logs — check the Issues section, not Logs   |
+| Logs missing trace context    | Use `logger.Info().WithCtx(spanCtx).Emit(...)` to attach span context |
+| Too many logs in Sentry       | Use `BeforeSendLog` to filter by severity or attribute                |