All Skills > SDK Setup > 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 hex package, , 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 v12.0.2, requires Elixir ~> 1.13).
Always verify against
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 |
|---|
| already in ? | Skip install; go to Phase 2 (configure features) |
| Phoenix detected? | Add , , optionally |
| LiveView detected? | Add to the macro in |
| Oban detected? | Recommend Crons + error capture via Oban integration |
| Quantum detected? | Recommend Crons via Quantum integration |
| OpenTelemetry already present? | Tracing setup only needs 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 — 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 — captures crashes that aren't explicit calls |
| Tracing | Phoenix, Plug, Ecto, or OpenTelemetry imports detected |
| Crons | Oban, Quantum, or periodic / 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
,
,
, and
lib/my_app/application.ex
.
Once it finishes, come back and skip to Verification.
If the user skips the Igniter installer, proceed with Option 2 (Manual Setup) below.
Option 2: Manual Setup
Install
elixir
# mix.exs
defp deps do
[
{:sentry, "~> 12.0"},
{:finch, "~> 0.21"}
# Add jason if using Elixir < 1.18:
# {:jason, "~> 1.4"},
]
end
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
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: is only needed for the
Cowboy adapter. Phoenix 1.7+ defaults to
Bandit, where
is harmless but unnecessary.
is always recommended — it enriches events with HTTP request data.
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
| 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 |
|---|
| | | SDK disabled if nil; env: |
| | | e.g., ; env: |
| | | e.g., ; env: |
| | | Error event sample rate (0.0–1.0) |
:enable_source_code_context
| | | Include source lines around errors |
| | | Required when source context is enabled |
| | | OTP apps whose modules are "in-app" in stacktraces |
| (event -> event | nil) | {m, f}
| | Hook to mutate or drop error events |
| (event, result -> any) | {m, f}
| | Hook called after event is sent |
| | Sentry.DefaultEventFilter
| Module implementing |
| | | Max breadcrumbs per process |
| | | Deduplicate identical events within ~30 seconds |
| | | Global tags sent with every event |
| | | Non-nil enables tracing (requires OTel setup) |
| | | Custom per-transaction sampling |
| | | Enable Sentry Logs Protocol (v12.0.0+) |
| | | Capture events in-memory for testing |
Environment Variables
| Variable | Maps to | Purpose |
|---|
| | Data Source Name |
| | App version (e.g., ) |
| | 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:
- Set
config :sentry, log_level: :debug
- Verify is set and the project exists
- Confirm 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:
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 is set; run mix sentry.send_test_event
|
| Missing stack traces on captured exceptions | Pass stacktrace: __STACKTRACE__
Sentry.capture_exception(e, stacktrace: __STACKTRACE__)
|
| not working on Bandit | is Cowboy-only; with Bandit errors surface via |
| Source code context missing in production | Run mix sentry.package_source_code
|
| Context not appearing on async events | 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 in job meta |
| Duplicate events from Cowboy crashes | Set excluded_domains: [:cowboy]
|
| not starting | Ensure is in deps; Finch is the default HTTP client since v12.0.0 |
| JSON encoding error | Add and set for Elixir < 1.18 |