@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,383 @@
+# Sentry Elixir SDK
+
+Opinionated wizard that scans your Elixir project and guides you through complete Sentry
+setup.
+
+> **Note:** SDK versions and APIs below reflect Sentry docs at time of writing (sentry
+> v13.2.0, requires Elixir ~> 1.13). Always verify against
+> [docs.sentry.io/platforms/elixir/](https://docs.sentry.io/platforms/elixir/) before
+> implementing.
+
+---
+
+## Phase 1: Detect
+
+Run these commands to understand the project before making any recommendations:
+
+```bash
+# Check existing Sentry dependency
+grep -i sentry mix.exs 2>/dev/null
+
+# Detect Elixir version
+cat .tool-versions 2>/dev/null | grep elixir
+grep "elixir:" mix.exs 2>/dev/null
+
+# Detect Phoenix or Plug
+grep -E '"phoenix"|"plug"' mix.exs 2>/dev/null
+
+# Detect Phoenix LiveView
+grep "phoenix_live_view" mix.exs 2>/dev/null
+
+# Detect Oban (job queue / crons)
+grep "oban" mix.exs 2>/dev/null
+
+# Detect Quantum (cron scheduler)
+grep "quantum" mix.exs 2>/dev/null
+
+# Detect OpenTelemetry usage
+grep "opentelemetry" mix.exs 2>/dev/null
+
+# Check for companion frontend
+ls assets/ frontend/ web/ client/ 2>/dev/null
+```
+
+**What to note:**
+
+| Signal                         | Impact                                                                           |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| `sentry` already in `mix.exs`? | Skip install; go to Phase 2 (configure features)                                 |
+| Phoenix detected?              | Add `Sentry.PlugCapture`, `Sentry.PlugContext`, optionally `Sentry.LiveViewHook` |
+| LiveView detected?             | Add `Sentry.LiveViewHook` to the `live_view` macro in `my_app_web.ex`            |
+| Oban detected?                 | Recommend Crons + error capture via Oban integration                             |
+| Quantum detected?              | Recommend Crons via Quantum integration                                          |
+| OpenTelemetry already present? | Tracing setup only needs `Sentry.OpenTelemetry.*` config                         |
+| Frontend directory found?      | Trigger Phase 4 cross-link suggestion                                            |
+
+---
+
+## 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 exceptions and crash reports
+- ✅ **Logging** — `Sentry.LoggerHandler` forwards crash reports and error logs to Sentry
+- ✅ **Tracing** — if Phoenix, Plug, or Ecto detected (via OpenTelemetry)
+
+**Optional (enhanced observability):**
+
+- ⚡ **Crons** — detect silent failures in scheduled jobs (Oban, Quantum, or manual
+  GenServer)
+- ⚡ **Sentry Logs** — forward structured logs to Sentry Logs Protocol (sentry v12.0.0+)
+
+**Recommendation logic:**
+
+| Feature          | Recommend when …                                                                             |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| Error Monitoring | **Always** — non-negotiable baseline                                                         |
+| Logging          | **Always** — `LoggerHandler` captures crashes that aren’t explicit `capture_exception` calls |
+| Tracing          | Phoenix, Plug, Ecto, or OpenTelemetry imports detected                                       |
+| Crons            | Oban, Quantum, or periodic `GenServer`/`Task` patterns detected                              |
+| Sentry Logs      | sentry v12.0.0+ in use and structured log search is needed                                   |
+
+Propose: _“I recommend setting up Error Monitoring + Logging
+[+ Tracing if Phoenix/Ecto detected]. Want me to also add Crons or Sentry Logs?”_
+
+---
+
+## Phase 3: Guide
+
+### Option 1: Igniter Installer (Recommended)
+
+> **You need to run this yourself** — the Igniter installer requires interactive
+> terminal input that the agent can’t handle.
+> Copy-paste into your terminal:
+>
+> ```bash
+> mix igniter.install sentry
+> ```
+>
+> Available since sentry v11.0.0. It auto-configures `config/config.exs`,
+> `config/prod.exs`, `config/runtime.exs`, and `lib/my_app/application.ex`.
+>
+> **Once it finishes, come back and skip to [Verification](#verification).**
+
+If the user skips the Igniter installer, proceed with Option 2 (Manual Setup) below.
+
+---
+
+### Option 2: Manual Setup
+
+#### Install
+
+Add to `mix.exs` dependencies:
+
+```elixir
+# mix.exs
+defp deps do
+  [
+    {:sentry, "~> 13.0"},
+    {:finch, "~> 0.21"}
+    # Add jason if using Elixir < 1.18:
+    # {:jason, "~> 1.4"},
+  ]
+end
+```
+
+```bash
+mix deps.get
+```
+
+#### Configure
+
+```elixir
+# config/config.exs
+config :sentry,
+  dsn: System.get_env("SENTRY_DSN"),
+  environment_name: config_env(),
+  enable_source_code_context: true,
+  root_source_code_paths: [File.cwd!()],
+  in_app_otp_apps: [:my_app]
+```
+
+For runtime configuration (recommended for DSN and release):
+
+```elixir
+# config/runtime.exs
+import Config
+
+config :sentry,
+  dsn: System.fetch_env!("SENTRY_DSN"),
+  release: System.get_env("SENTRY_RELEASE", "my-app@#{Application.spec(:my_app, :vsn)}")
+```
+
+#### Quick Start — Recommended Init Config
+
+This config enables the most features with sensible defaults:
+
+```elixir
+# config/config.exs
+config :sentry,
+  dsn: System.get_env("SENTRY_DSN"),
+  environment_name: config_env(),
+  enable_source_code_context: true,
+  root_source_code_paths: [File.cwd!()],
+  in_app_otp_apps: [:my_app]
+
+# Logger handler — captures crash reports. Defined under your OTP app's :logger
+# key so that Logger.add_handlers(:my_app) (below) actually loads it. Handlers
+# nested under `config :sentry` would be ignored by add_handlers/1.
+config :my_app, :logger, [
+  {:handler, :sentry_handler, Sentry.LoggerHandler, %{
+    config: %{
+      metadata: [:request_id],
+      capture_log_messages: true,
+      level: :error
+    }
+  }}
+]
+```
+
+#### Activate Logger Handler
+
+Add `Logger.add_handlers/1` in `Application.start/2`:
+
+```elixir
+# lib/my_app/application.ex
+def start(_type, _args) do
+  Logger.add_handlers(:my_app)   # activates the :sentry_handler configured above
+
+  children = [
+    MyAppWeb.Endpoint
+    # ... other children
+  ]
+
+  Supervisor.start_link(children, strategy: :one_for_one)
+end
+```
+
+#### Phoenix Integration
+
+**`lib/my_app_web/endpoint.ex`**
+
+```elixir
+defmodule MyAppWeb.Endpoint do
+  use Sentry.PlugCapture          # Add ABOVE use Phoenix.Endpoint (Cowboy adapter only)
+  use Phoenix.Endpoint, otp_app: :my_app
+
+  # ...
+
+  plug Plug.Parsers,
+    parsers: [:urlencoded, :multipart, :json],
+    pass: ["*/*"],
+    json_decoder: Phoenix.json_library()
+
+  plug Sentry.PlugContext          # Add BELOW Plug.Parsers
+  # ...
+end
+```
+
+> **Note:** `Sentry.PlugCapture` is only needed for the **Cowboy** adapter.
+> Phoenix 1.7+ defaults to **Bandit**, where `PlugCapture` is harmless but unnecessary.
+> `Sentry.PlugContext` is always recommended — it enriches events with HTTP request
+> data.
+
+**LiveView errors — `lib/my_app_web.ex`**
+
+```elixir
+def live_view do
+  quote do
+    use Phoenix.LiveView
+
+    on_mount Sentry.LiveViewHook   # captures errors in mount/handle_event/handle_info
+  end
+end
+```
+
+#### Plain Plug Application
+
+```elixir
+defmodule MyApp.Router do
+  use Plug.Router
+  use Sentry.PlugCapture          # Cowboy only
+
+  plug Plug.Parsers, parsers: [:urlencoded, :multipart]
+  plug Sentry.PlugContext
+  # ...
+end
+```
+
+### 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`          | Phoenix / Ecto / OpenTelemetry detected  |
+| Logging          | `./logging.md`          | `LoggerHandler` or Sentry Logs setup     |
+| Crons            | `./crons.md`            | Oban, Quantum, or periodic jobs detected |
+
+For each feature: `Read ./<feature>.md`, follow steps exactly, verify it works.
+
+---
+
+## Configuration Reference
+
+### Key Config Options
+
+| Option                        | Type                                | Default                     | Purpose                                                                                                    |
+| ----------------------------- | ----------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `:dsn`                        | `string \| nil`                     | `nil`                       | SDK disabled if nil; env: `SENTRY_DSN`                                                                     |
+| `:environment_name`           | `atom \| string`                    | `"production"`              | e.g., `:prod`; env: `SENTRY_ENVIRONMENT`                                                                   |
+| `:release`                    | `string \| nil`                     | `nil`                       | e.g., `"my-app@1.0.0"`; env: `SENTRY_RELEASE`                                                              |
+| `:sample_rate`                | `float`                             | `1.0`                       | Error event sample rate (0.0–1.0)                                                                          |
+| `:enable_source_code_context` | `boolean`                           | `false`                     | Include source lines around errors                                                                         |
+| `:root_source_code_paths`     | `[path]`                            | `[]`                        | Required when source context is enabled                                                                    |
+| `:in_app_otp_apps`            | `[atom]`                            | `[]`                        | OTP apps whose modules are “in-app” in stacktraces                                                         |
+| `:before_send`                | `(event -> event \| nil) \| {m, f}` | `nil`                       | Hook to mutate or drop error events                                                                        |
+| `:after_send_event`           | `(event, result -> any) \| {m, f}`  | `nil`                       | Hook called after event is sent                                                                            |
+| `:filter`                     | `module`                            | `Sentry.DefaultEventFilter` | Module implementing `Sentry.EventFilter`                                                                   |
+| `:max_breadcrumbs`            | `integer`                           | `100`                       | Max breadcrumbs per process                                                                                |
+| `:max_stacktrace_arg_length`  | `integer`                           | `10000`                     | Max length (in graphemes) of each inspected function argument in stacktrace vars (v13.2.0+)                |
+| `:dedup_events`               | `boolean`                           | `true`                      | Deduplicate identical events within ~30 seconds                                                            |
+| `:tags`                       | `map`                               | `%{}`                       | Global tags sent with every event                                                                          |
+| `:traces_sample_rate`         | `float \| nil`                      | `nil`                       | Non-nil enables tracing (requires OTel setup)                                                              |
+| `:traces_sampler`             | `fn \| {m, f} \| nil`               | `nil`                       | Custom per-transaction sampling                                                                            |
+| `:enable_logs`                | `boolean`                           | `false`                     | Enable Sentry Logs Protocol (v12.0.0+)                                                                     |
+| `:scrubber`                   | `keyword`                           | `[]`                        | Scrubber config (v13.1.1+); keys: `:conn_private_allow_list` (list of atoms kept from `Plug.Conn.private`) |
+| `:test_mode`                  | `boolean`                           | `false`                     | Capture events in-memory for testing                                                                       |
+
+### Default PII Guidance
+
+Most Sentry SDKs expose a send-default-PII option.
+As of sentry v12, the Elixir SDK does not expose a `send_default_pii` config option in
+its documented option list or current config schema, so do **not** add a non-existent
+option. For richer user context, use `Sentry.PlugContext` and explicitly set allowed
+fields with `Sentry.Context.set_user_context/1`, then scrub with `:before_send` if
+needed. If a future Elixir SDK release adds `send_default_pii`, recommend setting it.
+
+**Automatic PII Scrubbing:** As of v13.1.0, stacktrace frame variables and
+`FunctionClauseError`/`Phoenix.ActionClauseError` arguments are automatically scrubbed
+for sensitive data using the same scrubber rules as HTTP request data.
+Use `:scrubber` config to customize which `Plug.Conn.private` keys are retained.
+
+### 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_name` | Deployment environment             |
+
+---
+
+## Verification
+
+Test that Sentry is receiving events:
+
+```bash
+# Send a test event from your project
+MIX_ENV=dev mix sentry.send_test_event
+```
+
+Or add a temporary call in a controller action:
+
+```elixir
+# Temporary test — remove after confirming
+def index(conn, _params) do
+  Sentry.capture_message("Sentry Elixir SDK test event")
+  text(conn, "sent")
+end
+```
+
+Check the Sentry dashboard within a few seconds.
+If nothing appears:
+
+1. Set `config :sentry, log_level: :debug` for verbose SDK output
+2. Verify `SENTRY_DSN` is set and the project exists
+3. Confirm `:environment_name` is not set to a value Sentry filters in your alert rules
+
+---
+
+## Phase 4: Cross-Link
+
+After completing Elixir setup, check for a companion frontend missing Sentry coverage:
+
+```bash
+ls assets/ frontend/ web/ client/ ui/ 2>/dev/null
+cat assets/package.json frontend/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) or [`nextjs`](../nextjs/index.md)                                                 |
+| Svelte / SvelteKit | [`svelte`](../svelte/index.md)                                                                                 |
+| Vue                | See [docs.sentry.io/platforms/javascript/guides/vue/](https://docs.sentry.io/platforms/javascript/guides/vue/) |
+| Other JS/TS        | [`browser`](../browser/index.md)                                                                               |
+
+Connecting Phoenix backend and JavaScript frontend with linked Sentry projects enables
+**distributed tracing** — stack traces that span the browser, Phoenix HTTP server, and
+downstream services in a single trace view.
+
+---
+
+## Troubleshooting
+
+| Issue                                       | Solution                                                                                                           |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Events not appearing                        | Verify `SENTRY_DSN` is set; run `mix sentry.send_test_event`; set `log_level: :debug`                              |
+| Missing stack traces on captured exceptions | Pass `stacktrace: __STACKTRACE__` in the `rescue` block: `Sentry.capture_exception(e, stacktrace: __STACKTRACE__)` |
+| `PlugCapture` not working on Bandit         | `Sentry.PlugCapture` is Cowboy-only; with Bandit errors surface via `LoggerHandler`                                |
+| Source code context missing in production   | Run `mix sentry.package_source_code` before building your OTP release                                              |
+| Context not appearing on async events       | `Sentry.Context.*` is process-scoped; pass values explicitly or propagate Logger metadata across processes         |
+| Oban integration not reporting crons        | Requires Oban v2.17.6+ or Oban Pro; cron jobs must have `"cron" => true` in job meta                               |
+| Duplicate events from Cowboy/Bandit crashes | Set `excluded_domains: [:cowboy, :bandit]` in `LoggerHandler` config (both excluded by default as of v13.1.0)      |
+| `finch` not starting                        | Ensure `{:finch, "~> 0.21"}` is in deps; Finch is the default HTTP client since v12.0.0                            |
+| JSON encoding error                         | Add `{:jason, "~> 1.4"}` and set `json_library: Jason` for Elixir < 1.18                                           |

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

@@ -0,0 +1,239 @@
+# Logging — Sentry Elixir SDK
+
+> Minimum SDK: `sentry` v9.0.0+ for `Sentry.LoggerHandler`; v12.0.0+ for Sentry Logs
+> Protocol
+
+The Elixir SDK provides two independent logging mechanisms:
+
+1. **`Sentry.LoggerHandler`** — Erlang `:logger` handler that forwards crash reports and
+   error log messages from your app to Sentry as _error events_. This is the primary way
+   to catch errors that weren’t explicitly passed to `capture_exception/2`.
+
+2. **Sentry Logs Protocol** (v12.0.0+) — Forwards structured log entries to Sentry’s
+   Logs product, where they appear alongside errors and traces.
+
+---
+
+## Sentry.LoggerHandler
+
+### Configuration
+
+The recommended setup uses the `:logger` key in your app’s config and activates handlers
+in `Application.start/2`.
+
+**Step 1: Define the handler in config**
+
+```elixir
+# config/config.exs
+config :my_app, :logger, [
+  {:handler, :sentry_handler, Sentry.LoggerHandler, %{
+    config: %{
+      metadata: [:request_id, :user_id],   # Logger metadata keys to include as extra context
+      capture_log_messages: true,           # Send all :error messages, not just crash reports
+      level: :error                         # Minimum log level (default: :error)
+    }
+  }}
+]
+```
+
+**Step 2: Activate in Application.start/2**
+
+```elixir
+# lib/my_app/application.ex
+def start(_type, _args) do
+  Logger.add_handlers(:my_app)   # activates all handlers defined in config :my_app, :logger
+
+  children = [
+    MyAppWeb.Endpoint
+    # ... other children
+  ]
+
+  Supervisor.start_link(children, strategy: :one_for_one)
+end
+```
+
+**Alternative: Add handler directly in Application.start/2**
+
+```elixir
+def start(_type, _args) do
+  :logger.add_handler(:sentry_handler, Sentry.LoggerHandler, %{
+    config: %{
+      metadata: [:request_id],
+      capture_log_messages: true,
+      level: :error
+    }
+  })
+
+  Supervisor.start_link(children, strategy: :one_for_one)
+end
+```
+
+### LoggerHandler Configuration Options
+
+| Option                  | Type                                              | Default     | Description                                                                                                                     |
+| ----------------------- | ------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `:level`                | `Logger.level \| nil`                             | `:error`    | Minimum log level to forward to Sentry                                                                                          |
+| `:excluded_domains`     | `[atom]`                                          | `[:cowboy]` | Domains to skip (cowboy excluded by default to avoid double-reporting with `PlugCapture`)                                       |
+| `:metadata`             | `[atom] \| :all`                                  | `[]`        | Logger metadata keys to include as extra context on the Sentry event                                                            |
+| `:tags_from_metadata`   | `[atom]`                                          | `[]`        | Metadata keys to promote to Sentry tags (searchable). Since v10.9.0                                                             |
+| `:capture_log_messages` | `boolean`                                         | `false`     | When `true`, all `:error`+ log messages are sent; when `false`, only crash reports (supervisor crashes, process exits) are sent |
+| `:rate_limiting`        | `[max_events: integer, interval: integer] \| nil` | `nil`       | Rate limit; e.g., `[max_events: 10, interval: 1_000]`. Since v10.5.0                                                            |
+| `:sync_threshold`       | `non_neg_integer \| nil`                          | `100`       | Queue depth before switching to sync mode. Since v10.6.0                                                                        |
+| `:discard_threshold`    | `non_neg_integer \| nil`                          | `nil`       | Queue depth above which events are dropped (cannot combine with `:sync_threshold`). Since v10.9.0                               |
+
+### Capturing specific log levels only
+
+```elixir
+config :my_app, :logger, [
+  {:handler, :sentry_handler, Sentry.LoggerHandler, %{
+    config: %{
+      level: :warning,              # :debug | :info | :warning | :error | :critical
+      capture_log_messages: true,
+      metadata: :all                # include all Logger metadata
+    }
+  }}
+]
+```
+
+### Rate limiting
+
+Prevent log storms from flooding Sentry:
+
+```elixir
+config :my_app, :logger, [
+  {:handler, :sentry_handler, Sentry.LoggerHandler, %{
+    config: %{
+      capture_log_messages: true,
+      level: :error,
+      rate_limiting: [max_events: 20, interval: 60_000]   # max 20 events per minute
+    }
+  }}
+]
+```
+
+### Promoting metadata to Sentry tags
+
+Tags are indexed and searchable in Sentry.
+Promote high-value metadata keys:
+
+```elixir
+config :my_app, :logger, [
+  {:handler, :sentry_handler, Sentry.LoggerHandler, %{
+    config: %{
+      metadata: [:request_id, :user_id, :region],
+      tags_from_metadata: [:region],        # "region" becomes a searchable Sentry tag
+      capture_log_messages: true,
+      level: :error
+    }
+  }}
+]
+```
+
+### LoggerBackend (legacy)
+
+`Sentry.LoggerBackend` is the older Elixir `Logger` backend.
+Prefer `LoggerHandler` for new projects.
+`LoggerBackend` will eventually be deprecated.
+
+```elixir
+# lib/my_app/application.ex
+def start(_type, _args) do
+  Logger.add_backend(Sentry.LoggerBackend)
+  # ...
+end
+
+# config/config.exs
+config :logger, Sentry.LoggerBackend,
+  level: :warning,
+  excluded_domains: [],
+  metadata: [:foo_bar],
+  capture_log_messages: true
+```
+
+---
+
+## Sentry Logs Protocol (since v12.0.0)
+
+The Sentry Logs feature sends structured log entries to Sentry’s Logs product — separate
+from error events. This enables log search, log-to-trace correlation, and dashboards
+alongside your error data.
+
+### Enable
+
+```elixir
+# config/config.exs
+config :sentry,
+  enable_logs: true,   # auto-attaches a TelemetryProcessor-backed LoggerHandler
+  logs: [
+    level: :info,                              # minimum log level (default: :info)
+    metadata: [:request_id, :user_id],         # metadata keys to include as log attributes
+    excluded_domains: [:cowboy, :ecto_sql]     # domains to skip
+  ]
+```
+
+`enable_logs: true` automatically wires up a Logger handler that captures log entries
+and forwards them to the Sentry Logs Protocol endpoint via the `TelemetryProcessor`.
+
+### Filter logs before sending
+
+```elixir
+config :sentry,
+  enable_logs: true,
+  before_send_log: fn log_event ->
+    # Return nil to drop the log; return log_event to send it
+    if log_event.level == :debug, do: nil, else: log_event
+  end
+```
+
+### Route all categories through TelemetryProcessor
+
+By default only logs use the `TelemetryProcessor` ring buffer.
+You can route errors, check-ins, and transactions through it too:
+
+```elixir
+config :sentry,
+  enable_logs: true,
+  telemetry_processor_categories: [:log, :error, :check_in, :transaction]
+```
+
+---
+
+## How the Two Systems Interact
+
+| What              | LoggerHandler                   | Sentry Logs Protocol                            |
+| ----------------- | ------------------------------- | ----------------------------------------------- |
+| Appears in Sentry | Issues (errors)                 | Logs product                                    |
+| Use for           | Crash reports, unhandled errors | Structured log search, log-to-trace correlation |
+| Min SDK version   | v9.0.0                          | v12.0.0                                         |
+| Config key        | `:logger` in app config         | `:enable_logs` in sentry config                 |
+
+You can run both simultaneously.
+A common setup: `LoggerHandler` at `:error` level for issues, and Sentry Logs at `:info`
+for structured log search.
+
+---
+
+## Best Practices
+
+- Prefer `Sentry.LoggerHandler` over `Sentry.LoggerBackend` for new projects —
+  `LoggerHandler` is the Erlang `:logger` handler and runs in the calling process, which
+  is more efficient
+- Set `excluded_domains: [:cowboy]` (the default) to avoid duplicate events when using
+  `Sentry.PlugCapture` with Cowboy
+- Enable `capture_log_messages: true` to catch error-level log messages that are not
+  explicit `capture_exception` calls
+- Use `tags_from_metadata` to promote high-cardinality identifiers (user ID, region,
+  request ID) to searchable Sentry tags
+- Apply `rate_limiting` in high-throughput services to prevent log storms from
+  overwhelming your Sentry quota
+
+## Troubleshooting
+
+| Issue                                | Solution                                                                          |
+| ------------------------------------ | --------------------------------------------------------------------------------- |
+| LoggerHandler not capturing anything | Verify `Logger.add_handlers(:my_app)` is called in `Application.start/2`          |
+| Duplicate events from Cowboy crashes | `excluded_domains: [:cowboy]` is the default; check if it was removed from config |
+| No Sentry Logs entries appearing     | Ensure `enable_logs: true` is set and sentry v12.0.0+ is in use                   |
+| Log metadata not appearing in Sentry | List keys explicitly in `metadata:` option; or use `metadata: :all`               |
+| Too many log events hitting quota    | Add `rate_limiting: [max_events: N, interval: ms]` to `LoggerHandler` config      |
+| `LoggerBackend` warnings in logs     | Migrate to `Sentry.LoggerHandler`; `LoggerBackend` will be deprecated             |