@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,168 @@
+# Logging — Sentry Ruby SDK
+
+> Minimum SDK: `sentry-ruby` v5.27.0+ Logs are sent as independent events to Sentry Logs
+> — separate from breadcrumbs and error events.
+
+## Contents
+
+- [Configuration](#configuration)
+- [Logging Methods](#logging-methods)
+- [Filtering Logs](#filtering-logs)
+- [Breadcrumb Loggers](#breadcrumb-loggers)
+- [Ruby stdlib Logger integration](#ruby-stdlib-logger-integration)
+- [Rails Logger](#rails-logger)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Configuration
+
+| Option               | Type    | Default | Purpose                                                       |
+| -------------------- | ------- | ------- | ------------------------------------------------------------- |
+| `enable_logs`        | Boolean | `false` | Enable Sentry structured Logs — must be `true`                |
+| `before_send_log`    | Lambda  | `nil`   | Mutate or drop log events before sending                      |
+| `breadcrumbs_logger` | Array   | `[]`    | Loggers for automatic breadcrumbs (separate from Sentry Logs) |
+
+```ruby
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.enable_logs = true  # required — disabled by default
+end
+```
+
+## Logging Methods
+
+`Sentry.logger` provides six levels:
+
+```ruby
+Sentry.logger.trace("entering payment flow")
+Sentry.logger.debug("cache miss for key: %{key}", key: cache_key)
+Sentry.logger.info("User %{name} logged in", name: user.email)
+Sentry.logger.warn("Retry %{attempt} of %{max}", attempt: 3, max: 5)
+Sentry.logger.error("Payment failed: %{message}", message: e.message)
+Sentry.logger.fatal("Database unreachable — shutting down")
+```
+
+### Parameterized messages
+
+Use `%{key}` named parameters.
+Parameters are sent as structured attributes, enabling filtering and aggregation in
+Sentry:
+
+```ruby
+# Named parameters (preferred)
+Sentry.logger.info(
+  "Order %{order_id} placed for %{amount}",
+  order_id: order.id,
+  amount: order.total
+)
+
+# Positional parameters
+Sentry.logger.info("Order %s placed", [order.id])
+```
+
+### Extra attributes
+
+Pass keyword arguments beyond the message to attach searchable data:
+
+```ruby
+Sentry.logger.error(
+  "Failed to process payment for order %{order_id}",
+  order_id: order.id,
+  amount: order.total,
+  payment_provider: "stripe",
+  error_code: stripe_error.code
+)
+```
+
+## Filtering Logs
+
+```ruby
+config.before_send_log = lambda do |log|
+  # Drop debug-level logs in production
+  return nil if log.level == :debug
+
+  # Scrub sensitive content
+  log.message = log.message.gsub(/token=\S+/, "token=[FILTERED]")
+
+  log
+end
+```
+
+### `before_send_log` parameter
+
+The `log` argument passed to the callback exposes:
+
+| Property     | Type   | Description                                              |
+| ------------ | ------ | -------------------------------------------------------- |
+| `level`      | Symbol | `:trace`, `:debug`, `:info`, `:warn`, `:error`, `:fatal` |
+| `message`    | String | The formatted log message                                |
+| `body`       | String | Raw template string (e.g., `"Order %{order_id} placed"`) |
+| `attributes` | Hash   | Structured parameters passed as keyword arguments        |
+
+## Breadcrumb Loggers
+
+Breadcrumbs are different from Sentry Logs — they are attached to the next error event,
+not sent independently.
+See `error-monitoring.md` for the full logger table and configuration options.
+
+```ruby
+config.breadcrumbs_logger = [:active_support_logger, :http_logger, :redis_logger, :sentry_logger]
+```
+
+### Filtering breadcrumbs
+
+```ruby
+config.before_breadcrumb = lambda do |breadcrumb, hint|
+  # Drop Redis noise in high-traffic environments
+  return nil if breadcrumb.category == "redis"
+  breadcrumb
+end
+```
+
+## Ruby stdlib Logger integration
+
+Capture writes from existing Ruby `Logger` instances as Sentry breadcrumbs.
+This requires enabling the `:logger` patch first — without it `std_lib_logger_filter` is
+never called:
+
+```ruby
+config.breadcrumbs_logger = [:sentry_logger]
+config.enabled_patches << :logger   # required — activates the Logger patch
+
+# Optional: filter by severity
+config.std_lib_logger_filter = proc do |logger, message, severity|
+  [:error, :fatal].include?(severity)
+end
+```
+
+## Rails Logger
+
+In Rails, `Rails.logger` writes automatically appear as breadcrumbs when
+`:active_support_logger` is enabled — no extra configuration needed.
+
+To also send key Rails log lines as Sentry Logs (not just breadcrumbs), call
+`Sentry.logger` explicitly alongside your existing logging:
+
+```ruby
+Rails.logger.error("Payment failed: #{e.message}")
+Sentry.logger.error("Payment failed: %{message}", message: e.message)
+```
+
+## Best Practices
+
+- Always use parameterized messages (`%{key}` syntax) rather than string interpolation —
+  this enables structured log aggregation and search in Sentry
+- Use `Sentry.logger` for observability-grade messages (errors, key business events);
+  let high-volume debug logging stay local
+- Set `before_send_log` to drop `:trace` and `:debug` levels in production
+- Combine `Sentry.logger.error(...)` with `Sentry.capture_exception(e)` for errors — the
+  log provides context, the exception provides the stack trace
+
+## Troubleshooting
+
+| Issue                              | Solution                                                                                  |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| Logs not appearing in Sentry       | Set `config.enable_logs = true`; verify `sentry-ruby` ≥ 5.27.0                            |
+| Breadcrumbs not attached to events | Check `breadcrumbs_logger` includes the right symbol for your stack                       |
+| `Sentry.logger` call crashes       | Ensure `Sentry.init` was called before `Sentry.logger` is accessed                        |
+| High log volume                    | Use `before_send_log` to filter by level; set `:debug` and `:trace` to drop in production |

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

@@ -0,0 +1,196 @@
+# Metrics — Sentry Ruby SDK
+
+> Minimum SDK: `sentry-ruby` v6.3.0+ Metrics are enabled by default
+> (`config.enable_metrics = true`). The v6.3.0 release replaced the beta `increment` API
+> with `count`.
+
+## Contents
+
+- [Configuration](#configuration)
+- [Metric Types](#metric-types)
+- [Unit Reference](#unit-reference)
+- [Sidekiq Metrics](#sidekiq-metrics)
+- [Detecting Existing Metric Patterns](#detecting-existing-metric-patterns)
+- [`before_send_metric` Hook](#before_send_metric-hook)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Configuration
+
+```ruby
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  # Metrics on by default. To filter or enrich before sending:
+  config.before_send_metric = lambda do |metric|
+    return nil if metric.name.start_with?("internal.")
+    metric.attributes[:environment] ||= Rails.env
+    metric
+  end
+end
+```
+
+## Metric Types
+
+### Counter — occurrence counts
+
+```ruby
+Sentry.metrics.count("api.requests", attributes: { endpoint: "/orders", status: "200" })
+Sentry.metrics.count("user.signup", attributes: { plan: "pro" })
+```
+
+### Gauge — current value (can go up or down)
+
+```ruby
+Sentry.metrics.gauge("sidekiq.queue.depth", Sidekiq::Stats.new.enqueued)
+Sentry.metrics.gauge("cache.size", Rails.cache.stats[:curr_items])
+```
+
+### Distribution — statistical spread of a value
+
+```ruby
+Sentry.metrics.distribution("http.response_time", duration_ms, unit: "millisecond",
+  attributes: { route: "/api/orders" })
+Sentry.metrics.distribution("db.query_time", query_ms, unit: "millisecond",
+  attributes: { table: "orders" })
+```
+
+## Unit Reference
+
+| Category  | Values                                                                             |
+| --------- | ---------------------------------------------------------------------------------- |
+| Duration  | `"nanosecond"`, `"microsecond"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"` |
+| Data      | `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`                                 |
+| Fractions | `"ratio"`, `"percent"`                                                             |
+| None      | `"none"` (default)                                                                 |
+
+## Sidekiq Metrics
+
+Two complementary approaches cover different aspects of Sidekiq observability:
+
+### Option A — Server middleware (per-job metrics)
+
+A Sidekiq server middleware fires for every job execution — the right tool for job
+duration, throughput, and error rate broken down by queue and worker class.
+
+```ruby
+# lib/sentry_job_metrics.rb
+class SentryJobMetrics
+  def call(worker, job, queue)
+    start = Time.now
+    yield
+    attrs = { queue: queue, worker: worker.class.name }
+    Sentry.metrics.distribution("sidekiq.job.duration",
+      (Time.now - start) * 1000, unit: "millisecond", attributes: attrs)
+    Sentry.metrics.count("sidekiq.job.success", attributes: attrs)
+  rescue => e
+    Sentry.metrics.count("sidekiq.job.failure",
+      attributes: { queue: queue, worker: worker.class.name })
+    raise
+  end
+end
+
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add SentryJobMetrics
+  end
+end
+```
+
+**What this gives you:** `sidekiq.job.duration` (p50/p95/p99 per queue + worker),
+`sidekiq.job.success` and `sidekiq.job.failure` counters.
+
+**What it cannot give you:** queue depth, queue latency (oldest job age), retry/dead
+queue sizes — these are aggregate stats that require polling `Sidekiq::Stats`.
+
+### Option B — Aggregate queue stats (periodic sampling)
+
+For queue depth and latency, poll `Sidekiq::Stats` on a schedule.
+A lightweight background thread or a recurring Sidekiq job both work:
+
+```ruby
+# config/initializers/sentry_sidekiq_stats.rb
+Thread.new do
+  loop do
+    begin
+      stats = Sidekiq::Stats.new
+      Sentry.metrics.gauge("sidekiq.enqueued",  stats.enqueued)
+      Sentry.metrics.gauge("sidekiq.retries",   stats.retry_size)
+      Sentry.metrics.gauge("sidekiq.dead",      stats.dead_size)
+
+      Sidekiq::Queue.all.first(10).each do |q|
+        attrs = { queue: q.name }
+        Sentry.metrics.gauge("sidekiq.queue.depth",   q.size,    attributes: attrs)
+        Sentry.metrics.gauge("sidekiq.queue.latency", q.latency,
+          unit: "second", attributes: attrs)
+      end
+    rescue => e
+      # don't crash the thread on transient Redis errors
+    end
+    sleep 30
+  end
+end
+```
+
+> **Production note:** In forking servers (Puma, Unicorn), start the polling thread in
+> `on_worker_boot` / `after_fork` — threads don’t survive `fork()`. Consider using a
+> Sidekiq periodic job instead of a bare thread for better reliability and error
+> visibility.
+
+**Use both together** for complete Sidekiq visibility: the middleware captures per-job
+detail, the poller captures queue health over time.
+
+## Detecting Existing Metric Patterns
+
+Before adding Sentry metrics, scan for existing instrumentation to migrate or
+complement:
+
+```bash
+# StatsD / Datadog / Prometheus calls
+grep -rE "(statsd|dogstatsd|prometheus|\.gauge|\.distribution|\.histogram|\.increment|\.timing)" \
+  app/ lib/ --include="*.rb" | grep -v "_spec\|_test"
+
+# Sidekiq::Stats usage (shows what's already being tracked)
+grep -rn "Sidekiq::Stats\|Sidekiq::Queue" app/ lib/ --include="*.rb"
+```
+
+## `before_send_metric` Hook
+
+```ruby
+config.before_send_metric = lambda do |metric|
+  return nil if metric.name.start_with?("internal.")
+  metric.attributes.delete(:user_id)  # strip PII
+  metric
+end
+```
+
+`MetricEvent` properties:
+
+| Property     | Type      | Description                              |
+| ------------ | --------- | ---------------------------------------- |
+| `name`       | `String`  | Metric identifier                        |
+| `type`       | `Symbol`  | `:counter`, `:gauge`, or `:distribution` |
+| `value`      | `Numeric` | Measurement value                        |
+| `unit`       | `String?` | Measurement unit                         |
+| `attributes` | `Hash`    | Custom key-value pairs                   |
+| `trace_id`   | `String?` | Auto-linked when inside a transaction    |
+
+## Best Practices
+
+- Use `count` for events, `gauge` for current state, `distribution` for latency/sizes
+- Always set `unit:` on distributions — enables proper chart rendering
+- Use `attributes:` to slice by queue name, route, status code — these become filter
+  dimensions
+- Use `before_send_metric` to strip PII (user IDs, email addresses) from attribute
+  values
+- Metrics emitted inside a Sentry transaction are trace-linked automatically
+
+## Troubleshooting
+
+| Issue                              | Solution                                                                                      |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| Metrics not in Sentry              | Verify `enable_metrics` is not `false`; check DSN                                             |
+| `count` values look wrong          | Sentry diffs lifetime counters — reporting deltas directly avoids confusion                   |
+| `before_send_metric` not filtering | Return `nil`, not `false`, to drop a metric                                                   |
+| Per-job breakdown missing          | Ensure `SentryJobMetrics` middleware is added to `server_middleware`, not `client_middleware` |
+| Queue depth always zero            | Verify the stats polling thread is running; check Redis connectivity                          |

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

@@ -0,0 +1,321 @@
+# Migrating to Sentry — Ruby SDK
+
+> Minimum SDK: `sentry-ruby` v5.0.0+ (Rails: also add `sentry-rails`) Covers migrations
+> from: AppSignal, Honeybadger, Bugsnag, Rollbar, Airbrake
+
+## Contents
+
+- [Step 1: Detect What’s in the Codebase](#step-1-detect-whats-in-the-codebase)
+- [AppSignal → Sentry](#appsignal--sentry)
+- [Honeybadger → Sentry](#honeybadger--sentry)
+- [Bugsnag → Sentry](#bugsnag--sentry)
+- [Rollbar → Sentry](#rollbar--sentry)
+- [Airbrake → Sentry](#airbrake--sentry)
+- [Universal Migration Checklist](#universal-migration-checklist)
+- [Troubleshooting](#troubleshooting)
+
+## Step 1: Detect What’s in the Codebase
+
+```bash
+# Find competitor gems
+grep -iE '\bappsignal\b|\bhoneybadger\b|\bbugsnag\b|\brollbar\b|\bairbrake\b' Gemfile Gemfile.lock 2>/dev/null
+
+# Find call sites across the app
+grep -rn "Appsignal\.\|Honeybadger\.\|Bugsnag\.\|Rollbar\.\|Airbrake\." \
+  app/ lib/ config/ --include="*.rb" | grep -v "_spec\|_test"
+
+# Find config files to remove after migration
+ls config/appsignal.yml \
+   config/honeybadger.yml .honeybadger.yml \
+   config/initializers/bugsnag.rb \
+   config/initializers/rollbar.rb \
+   config/initializers/airbrake.rb 2>/dev/null
+```
+
+---
+
+## AppSignal → Sentry
+
+**Gemfile:**
+
+```ruby
+# Remove:
+gem "appsignal"
+
+# Add:
+gem "sentry-ruby"
+gem "sentry-rails"     # if Rails
+gem "sentry-sidekiq"   # if Sidekiq
+```
+
+**Delete:** `config/appsignal.yml`, `config/initializers/appsignal.rb`
+
+### API mapping
+
+| AppSignal                                     | Sentry                                                                       |
+| --------------------------------------------- | ---------------------------------------------------------------------------- |
+| `Appsignal.report_error(e)`                   | `Sentry.capture_exception(e)`                                                |
+| `Appsignal.send_error(e)`                     | `Sentry.capture_exception(e)`                                                |
+| `Appsignal.set_error(e)`                      | `Sentry.capture_exception(e)`                                                |
+| `Appsignal.listen_for_error { }`              | `begin … rescue => e; Sentry.capture_exception(e); raise; end`               |
+| `Appsignal.tag_request(key: val)`             | `Sentry.set_tags(key: val)`                                                  |
+| `Appsignal.add_tags(key: val)`                | `Sentry.set_tags(key: val)`                                                  |
+| `Appsignal.add_custom_data(hash)`             | `Sentry.set_context("custom", hash)`                                         |
+| `Appsignal.set_action("name")`                | `Sentry.get_current_scope.set_transaction_name("name")`                      |
+| `Appsignal.add_breadcrumb(cat, action, msg)`  | `Sentry.add_breadcrumb(Sentry::Breadcrumb.new(category: cat, message: msg))` |
+| `Appsignal.instrument("name") { }`            | `Sentry.with_child_span(op: "name") { }`                                     |
+| `Appsignal.set_gauge("m", val, tags)`         | `Sentry.metrics.gauge("m", val, attributes: tags)`                           |
+| `Appsignal.increment_counter("m", val, tags)` | `Sentry.metrics.count("m", value: val, attributes: tags)`                    |
+
+### Find call sites
+
+```bash
+grep -rn "Appsignal\.\(report_error\|send_error\|set_error\|listen_for_error\|tag_request\|add_tags\|add_custom_data\|instrument\|set_gauge\|increment_counter\)" \
+  app/ lib/ --include="*.rb"
+```
+
+### Initializer
+
+```ruby
+# config/initializers/sentry.rb
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.breadcrumbs_logger = [:active_support_logger, :http_logger]
+  config.send_default_pii = true
+  config.traces_sample_rate = 1.0
+  config.enable_logs = true
+end
+```
+
+---
+
+## Honeybadger → Sentry
+
+**Gemfile:**
+
+```ruby
+# Remove:
+gem "honeybadger"
+
+# Add:
+gem "sentry-ruby"
+gem "sentry-rails"
+```
+
+**Delete:** `config/honeybadger.yml`, `.honeybadger.yml`,
+`config/initializers/honeybadger.rb`
+
+### API mapping
+
+| Honeybadger                                           | Sentry                                                                                |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `Honeybadger.notify(e)`                               | `Sentry.capture_exception(e)`                                                         |
+| `Honeybadger.notify("message")`                       | `Sentry.capture_message("message")`                                                   |
+| `Honeybadger.notify(e, context: hash)`                | `Sentry.with_scope { \|s\| s.set_context("ctx", hash); Sentry.capture_exception(e) }` |
+| `Honeybadger.context(key: val)`                       | `Sentry.set_tags(key: val)`                                                           |
+| `Honeybadger.context { \|c\| c[:key] = val }`         | `Sentry.configure_scope { \|s\| s.set_context("app", {key: val}) }`                   |
+| `Honeybadger.context.clear!`                          | `Sentry.get_current_scope.clear`                                                      |
+| `Honeybadger.add_breadcrumb(msg, metadata: h)`        | `Sentry.add_breadcrumb(Sentry::Breadcrumb.new(message: msg, data: h))`                |
+| `Honeybadger.exception_filter { \|n\| n.halt! if … }` | `config.before_send = lambda { \|e, _h\| … ? nil : e }`                               |
+
+### Find call sites
+
+```bash
+grep -rn "Honeybadger\.\(notify\|context\|add_breadcrumb\|exception_filter\)" \
+  app/ lib/ --include="*.rb"
+```
+
+---
+
+## Bugsnag → Sentry
+
+**Gemfile:**
+
+```ruby
+# Remove:
+gem "bugsnag"
+
+# Add:
+gem "sentry-ruby"
+gem "sentry-rails"     # if Rails
+gem "sentry-sidekiq"   # if Sidekiq
+```
+
+**Delete:** `config/initializers/bugsnag.rb`
+
+### API mapping
+
+| Bugsnag                                                           | Sentry                                                                                     |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `Bugsnag.notify(e)`                                               | `Sentry.capture_exception(e)`                                                              |
+| `Bugsnag.notify(e) { \|event\| event.severity = "warning" }`      | `Sentry.capture_exception(e, level: :warning)`                                             |
+| `Bugsnag.notify(e) { \|event\| event.add_metadata(:ctx, hash) }`  | `Sentry.with_scope { \|s\| s.set_context("ctx", hash); Sentry.capture_exception(e) }`      |
+| `Bugsnag.notify(e) { \|event\| event.set_user(id, email, name) }` | `Sentry.set_user(id: id, email: email, username: name)`                                    |
+| `Bugsnag.leave_breadcrumb(name, meta, type)`                      | `Sentry.add_breadcrumb(Sentry::Breadcrumb.new(message: name, data: meta, category: type))` |
+| `Bugsnag.add_metadata(:section, hash)`                            | `Sentry.set_context("section", hash)`                                                      |
+| `Bugsnag.configure { \|c\| c.discard_classes << "MyError" }`      | `config.before_send = lambda { \|e, h\| h[:exception].is_a?(MyError) ? nil : e }`          |
+| `event.ignore!` (in on_error callback)                            | Return `nil` from `config.before_send`                                                     |
+
+### Find call sites
+
+```bash
+grep -rn "Bugsnag\.\(notify\|leave_breadcrumb\|add_metadata\|clear_metadata\|start_session\)" \
+  app/ lib/ --include="*.rb"
+```
+
+---
+
+## Rollbar → Sentry
+
+**Gemfile:**
+
+```ruby
+# Remove:
+gem "rollbar"
+
+# Add:
+gem "sentry-ruby"
+gem "sentry-rails"     # if Rails
+gem "sentry-sidekiq"   # if Sidekiq
+```
+
+**Delete:** `config/initializers/rollbar.rb`
+
+### API mapping
+
+| Rollbar                         | Sentry                                                                                                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Rollbar.error(e)`              | `Sentry.capture_exception(e)`                                                                          |
+| `Rollbar.warning(msg)`          | `Sentry.capture_message(msg, level: :warning)`                                                         |
+| `Rollbar.info(msg, extra)`      | `Sentry.with_scope { \|s\| s.set_context("extra", extra); Sentry.capture_message(msg, level: :info) }` |
+| `Rollbar.critical(e)`           | `Sentry.capture_exception(e, level: :fatal)`                                                           |
+| `Rollbar.debug(msg)`            | `Sentry.capture_message(msg, level: :debug)`                                                           |
+| `Rollbar.log(level, e)`         | `Sentry.capture_exception(e, level: { "critical" => :fatal }.fetch(level, level.to_sym))`              |
+| `Rollbar.scoped(person: p) { }` | `Sentry.with_scope { \|s\| s.set_user(p); ... }`                                                       |
+| `Rollbar.scope!(person: p)`     | `Sentry.set_user(p)`                                                                                   |
+| `Rollbar.silenced { }`          | `# remove — no Sentry equivalent needed`                                                               |
+
+Rollbar uses `'warning'` level; Sentry uses `:warning`. Rollbar uses `'critical'`; map
+to Sentry’s `:fatal`.
+
+### Find call sites
+
+```bash
+grep -rn "Rollbar\.\(error\|warning\|warn\|info\|debug\|critical\|log\|scoped\|scope\)" \
+  app/ lib/ --include="*.rb"
+```
+
+---
+
+## Airbrake → Sentry
+
+**Gemfile:**
+
+```ruby
+# Remove:
+gem "airbrake"
+gem "airbrake-ruby"    # if present separately
+
+# Add:
+gem "sentry-ruby"
+gem "sentry-rails"     # if Rails
+gem "sentry-sidekiq"   # if Sidekiq
+```
+
+**Delete:** `config/initializers/airbrake.rb`
+
+Also check for and remove: `require 'airbrake/capistrano'` in `Capfile`,
+`require 'airbrake/rake'` in `Rakefile`, and any Sidekiq/DelayedJob/Resque middleware
+references.
+
+### API mapping
+
+| Airbrake                                         | Sentry                                                                                     |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `Airbrake.notify(e)`                             | `Sentry.capture_exception(e)`                                                              |
+| `Airbrake.notify(e, params)`                     | `Sentry.with_scope { \|s\| s.set_context("params", params); Sentry.capture_exception(e) }` |
+| `Airbrake.notify_sync(e)`                        | `Sentry.capture_exception(e)` (Sentry handles delivery asynchronously)                     |
+| `Airbrake.notify("message")`                     | `Sentry.capture_message("message")`                                                        |
+| `Airbrake.merge_context(hash)`                   | `Sentry.set_context("app", hash)`                                                          |
+| `Airbrake.add_filter { \|n\| n.ignore! if ... }` | `config.before_send = lambda { \|e, _h\| ... ? nil : e }`                                  |
+| `Airbrake.add_filter(MyFilter)`                  | `config.before_send = lambda { \|e, _h\| ... }`                                            |
+| `notice[:context][:user_id] = id`                | `Sentry.set_user(id: id)`                                                                  |
+| `Airbrake.notify_deploy(info)`                   | Use Sentry release tracking via `SENTRY_RELEASE` env var                                   |
+| `Airbrake.notify_request(...)`                   | Automatic via `sentry-rails` tracing                                                       |
+| `Airbrake.notify_query(...)`                     | Automatic via `sentry-rails` ActiveRecord spans                                            |
+
+### Find call sites
+
+```bash
+grep -rn "Airbrake\.\(notify\|notify_sync\|merge_context\|add_filter\|notify_request\|notify_query\)" \
+  app/ lib/ --include="*.rb"
+```
+
+---
+
+## Universal Migration Checklist
+
+Works for any tool not covered above:
+
+```bash
+# Error capture
+grep -rn "\.\(notify\|report_error\|send_error\|notice_error\)" \
+  app/ lib/ --include="*.rb" | grep -v "_spec\|_test"
+
+# Context / tagging
+grep -rn "\.\(context\|tag_request\|add_tags\|add_custom_attributes\)" \
+  app/ lib/ --include="*.rb" | grep -v "_spec\|_test"
+
+# Custom spans / instrumentation
+grep -rn "\.\(instrument\|monitor\|in_transaction\)" \
+  app/ lib/ --include="*.rb" | grep -v "_spec\|_test"
+
+# Metric calls
+grep -rn "\.\(set_gauge\|increment_counter\|record_metric\|gauge\|histogram\|timing\)" \
+  app/ lib/ --include="*.rb" | grep -v "_spec\|_test"
+
+# Environment variables to update
+grep -rn "APPSIGNAL\|HONEYBADGER\|BUGSNAG\|ROLLBAR\|AIRBRAKE" \
+  .env .env.* config/ --include="*.rb" --include="*.yml" 2>/dev/null
+```
+
+### Environment variable mapping
+
+| Tool        | Old env var                                    | Sentry       |
+| ----------- | ---------------------------------------------- | ------------ |
+| AppSignal   | `APPSIGNAL_PUSH_API_KEY`                       | `SENTRY_DSN` |
+| Honeybadger | `HONEYBADGER_API_KEY`                          | `SENTRY_DSN` |
+| Bugsnag     | `BUGSNAG_API_KEY`                              | `SENTRY_DSN` |
+| Rollbar     | `ROLLBAR_ACCESS_TOKEN`                         | `SENTRY_DSN` |
+| Airbrake    | `AIRBRAKE_PROJECT_ID` + `AIRBRAKE_PROJECT_KEY` | `SENTRY_DSN` |
+
+### Rollout strategy
+
+Run both tools in parallel for one release cycle, then remove the old gem once Sentry is
+receiving events in production.
+
+```ruby
+# Temporary dual-capture shim — remove after rollout validation:
+module ErrorCapture
+  def self.capture(exception, context: {})
+    Sentry.with_scope do |scope|
+      scope.set_context("extra", context) unless context.empty?
+      Sentry.capture_exception(exception)
+    end
+    begin
+      OldTool.notify(exception)  # replace OldTool with actual constant
+    rescue => e
+      Sentry.logger.warn("OldTool capture failed: %{message}", message: e.message)
+    end
+  end
+end
+```
+
+## Troubleshooting
+
+| Issue                          | Solution                                                                                                                   |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| Missing errors after migration | Ensure `sentry-rails` is present — `sentry-ruby` alone doesn’t hook Rails error handlers                                   |
+| Context missing from events    | Old tools often set context via middleware; replicate with a `before_action` calling `Sentry.set_user` / `Sentry.set_tags` |
+| Old gem still loading          | Check `Gemfile.lock` — it may be a transitive dependency                                                                   |
+| Distributed traces broken      | Ensure all services have migrated and propagate `sentry-trace` + `baggage` headers                                         |