@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,371 @@
+# Crons — Sentry Elixir SDK
+
+> Minimum SDK: `sentry` v10.2.0+
+
+Sentry Cron Monitoring detects when scheduled jobs fail silently — they don’t error, but
+they stop running or take too long.
+The SDK provides three integration paths: manual check-ins (any scheduler), Oban (job
+queue), and Quantum (cron scheduler).
+
+## Manual Check-Ins
+
+Use `Sentry.capture_check_in/1` with any periodic task — `GenServer`, `Task`, or custom
+scheduler.
+
+### Basic pattern: start → work → complete/error
+
+```elixir
+defmodule MyApp.ReportWorker do
+  use GenServer
+
+  def handle_info(:run, state) do
+    # 1. Signal job started
+    {:ok, check_in_id} = Sentry.capture_check_in(
+      status: :in_progress,
+      monitor_slug: "daily-report"
+    )
+
+    # 2. Do the work
+    result = MyApp.Reports.generate_daily_report()
+
+    # 3. Signal completion or failure
+    case result do
+      {:ok, _report} ->
+        Sentry.capture_check_in(
+          check_in_id: check_in_id,
+          status: :ok,
+          monitor_slug: "daily-report"
+        )
+
+      {:error, reason} ->
+        Sentry.capture_check_in(
+          check_in_id: check_in_id,
+          status: :error,
+          monitor_slug: "daily-report"
+        )
+        Logger.error("Report generation failed: #{inspect(reason)}")
+    end
+
+    {:noreply, state}
+  end
+end
+```
+
+### With monitor configuration (upsert)
+
+Providing `monitor_config` creates or updates the monitor definition in Sentry on first
+check-in. This eliminates the need to create monitors in the Sentry UI manually:
+
+```elixir
+Sentry.capture_check_in(
+  status: :in_progress,
+  monitor_slug: "hourly-sync",
+  monitor_config: [
+    schedule: [type: :crontab, value: "0 * * * *"],   # runs every hour at :00
+    timezone: "America/New_York",
+    checkin_margin: 5,         # minutes before Sentry considers the check-in missed
+    max_runtime: 30,           # minutes before Sentry considers the job failed
+    failure_issue_threshold: 2,
+    recovery_threshold: 2,
+    owner: "platform-team"     # since v10.10.0
+  ]
+)
+```
+
+### Interval schedule
+
+For jobs that run every N minutes/hours rather than on a crontab:
+
+```elixir
+Sentry.capture_check_in(
+  status: :in_progress,
+  monitor_slug: "health-probe",
+  monitor_config: [
+    schedule: [type: :interval, value: 15, unit: :minute],
+    # unit options: :year | :month | :week | :day | :hour | :minute
+    checkin_margin: 3,
+    max_runtime: 5
+  ]
+)
+```
+
+### `capture_check_in/1` options
+
+| Option            | Type                            | Required      | Description                                                      |
+| ----------------- | ------------------------------- | ------------- | ---------------------------------------------------------------- |
+| `:status`         | `:in_progress \| :ok \| :error` | Yes           | Current job status                                               |
+| `:monitor_slug`   | `string`                        | Yes           | Unique identifier for the monitor (slug format)                  |
+| `:check_in_id`    | `string`                        | On completion | ID from the initial `:in_progress` call                          |
+| `:duration`       | `number`                        | No            | Job duration in seconds (auto-calculated when using check_in_id) |
+| `:monitor_config` | `keyword`                       | No            | Monitor definition; upserted on each call                        |
+| `:environment`    | `string`                        | No            | Override default environment for this check-in                   |
+
+`capture_check_in/1` returns:
+
+- `{:ok, check_in_id}` — check-in ID string; pass it to subsequent calls
+- `:ignored` — not sent (no DSN, wrong environment, etc.)
+- `{:error, ClientError.t()}` — HTTP error
+
+### Helper wrapper pattern
+
+For clean code, wrap the check-in lifecycle in a helper:
+
+```elixir
+defmodule MyApp.Crons do
+  @doc """
+  Runs a function as a Sentry-monitored cron job.
+  Returns {:ok, result} or {:error, exception}.
+  """
+  def monitor(slug, fun, monitor_config \\ []) do
+    # capture_check_in/1 returns {:ok, id}, :ignored (no DSN / filtered env),
+    # or {:error, _} (HTTP failure). Match all three so a non-:ok result never
+    # raises a MatchError and crashes the job.
+    check_in_id =
+      case Sentry.capture_check_in(
+             status: :in_progress,
+             monitor_slug: slug,
+             monitor_config: monitor_config
+           ) do
+        {:ok, id} -> id
+        :ignored -> nil
+        {:error, _reason} -> nil
+      end
+
+    try do
+      result = fun.()
+
+      if check_in_id do
+        Sentry.capture_check_in(
+          check_in_id: check_in_id,
+          status: :ok,
+          monitor_slug: slug
+        )
+      end
+
+      {:ok, result}
+    rescue
+      exception ->
+        if check_in_id do
+          Sentry.capture_check_in(
+            check_in_id: check_in_id,
+            status: :error,
+            monitor_slug: slug
+          )
+        end
+
+        Sentry.capture_exception(exception, stacktrace: __STACKTRACE__)
+        {:error, exception}
+    end
+  end
+end
+
+# Usage
+MyApp.Crons.monitor("nightly-cleanup", fn ->
+  MyApp.Cleanup.run()
+end, schedule: [type: :crontab, value: "0 3 * * *"])
+```
+
+---
+
+## Oban Integration
+
+Requires: Oban v2.17.6+ or Oban Pro v0.14+
+
+### Error capture (since v10.9.0)
+
+Report failed Oban job errors to Sentry automatically:
+
+```elixir
+# config/config.exs
+config :sentry,
+  integrations: [
+    oban: [
+      capture_errors: true
+    ]
+  ]
+```
+
+Errors from all Oban workers are captured with job context included.
+
+### Cron monitoring (since v10.2.0)
+
+Monitor scheduled Oban jobs automatically.
+The integration reads cron metadata set by Oban Pro (or manually via job meta):
+
+```elixir
+# config/config.exs
+config :sentry,
+  integrations: [
+    oban: [
+      capture_errors: true,
+      cron: [
+        enabled: true
+      ]
+    ]
+  ]
+```
+
+Jobs are only monitored if their meta contains `"cron" => true`. Oban Pro sets this
+automatically. For standard Oban, add it manually:
+
+```elixir
+# Scheduling a cron job with Oban (standard, not Pro)
+Oban.insert(%Oban.Job{
+  worker: MyApp.DailyReportWorker,
+  meta: %{"cron" => true, "cron_expr" => "0 8 * * *"}
+})
+```
+
+### Per-worker monitor configuration (since v10.9.0)
+
+Override monitor settings per worker using the `Sentry.Integrations.Oban.Cron` callback:
+
+```elixir
+defmodule MyApp.DailyReportWorker do
+  use Oban.Worker, queue: :reports
+
+  @behaviour Sentry.Integrations.Oban.Cron   # optional callback
+
+  @impl Sentry.Integrations.Oban.Cron
+  def sentry_check_in_configuration(_job) do
+    [
+      monitor_config: [
+        timezone: "America/New_York",
+        checkin_margin: 10,
+        max_runtime: 60
+      ]
+    ]
+  end
+
+  @impl Oban.Worker
+  def perform(%Oban.Job{} = job) do
+    # ... job logic
+    :ok
+  end
+end
+```
+
+### Custom error reporting filter (since v12.0.0)
+
+Suppress reporting for specific noisy workers:
+
+```elixir
+config :sentry,
+  integrations: [
+    oban: [
+      capture_errors: true,
+      should_report_error_callback: fn worker, _job ->
+        worker not in [MyApp.NoisyWorker, MyApp.ExpectedFailureWorker]
+      end
+    ]
+  ]
+```
+
+### Custom monitor slug generator
+
+```elixir
+defmodule MyApp.ObanSlugger do
+  def generate_slug(%Oban.Job{worker: worker}) do
+    worker
+    |> Module.split()
+    |> Enum.map(&Macro.underscore/1)
+    |> Enum.join("-")
+  end
+end
+
+config :sentry,
+  integrations: [
+    oban: [
+      cron: [
+        enabled: true,
+        monitor_slug_generator: {MyApp.ObanSlugger, :generate_slug}
+      ]
+    ]
+  ]
+```
+
+---
+
+## Quantum Integration
+
+Requires: Quantum v3.0+
+
+### Enable cron monitoring
+
+```elixir
+# mix.exs
+{:quantum, "~> 3.0"}
+```
+
+```elixir
+# config/config.exs
+config :sentry,
+  integrations: [
+    quantum: [
+      cron: [
+        enabled: true
+      ]
+    ]
+  ]
+```
+
+The Quantum integration automatically reads cron expressions from your Quantum scheduler
+configuration and creates monitors for each job.
+The monitor slug is derived from the job name.
+
+```elixir
+# lib/my_app/scheduler.ex
+defmodule MyApp.Scheduler do
+  use Quantum, otp_app: :my_app
+end
+
+# config/config.exs
+config :my_app, MyApp.Scheduler,
+  jobs: [
+    {"0 * * * *", {MyApp.HourlyTask, :run, []}},    # monitored as "hourly_task"
+    {"@daily",    {MyApp.DailyReport, :run, []}},    # monitored as "daily_report"
+  ]
+```
+
+> **Note:** Quantum jobs using `@reboot` are not monitored (no equivalent schedule type
+> in Sentry Crons).
+
+---
+
+## Monitor Configuration Reference
+
+| Option                    | Type                                                   | Description                                        |
+| ------------------------- | ------------------------------------------------------ | -------------------------------------------------- |
+| `schedule.type`           | `:crontab \| :interval`                                | Schedule type                                      |
+| `schedule.value`          | `string` (crontab) or `integer` (interval)             | Crontab expression or interval count               |
+| `schedule.unit`           | `:minute \| :hour \| :day \| :week \| :month \| :year` | Interval unit (`:interval` type only)              |
+| `timezone`                | `string`                                               | IANA timezone (e.g., `"America/New_York"`)         |
+| `checkin_margin`          | `integer`                                              | Minutes after expected start before marking missed |
+| `max_runtime`             | `integer`                                              | Minutes from start before marking timed out        |
+| `failure_issue_threshold` | `integer`                                              | Consecutive failures before opening an issue       |
+| `recovery_threshold`      | `integer`                                              | Consecutive successes before closing the issue     |
+| `owner`                   | `string`                                               | Team or user slug (since v10.10.0)                 |
+
+## Best Practices
+
+- Always call `Sentry.capture_check_in/1` with `:in_progress` before starting work and
+  `:ok` or `:error` on completion — sending only `:ok` at the end still works but loses
+  duration tracking
+- Wrap job logic in a try/rescue so failures also send the `:error` status (see helper
+  wrapper pattern above)
+- Use `monitor_config` on the first check-in of a new job to create the monitor
+  automatically — no need to set it on every subsequent check-in
+- Set `checkin_margin` to a reasonable buffer (e.g., 5 minutes for hourly jobs) to avoid
+  false alarms from minor scheduling jitter
+- For Oban, prefer the built-in integration over manual check-ins — it handles the
+  check-in lifecycle and job context enrichment automatically
+
+## Troubleshooting
+
+| Issue                                   | Solution                                                                                                               |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Monitor not appearing in Sentry         | Send at least one `:in_progress` check-in with `monitor_config` to create the monitor                                  |
+| Oban integration not monitoring crons   | Requires Oban v2.17.6+ or Oban Pro; job meta must contain `"cron" => true`                                             |
+| `capture_check_in/1` returns `:ignored` | DSN is not set or `:environment_name` is excluded in your Sentry alert filters                                         |
+| Quantum `@reboot` jobs not monitored    | Expected — `@reboot` has no crontab/interval equivalent; use manual check-ins for one-time startup jobs                |
+| Missed check-ins on deploy              | If the app restarts during a cron window, the check-in is missed; increase `checkin_margin` to account for deploy time |

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

@@ -0,0 +1,335 @@
+# Error Monitoring — Sentry Elixir SDK
+
+> Minimum SDK: `sentry` v8.0.0+
+
+## Configuration
+
+Key config options for error monitoring:
+
+| Option                        | Type                                         | Default                     | Purpose                                                  |
+| ----------------------------- | -------------------------------------------- | --------------------------- | -------------------------------------------------------- |
+| `:dsn`                        | `string \| nil`                              | `nil`                       | SDK disabled if nil                                      |
+| `:sample_rate`                | `float`                                      | `1.0`                       | Error event sample rate (0.0–1.0)                        |
+| `:before_send`                | `(event -> event \| nil \| false) \| {m, f}` | `nil`                       | Mutate or drop error events before sending               |
+| `:after_send_event`           | `(event, result -> any) \| {m, f}`           | `nil`                       | Called after sending; return value ignored               |
+| `:filter`                     | `module`                                     | `Sentry.DefaultEventFilter` | Module implementing `Sentry.EventFilter`                 |
+| `:max_breadcrumbs`            | `integer`                                    | `100`                       | Max breadcrumbs stored per process                       |
+| `:dedup_events`               | `boolean`                                    | `true`                      | Deduplicate identical events within ~30 seconds          |
+| `:tags`                       | `map`                                        | `%{}`                       | Global tags sent with every event                        |
+| `: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 appear as “in-app” in stacktraces |
+
+## Code Examples
+
+### Basic setup
+
+```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]
+```
+
+### Capturing exceptions
+
+Always pass `stacktrace: __STACKTRACE__` in rescue blocks — Elixir only populates
+`__STACKTRACE__` inside a `rescue` or `catch` clause:
+
+```elixir
+try do
+  perform_risky_operation()
+rescue
+  exception ->
+    Sentry.capture_exception(exception, stacktrace: __STACKTRACE__)
+    reraise exception, __STACKTRACE__
+end
+```
+
+With extra context:
+
+```elixir
+try do
+  process_order(order_id)
+rescue
+  exception ->
+    Sentry.capture_exception(exception,
+      stacktrace: __STACKTRACE__,
+      extra: %{order_id: order_id},
+      tags: %{region: "us-east-1"},
+      level: :error
+    )
+end
+```
+
+### Capturing messages
+
+```elixir
+# Simple message
+Sentry.capture_message("Payment gateway timeout")
+
+# With context
+Sentry.capture_message("Queue depth exceeded threshold",
+  extra: %{depth: 5000, limit: 1000},
+  tags: %{queue: "payments"},
+  level: :warning
+)
+
+# With interpolation (since v10.1.0)
+Sentry.capture_message("Failed to process user %s after %d attempts",
+  interpolation_parameters: [user_id, attempt_count]
+)
+```
+
+### Context enrichment with `Sentry.Context`
+
+Context is stored per-process (in Logger metadata).
+Set it early in request handling — in a Plug, LiveView mount, or GenServer handler:
+
+```elixir
+# Set user identity
+Sentry.Context.set_user_context(%{
+  id: current_user.id,
+  username: current_user.username,
+  email: current_user.email,
+  ip_address: "{{auto}}"   # Sentry infers from request headers
+})
+
+# Set tags (searchable in Sentry)
+Sentry.Context.set_tags_context(%{
+  subscription_tier: "pro",
+  region: "us-east-1"
+})
+
+# Set extra context (not searchable — use tags for filtering)
+Sentry.Context.set_extra_context(%{
+  order_id: "abc-123",
+  items_count: 5
+})
+
+# Set request context (URL, method, headers)
+Sentry.Context.set_request_context(%{
+  url: conn.request_path,
+  method: conn.method,
+  headers: Enum.into(conn.req_headers, %{})
+})
+
+# Add a breadcrumb
+Sentry.Context.add_breadcrumb(%{
+  category: "auth",
+  message: "User authenticated",
+  level: :info,
+  data: %{method: "oauth2", provider: "github"}
+})
+```
+
+> **Important:** `Sentry.Context` data is scoped to the current process only.
+> It is NOT automatically propagated to spawned `Task` or `GenServer` processes.
+> For async work, pass context values explicitly.
+
+### Context in a Phoenix controller (via Plug)
+
+```elixir
+defmodule MyAppWeb.Plugs.SentryContext do
+  @behaviour Plug
+
+  def init(opts), do: opts
+
+  def call(conn, _opts) do
+    if user = conn.assigns[:current_user] do
+      Sentry.Context.set_user_context(%{
+        id: user.id,
+        username: user.username,
+        email: user.email
+      })
+    end
+
+    Sentry.Context.set_request_context(%{
+      url: Phoenix.Controller.current_url(conn),
+      method: conn.method,
+      headers: Enum.into(conn.req_headers, %{})
+    })
+
+    conn
+  end
+end
+
+# In your router pipeline:
+pipeline :browser do
+  plug :accepts, ["html"]
+  plug :fetch_session
+  plug :put_secure_browser_headers
+  plug MyAppWeb.Plugs.SentryContext
+end
+```
+
+### Breadcrumbs
+
+```elixir
+Sentry.Context.add_breadcrumb(%{
+  type: "http",
+  category: "http",
+  message: "GET https://api.stripe.com/v1/charges",
+  level: :info,
+  data: %{
+    url: "https://api.stripe.com/v1/charges",
+    method: "GET",
+    status_code: 200
+  }
+})
+
+Sentry.Context.add_breadcrumb(%{
+  category: "db.query",
+  message: "SELECT * FROM orders WHERE id = ?",
+  level: :debug,
+  data: %{duration_ms: 42}
+})
+```
+
+### Before-send hook
+
+Use `:before_send` to mutate or drop events before they are sent:
+
+```elixir
+defmodule MyApp.SentryHooks do
+  def before_send(event) do
+    # Drop events from test/health endpoints
+    if get_in(event, [:request, :url]) |> String.contains?("/health") do
+      nil   # return nil or false to drop the event
+    else
+      # Scrub PII from request headers
+      event = put_in(event, [:request, :headers, "authorization"], "[FILTERED]")
+      # Enrich with deployment metadata
+      put_in(event, [:extra, :deploy_sha], System.get_env("GIT_SHA"))
+    end
+  end
+end
+
+# config/config.exs
+config :sentry,
+  before_send: {MyApp.SentryHooks, :before_send}
+```
+
+### Custom event filter
+
+`Sentry.EventFilter` is called before `before_send` and before sampling.
+Returning `true` from `exclude_exception?/2` silently drops the event:
+
+```elixir
+defmodule MyApp.SentryFilter do
+  @behaviour Sentry.EventFilter
+
+  @impl Sentry.EventFilter
+  def exclude_exception?(%MyApp.NotFoundError{}, _source), do: true
+  def exclude_exception?(%MyApp.ValidationError{}, _source), do: true
+  def exclude_exception?(exception, source) do
+    # Delegate other exceptions to the default filter
+    Sentry.DefaultEventFilter.exclude_exception?(exception, source)
+  end
+end
+
+# config/config.exs
+config :sentry, filter: MyApp.SentryFilter
+```
+
+`Sentry.DefaultEventFilter` already excludes common Phoenix/Plug noise:
+
+- `Ecto.NoResultsError`
+- `Phoenix.Router.NoRouteError`
+- `Plug.Parsers.BadEncodingError`, `ParseError`, `RequestTooLargeError`,
+  `UnsupportedMediaTypeError`
+
+### Fingerprinting and custom grouping
+
+Override Sentry’s default grouping algorithm via `before_send`:
+
+```elixir
+def before_send(%{exception: [%{type: "MyApp.DatabaseError"} | _]} = event) do
+  %{event | fingerprint: ["database-connection", event.extra[:db_host]]}
+end
+
+def before_send(event) do
+  # Extend default grouping with additional discriminators
+  if event.exception != [] do
+    %{event | fingerprint: ["{{ default }}", System.get_env("RELEASE_NODE")]}
+  else
+    event
+  end
+end
+```
+
+### Attachments (since v10.1.0)
+
+```elixir
+Sentry.Context.add_attachment(%Sentry.Attachment{
+  filename: "debug.log",
+  data: File.read!("debug.log")
+})
+
+# Then capture the exception as usual
+Sentry.capture_exception(exception, stacktrace: __STACKTRACE__)
+```
+
+### Flush pending events
+
+```elixir
+# Default 5-second timeout
+Sentry.flush()
+
+# Custom timeout
+Sentry.flush(timeout: 10_000)
+```
+
+## Source Code Context in Production
+
+Without packaging, production releases strip source code — Sentry cannot show the lines
+around an error. Package your source before building:
+
+```bash
+# Run before mix release
+mix sentry.package_source_code
+```
+
+OTP 28 compatibility — use string patterns instead of compiled regexps:
+
+```elixir
+# config/config.exs
+config :sentry,
+  source_code_exclude_patterns: ["/_build/", "/deps/", "/priv/", "/test/"]
+```
+
+## `send_result` Types
+
+| Value                       | Description                                          |
+| --------------------------- | ---------------------------------------------------- |
+| `{:ok, event_id}`           | Event sent successfully (`:send_result: :sync` only) |
+| `:ignored`                  | Not sent (no DSN, filtered, sampled out)             |
+| `:excluded`                 | Dropped by `EventFilter`                             |
+| `{:error, ClientError.t()}` | HTTP-level send error                                |
+
+## Best Practices
+
+- Always pass `stacktrace: __STACKTRACE__` in rescue blocks — stacktraces are not
+  automatically captured in Elixir
+- Set `in_app_otp_apps: [:my_app]` to distinguish your code from library code in
+  Sentry’s issue grouping
+- Use `Sentry.Context.set_user_context/1` early in the request lifecycle (e.g., in a
+  Plug) so every event from that process includes user identity
+- Use `Sentry.EventFilter` for structural filtering (known non-errors), and
+  `before_send` for event mutation or conditional dropping
+- Run `mix sentry.package_source_code` as part of your release build process so
+  production stacktraces show source lines
+
+## Troubleshooting
+
+| Issue                                     | Solution                                                                              |
+| ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| No stack trace on captured exception      | Add `stacktrace: __STACKTRACE__` to `capture_exception/2` inside the rescue block     |
+| Events not appearing                      | Set `log_level: :debug`; check DSN; call `Sentry.flush/1` before process exit         |
+| All events showing “in-app: false”        | Set `in_app_otp_apps: [:my_app]` in config to mark your app’s modules as in-app       |
+| Context missing from async events         | `Sentry.Context` is process-scoped — pass data explicitly to spawned tasks/GenServers |
+| `before_send` not dropping events         | Ensure function returns `nil` or `false` (not an empty map) to drop the event         |
+| Duplicate events (Cowboy + LoggerHandler) | Set `excluded_domains: [:cowboy]` in `LoggerHandler` config (default behavior)        |