@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,248 @@
+# Error Monitoring — Sentry Ruby SDK
+
+> Minimum SDK: `sentry-ruby` gem 5.0.0+
+
+## Contents
+
+- [Configuration](#configuration)
+- [Code Examples](#code-examples)
+- [Scope API Reference](#scope-api-reference)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Configuration
+
+Key `Sentry.init` options for error monitoring:
+
+| Option                    | Type      | Default    | Purpose                                       |
+| ------------------------- | --------- | ---------- | --------------------------------------------- |
+| `send_default_pii`        | `Boolean` | `false`    | Include request headers, IP addresses         |
+| `sample_rate`             | `Float`   | `1.0`      | Error event sample rate (0.0–1.0)             |
+| `excluded_exceptions`     | `Array`   | common 4xx | Exception classes to ignore                   |
+| `include_local_variables` | `Boolean` | `false`    | Capture local variables from exception frames |
+| `max_breadcrumbs`         | `Integer` | `100`      | Max breadcrumbs per event                     |
+| `before_send`             | `Lambda`  | `nil`      | Mutate or drop error events before sending    |
+| `before_breadcrumb`       | `Lambda`  | `nil`      | Mutate or drop breadcrumbs                    |
+
+## Code Examples
+
+### Automatic capture
+
+**Rails** (`sentry-rails`): exceptions in controllers, background jobs, and mailers are
+captured automatically — no extra code needed.
+
+**Rack / Sinatra**: register the middleware once and all unhandled exceptions are
+captured:
+
+```ruby
+use Sentry::Rack::CaptureExceptions
+```
+
+### Manual capture
+
+```ruby
+# Capture any exception
+begin
+  risky_operation
+rescue => e
+  Sentry.capture_exception(e)
+  raise  # re-raise if you want normal error handling to continue
+end
+
+# Capture a plain message (no exception)
+Sentry.capture_message("payment gateway unreachable", level: :warning)
+```
+
+### User identification
+
+```ruby
+# Set user context — call in a Rails before_action or Rack middleware
+Sentry.set_user(
+  id: current_user.id,
+  email: current_user.email,
+  username: current_user.username
+)
+
+# Clear the user (e.g., on sign-out)
+Sentry.set_user({})
+```
+
+### Tags, context, and extras
+
+```ruby
+# Tags — indexed, filterable in Sentry search
+Sentry.set_tags(region: "us-east-1", plan: "enterprise")
+
+# Context — structured data attached to events (not indexed)
+Sentry.set_context("order", { id: order.id, total: order.total, currency: "USD" })
+
+# Extras — deprecated; prefer set_context for structured data
+Sentry.set_extras(raw_payload: payload.inspect)
+```
+
+### Isolated scope with `with_scope`
+
+Changes inside `with_scope` are discarded after the block — ideal for one-off enrichment
+without polluting subsequent events:
+
+```ruby
+Sentry.with_scope do |scope|
+  scope.set_tags(component: "checkout", payment_provider: "stripe")
+  scope.set_user(id: order.user_id)
+  Sentry.capture_exception(e)
+end
+# ← scope changes above do NOT affect subsequent events
+```
+
+### Persistent scope with `configure_scope`
+
+```ruby
+Sentry.configure_scope do |scope|
+  scope.set_tags(app_version: APP_VERSION)
+  scope.set_user(id: current_user.id)
+end
+# These values apply to all subsequent events in this request/fiber
+```
+
+### Rails: per-request context via `before_action`
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :set_sentry_context
+
+  private
+
+  def set_sentry_context
+    return unless current_user
+    Sentry.set_user(id: current_user.id, email: current_user.email)
+    Sentry.set_tags(tenant: current_user.account.slug)
+  end
+end
+```
+
+### Breadcrumbs
+
+```ruby
+crumb = Sentry::Breadcrumb.new(
+  category: "auth",
+  message: "User #{user.email} authenticated",
+  level: "info"
+)
+Sentry.add_breadcrumb(crumb)
+```
+
+Automatic breadcrumbs are recorded when `breadcrumbs_logger` is configured:
+
+```ruby
+config.breadcrumbs_logger = [:active_support_logger, :http_logger, :redis_logger]
+```
+
+| Logger                   | Captures                                             |
+| ------------------------ | ---------------------------------------------------- |
+| `:active_support_logger` | Rails controller actions, SQL queries, mailer events |
+| `:http_logger`           | Outbound Net::HTTP requests                          |
+| `:redis_logger`          | Redis commands                                       |
+| `:sentry_logger`         | Ruby `Logger` writes                                 |
+
+### `before_send` hook
+
+```ruby
+Sentry.init do |config|
+  config.before_send = lambda do |event, hint|
+    # Drop ZeroDivisionError
+    if hint[:exception].is_a?(ZeroDivisionError)
+      next nil  # return nil to discard the event
+    end
+
+    # Custom fingerprint for database errors
+    if hint[:exception].is_a?(ActiveRecord::StatementInvalid)
+      event.fingerprint = ["database-error", hint[:exception].message.split("\n").first]
+    end
+
+    # Scrub sensitive fields from the request body
+    event.request&.data&.delete("credit_card_number")
+
+    event
+  end
+end
+```
+
+### Exception filters
+
+```ruby
+config.excluded_exceptions += [
+  "ActionController::RoutingError",
+  "ActiveRecord::RecordNotFound",
+  "Rack::QueryParser::InvalidParameterError"
+]
+```
+
+### Local variable capture
+
+```ruby
+config.include_local_variables = true
+```
+
+Captures local variables from the frames in the exception backtrace.
+Useful for debugging hard-to-reproduce errors.
+Evaluate privacy implications before enabling in production.
+
+### Custom fingerprinting
+
+```ruby
+# One-off — override grouping for a specific capture
+Sentry.with_scope do |scope|
+  scope.set_fingerprint(["database-connection-error"])
+  Sentry.capture_exception(e)
+end
+
+# Extend default grouping in before_send
+config.before_send = lambda do |event, hint|
+  if hint[:exception].is_a?(MyWorker::JobError)
+    event.fingerprint = ["{{ default }}", hint[:exception].job_class]
+  end
+  event
+end
+```
+
+## Scope API Reference
+
+```ruby
+# Shorthand module methods (operate on current scope)
+Sentry.set_user(id:, email:, username:, ip_address:)
+Sentry.set_tags(key: "value")
+Sentry.set_context("key", { field: "value" })
+Sentry.set_extras(key: "value")  # deprecated — prefer set_context
+
+# Scope instance methods (inside with_scope / configure_scope blocks)
+scope.set_tags(key: "value")
+scope.set_user(id: "42", email: "user@example.com")
+scope.set_context("key", { field: "value" })
+scope.set_level(:error)            # :debug | :info | :warning | :error | :fatal
+scope.set_fingerprint(["my-group"])
+scope.clear
+```
+
+## Best Practices
+
+- Call `Sentry.init` in `config/initializers/sentry.rb` (Rails) or at the top of
+  `config.ru` before any middleware
+- Use `Sentry.with_scope` for one-off context; use `configure_scope` for persistent
+  request context
+- Set user in a Rails `before_action` so every exception in that request includes user
+  info
+- Use `excluded_exceptions` to filter out expected 4xx errors and keep signal-to-noise
+  high
+- Enable `include_local_variables` in development/staging; evaluate privacy implications
+  for production
+
+## Troubleshooting
+
+| Issue                                     | Solution                                                                                     |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Events not appearing                      | Set `config.debug = true`; check DSN; ensure `Sentry.init` is called before exceptions occur |
+| Rails exceptions missing                  | Use `sentry-rails` gem — `sentry-ruby` alone does not hook Rails error handlers              |
+| Missing request context                   | Set `config.send_default_pii = true`                                                         |
+| `before_send` not called for transactions | Use `before_send_transaction` for performance events                                         |
+| Error captured but wrong user             | Ensure `set_user` runs in a `before_action` before the exception is raised                   |
+| Noise from routing errors                 | Add `"ActionController::RoutingError"` to `excluded_exceptions`                              |

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

@@ -0,0 +1,297 @@
+# Sentry Ruby SDK
+
+Opinionated wizard that scans the project and guides through complete Sentry setup.
+
+> **Note:** SDK APIs below reflect sentry-ruby v6.6.2. Always verify against
+> [docs.sentry.io/platforms/ruby/](https://docs.sentry.io/platforms/ruby/) before
+> implementing.
+
+---
+
+## Phase 1: Detect
+
+```bash
+# Existing Sentry gems
+grep -i sentry Gemfile 2>/dev/null
+
+# Framework
+grep -iE '\brails\b|\bsinatra\b' Gemfile 2>/dev/null
+
+# Web server — Puma triggers queue time guidance
+grep -iE '\bpuma\b' Gemfile 2>/dev/null
+
+# Background jobs
+grep -iE '\bsidekiq\b|\bresque\b|\bdelayed_job\b' Gemfile 2>/dev/null
+
+# Yabeda metrics framework
+grep -iE '\byabeda\b' Gemfile 2>/dev/null
+
+# Competitor monitoring tools — triggers migration path if found
+grep -iE '\bappsignal\b|\bhoneybadger\b|\bbugsnag\b|\brollbar\b|\bairbrake\b' Gemfile 2>/dev/null
+
+# Scheduled jobs — triggers Crons recommendation
+grep -iE '\bsidekiq-cron\b|\bclockwork\b|\bwhenever\b|\brufus-scheduler\b' Gemfile 2>/dev/null
+grep -rn "Sidekiq::Cron\|Clockwork\|every.*do" config/ lib/ --include="*.rb" 2>/dev/null | head -10
+
+# OpenTelemetry tracing — check for SDK + instrumentations
+grep -iE '\bopentelemetry-sdk\b|\bopentelemetry-instrumentation\b' Gemfile 2>/dev/null
+grep -rn "OpenTelemetry::SDK\.configure\|\.use_all\|\.in_span" config/ lib/ app/ --include="*.rb" 2>/dev/null | head -5
+
+# Existing metric patterns (StatsD, Datadog, Prometheus)
+grep -rE "(statsd|dogstatsd|prometheus|\.gauge|\.histogram|\.increment|\.timing)" \
+  app/ lib/ --include="*.rb" 2>/dev/null | grep -v "_spec\|_test" | head -20
+
+# Companion frontend
+cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'
+```
+
+**Route from what you find:**
+
+- **Competitor detected** (`appsignal`, `honeybadger`, `bugsnag`, `rollbar`, `airbrake`)
+  → load `./migration.md` first; **delete the competitor initializer** as part of
+  migration
+- **Sentry already present** → skip to Phase 2 to configure features
+- **Rails** → use `sentry-rails` + `config/initializers/sentry.rb`
+- **Rack/Sinatra** → `sentry-ruby` + `Sentry::Rack::CaptureExceptions` middleware
+- **Sidekiq** → add `sentry-sidekiq`; recommend Metrics if existing metric patterns
+  found
+- **Yabeda detected** → add `sentry-yabeda`; routes Yabeda metrics to Sentry metrics
+- **Puma detected** → queue time capture is automatic (v6.4.0+), but the reverse proxy
+  must set `X-Request-Start` header; see `./tracing.md` → “Request Queue Time”
+- **OTel tracing detected** (`opentelemetry-sdk` + instrumentations in Gemfile, or
+  `OpenTelemetry::SDK.configure` in source) → use OTLP path:
+  `config.otlp.enabled = true`; do **not** set `traces_sample_rate`; Sentry links errors
+  to OTel traces automatically
+
+---
+
+## Phase 2: Recommend
+
+Lead with a concrete proposal — don’t ask open-ended questions:
+
+| Feature          | Recommend when …                                                                                                                                                            |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error Monitoring | **Always**                                                                                                                                                                  |
+| OTLP Integration | OTel tracing detected — **replaces** native Tracing                                                                                                                         |
+| Tracing          | Rails / Sinatra / Rack / any HTTP framework; **skip if OTel tracing detected**                                                                                              |
+| Logging          | **Always** — `enable_logs: true` costs nothing                                                                                                                              |
+| Metrics          | Sidekiq present; existing metric lib (StatsD, Prometheus) detected                                                                                                          |
+| Profiling        | ⚠️ Beta — performance profiling requested; requires `stackprof` or `vernier` gem; **skip if OTel tracing detected** (requires `traces_sample_rate`, incompatible with OTLP) |
+| Crons            | Scheduled jobs detected (ActiveJob, Sidekiq-Cron, Clockwork, Whenever)                                                                                                      |
+
+**OTel tracing detected:** _“I see OpenTelemetry tracing in the project.
+I recommend Sentry’s OTLP integration for tracing (via your existing OTel setup) + Error
+Monitoring + Sentry Logging [+ Metrics/Crons if applicable]. Shall I proceed?”_
+
+**No OTel:** _“I recommend Error Monitoring + Tracing + Logging
+[+ Metrics if applicable]. Shall I proceed?”_
+
+---
+
+## Phase 3: Guide
+
+### Install
+
+**Rails:**
+
+```ruby
+# Gemfile
+gem "sentry-ruby"
+gem "sentry-rails"
+gem "sentry-sidekiq"      # if using Sidekiq
+gem "sentry-resque"       # if using Resque
+gem "sentry-delayed_job"  # if using DelayedJob
+gem "sentry-yabeda"       # if using Yabeda metrics framework
+```
+
+**Rack / Sinatra / plain Ruby:**
+
+```ruby
+gem "sentry-ruby"
+```
+
+Run `bundle install`.
+
+### Framework Integration
+
+| Framework / Runtime | Gem                  | Init location                        | Auto-instruments                                            |
+| ------------------- | -------------------- | ------------------------------------ | ----------------------------------------------------------- |
+| Rails               | `sentry-rails`       | `config/initializers/sentry.rb`      | Controllers, ActiveRecord, ActiveJob, ActionMailer          |
+| Rack / Sinatra      | `sentry-ruby`        | Top of `config.ru`                   | Requests (via `Sentry::Rack::CaptureExceptions` middleware) |
+| Sidekiq             | `sentry-sidekiq`     | Sentry initializer or Sidekiq config | Worker execution → transactions                             |
+| Resque              | `sentry-resque`      | Sentry initializer                   | Worker execution → transactions                             |
+| DelayedJob          | `sentry-delayed_job` | Sentry initializer                   | Job execution → transactions                                |
+| Yabeda metrics      | `sentry-yabeda`      | Sentry initializer                   | Yabeda metric events → Sentry metrics                       |
+
+### Init — Rails (`config/initializers/sentry.rb`)
+
+```ruby
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.spotlight = Rails.env.development?  # local Spotlight UI; no DSN needed in dev
+  config.breadcrumbs_logger = [:active_support_logger, :http_logger]
+  config.send_default_pii = true
+  config.traces_sample_rate = 1.0  # lower to 0.05–0.2 in production
+  config.enable_logs = true
+  # Metrics on by default; disable with: config.enable_metrics = false
+end
+```
+
+`sentry-rails` auto-instruments ActionController, ActiveRecord, ActiveJob, ActionMailer.
+
+### Init — Rack / Sinatra
+
+```ruby
+require "sentry-ruby"
+
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.spotlight = ENV["RACK_ENV"] == "development"
+  config.breadcrumbs_logger = [:sentry_logger, :http_logger]
+  config.send_default_pii = true
+  config.traces_sample_rate = 1.0
+  config.enable_logs = true
+end
+
+use Sentry::Rack::CaptureExceptions  # in config.ru, before app middleware
+```
+
+### Init — Sidekiq standalone
+
+```ruby
+require "sentry-ruby"
+require "sentry-sidekiq"
+
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.spotlight = ENV.fetch("RAILS_ENV", "development") == "development"
+  config.breadcrumbs_logger = [:sentry_logger]
+  config.traces_sample_rate = 1.0
+  config.enable_logs = true
+end
+```
+
+### Environment variables
+
+```bash
+SENTRY_DSN=https://xxx@oYYY.ingest.sentry.io/ZZZ
+SENTRY_ENVIRONMENT=production   # overrides RAILS_ENV / RACK_ENV
+SENTRY_RELEASE=my-app@1.0.0
+```
+
+### Feature reference files
+
+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 …                                              |
+| ---------------- | ----------------------- | -------------------------------------------------------- |
+| Migration        | `./migration.md`        | Competitor gem found — load **before** installing Sentry |
+| Error Monitoring | `./error-monitoring.md` | Always                                                   |
+| Tracing          | `./tracing.md`          | HTTP handlers / distributed tracing                      |
+| Logging          | `./logging.md`          | Structured log capture                                   |
+| Metrics          | `./metrics.md`          | Sidekiq present; existing metric patterns                |
+| Profiling        | `./profiling.md`        | Performance profiling requested (beta)                   |
+| Crons            | `./crons.md`            | Scheduled jobs detected or requested                     |
+
+For each feature: `Read ./<feature>.md`, follow steps exactly, verify it works.
+
+---
+
+## Configuration Reference
+
+### Key `Sentry.init` Options
+
+| Option                      | Type    | Default | Purpose                                                                                                                                                    |
+| --------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dsn`                       | String  | `nil`   | SDK disabled if empty; env: `SENTRY_DSN`                                                                                                                   |
+| `environment`               | String  | `nil`   | e.g., `"production"`; env: `SENTRY_ENVIRONMENT`                                                                                                            |
+| `release`                   | String  | `nil`   | e.g., `"myapp@1.0.0"`; env: `SENTRY_RELEASE`                                                                                                               |
+| `spotlight`                 | Boolean | `false` | Send events to Spotlight sidecar (local dev, no DSN needed)                                                                                                |
+| `send_default_pii`          | Boolean | `false` | Include IP addresses and request headers                                                                                                                   |
+| `sample_rate`               | Float   | `1.0`   | Error event sample rate (0.0–1.0)                                                                                                                          |
+| `traces_sample_rate`        | Float   | `nil`   | Transaction sample rate; `nil` disables tracing                                                                                                            |
+| `profiles_sample_rate`      | Float   | `nil`   | Profiling rate relative to `traces_sample_rate`; requires `stackprof` or `vernier`                                                                         |
+| `enable_logs`               | Boolean | `false` | Enable Sentry structured Logs                                                                                                                              |
+| `enable_metrics`            | Boolean | `true`  | Enable custom metrics (on by default)                                                                                                                      |
+| `breadcrumbs_logger`        | Array   | `[]`    | Loggers for automatic breadcrumbs (see logging reference)                                                                                                  |
+| `max_breadcrumbs`           | Integer | `100`   | Max breadcrumbs per event                                                                                                                                  |
+| `debug`                     | Boolean | `false` | Verbose SDK output to stdout                                                                                                                               |
+| `capture_queue_time`        | Boolean | `true`  | Record request queue time from `X-Request-Start` header (v6.4.0+, Rails fixed in v6.4.1)                                                                   |
+| `otlp.enabled`              | Boolean | `false` | Route OTel spans to Sentry via OTLP; **do not combine with** `traces_sample_rate`                                                                          |
+| `otlp.collector_url`        | String  | `nil`   | OTLP HTTP endpoint of an OTel Collector (e.g., `http://localhost:4318/v1/traces`); when set, spans are sent to the collector instead of directly to Sentry |
+| `org_id`                    | String  | `nil`   | Explicit org ID; overrides DSN-extracted value; useful for self-hosted/Relay setups (v6.5.0+)                                                              |
+| `strict_trace_continuation` | Boolean | `false` | Only continue incoming traces when `sentry-org_id` baggage matches SDK’s org ID; prevents trace stitching from third-party services (v6.5.0+)              |
+| `before_send`               | Lambda  | `nil`   | Mutate or drop error events before sending                                                                                                                 |
+| `before_send_transaction`   | Lambda  | `nil`   | Mutate or drop transaction events before sending                                                                                                           |
+| `before_send_log`           | Lambda  | `nil`   | Mutate or drop log events before sending                                                                                                                   |
+
+### 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             |
+
+Options set in `Sentry.init` override environment variables.
+
+---
+
+## Verification
+
+**Local dev (no DSN needed) — Spotlight:**
+
+```bash
+npx @spotlightjs/spotlight          # browser UI at http://localhost:8969
+# or stream events to terminal:
+npx @spotlightjs/spotlight tail traces --format json
+```
+
+`config.spotlight = Rails.env.development?` (already in the init block above) routes
+events to the local sidecar automatically.
+
+**With a real DSN:**
+
+```ruby
+Sentry.capture_message("Sentry Ruby SDK test")
+```
+
+Nothing appears? Set `config.debug = true` and check stdout.
+Verify DSN format: `https://<key>@o<org>.ingest.sentry.io/<project>`.
+
+---
+
+## Phase 4: Cross-Link
+
+```bash
+cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'
+```
+
+| Frontend detected  | Suggest                                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| React / Next.js    | [`react`](../react/index.md)                                                                                               |
+| Svelte / SvelteKit | [`svelte`](../svelte/index.md)                                                                                             |
+| Vue                | `@sentry/vue` — [docs.sentry.io/platforms/javascript/guides/vue/](https://docs.sentry.io/platforms/javascript/guides/vue/) |
+
+For trace stitching between Ruby backend and JS frontend, see `./tracing.md` → “Frontend
+trace stitching”.
+
+---
+
+## Troubleshooting
+
+| Issue                               | Solution                                                                                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Events not appearing                | `config.debug = true`; verify DSN; ensure `Sentry.init` before first request                                                                      |
+| Rails exceptions missing            | Must use `sentry-rails` — `sentry-ruby` alone doesn’t hook Rails error handlers                                                                   |
+| No traces (native)                  | Set `traces_sample_rate > 0`; ensure `sentry-rails` or `Sentry::Rack::CaptureExceptions`                                                          |
+| No traces (OTLP)                    | Verify `opentelemetry-exporter-otlp` gem is installed; do **not** set `traces_sample_rate` when using `otlp.enabled = true`                       |
+| Sidekiq jobs not traced             | Add `sentry-sidekiq` gem                                                                                                                          |
+| Missing request context             | Set `config.send_default_pii = true`                                                                                                              |
+| Logs not appearing                  | Set `config.enable_logs = true`; sentry-ruby ≥ 5.27.0 required                                                                                    |
+| Metrics not appearing               | Check `enable_metrics` is not `false`; verify DSN                                                                                                 |
+| Events lost on shutdown             | `Process.exit!` skips `at_exit` hooks — call `Sentry.flush` explicitly before forced exits                                                        |
+| Forking server loses events         | Puma/Unicorn fork workers — re-initialize in `on_worker_boot` or `after_fork`; without this, the background worker thread dies in child processes |
+| DSN rejected / events not delivered | Verify DSN format: `https://<key>@o<org>.ingest.sentry.io/<project>`; set `config.debug = true` to see transport errors                           |