sentry-elixir-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Elixir SDK # Sentry Elixir SDK Opinionated wizard that scans your Elixir project and guides you through complete Sentry setup. ## Invoke This Skill When - User asks to "add Sentry to Elixir" or "set up Sentry" in an Elixir or Phoenix app - User wants error monitoring, tracing, logging, or crons in Elixir or Phoenix - User mentions `sentry` hex package, `getsentry/sentry-elixir`, or Elixir Sentry SDK - User wants to monitor exceptions, Plug errors, LiveView errors, or scheduled jobs > **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 config — captures crash reports 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 | `${SKILL_ROOT}/references/error-monitoring.md` | Always (baseline) | | Tracing | `${SKILL_ROOT}/references/tracing.md` | Phoenix / Ecto / OpenTelemetry detected | | Logging | `${SKILL_ROOT}/references/logging.md` | `LoggerHandler` or Sentry Logs setup | | Crons | `${SKILL_ROOT}/references/crons.md` | Oban, Quantum, or periodic jobs detected | For each feature: `Read ${SKILL_ROOT}/references/<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