Sentry Elixir Sdk

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 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/ before implementing.

---

Phase 1: Detect

Run these commands to understand the project before making any recommendations:

# 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:

---

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:

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:

# mix.exs
defp deps do
  [
    {:sentry, "~> 13.0"},
    {:finch, "~> 0.21"}
    # Add jason if using Elixir < 1.18:
    # {:jason, "~> 1.4"},
  ]
end

mix deps.get

Configure

# 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):

# 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:

# 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:

# 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`

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`

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

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:

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

---

Configuration Reference

Key Config Options

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

---

Verification

Test that Sentry is receiving events:

# Send a test event from your project
MIX_ENV=dev mix sentry.send_test_event

Or add a temporary call in a controller action:

# 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:

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

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

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:

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:

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

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:

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
    {:ok, check_in_id} = Sentry.capture_check_in(
      status: :in_progress,
      monitor_slug: slug,
      monitor_config: monitor_config
    )

    try do
      result = fun.()

      Sentry.capture_check_in(
        check_in_id: check_in_id,
        status: :ok,
        monitor_slug: slug
      )

      {:ok, result}
    rescue
      exception ->
        Sentry.capture_check_in(
          check_in_id: check_in_id,
          status: :error,
          monitor_slug: slug
        )

        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:

# 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):

# 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:

# 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:

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:

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

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

# mix.exs
{:quantum, "~> 3.0"}

# 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.

# 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

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

Error Monitoring — Sentry Elixir SDK

Minimum SDK: sentry v8.0.0+

Configuration

Key config options for error monitoring:

Code Examples

Basic setup

# 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:

try do
  perform_risky_operation()
rescue
  exception ->
    Sentry.capture_exception(exception, stacktrace: __STACKTRACE__)
    reraise exception, __STACKTRACE__
end

With extra context:

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

# 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:

# 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)

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

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:

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:

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:

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)

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

# 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:

# Run before mix release
mix sentry.package_source_code

OTP 28 compatibility — use string patterns instead of compiled regexps:

# config/config.exs
config :sentry,
  source_code_exclude_patterns: ["/_build/", "/deps/", "/priv/", "/test/"]

send_result Types

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

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

# 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

# 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

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

Capturing specific log levels only

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:

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:

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.

# 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

# 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

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:

config :sentry,
  enable_logs: true,
  telemetry_processor_categories: [:log, :error, :check_in, :transaction]

---

How the Two Systems Interact

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

Tracing — Sentry Elixir SDK

Minimum SDK: sentry v11.0.0+ (beta); v12.0.0+ for distributed tracing and LiveView spans

Tracing in the Elixir SDK is implemented via OpenTelemetry. Sentry ships three OTel components: a SpanProcessor, a Sampler, and a Propagator. These integrate with the OpenTelemetry Elixir ecosystem so you can use any OTel-compatible instrumentation library (Phoenix, Ecto, Finch, etc.) and have all spans forwarded to Sentry.

Configuration

Dependencies

# mix.exs
defp deps do
  [
    {:sentry, "~> 12.0"},
    {:finch, "~> 0.21"},
    # OpenTelemetry core
    {:opentelemetry, "~> 1.5"},
    {:opentelemetry_api, "~> 1.4"},
    {:opentelemetry_exporter, "~> 1.0"},
    {:opentelemetry_semantic_conventions, "~> 1.27"},
    # Optional: Phoenix and Ecto auto-instrumentation
    {:opentelemetry_phoenix, "~> 2.0"},
    {:opentelemetry_ecto, "~> 1.2"}
  ]
end

Sentry config

Any non-nil value for :traces_sample_rate enables tracing. Start with 1.0 for development, lower for production:

# config/config.exs
config :sentry,
  dsn: System.get_env("SENTRY_DSN"),
  traces_sample_rate: 1.0     # lower to 0.1 in high-traffic production

OpenTelemetry config

Wire Sentry's SpanProcessor and Sampler into the OTel pipeline:

# config/config.exs
config :opentelemetry,
  span_processor: {Sentry.OpenTelemetry.SpanProcessor, []},
  sampler: {Sentry.OpenTelemetry.Sampler, []}

Distributed tracing (since v12.0.0)

Enable Sentry's propagator to inject and extract sentry-trace and baggage headers:

# config/config.exs
config :opentelemetry,
  span_processor: {Sentry.OpenTelemetry.SpanProcessor, []},
  sampler: {Sentry.OpenTelemetry.Sampler, []},
  text_map_propagators: [
    :trace_context,
    :baggage,
    Sentry.OpenTelemetry.Propagator
  ]

Note: Add Sentry.OpenTelemetry.Propagator after the standard :trace_context and :baggage propagators. It reads and writes the Sentry-specific sentry-trace and baggage headers so spans from Elixir connect to browser and backend spans from other Sentry SDKs.

Sampling

Uniform sample rate

config :sentry,
  traces_sample_rate: 0.1   # 10% of all root spans

Custom sampler function

Use :traces_sampler to apply per-operation logic. Overrides :traces_sample_rate when set:

config :sentry,
  traces_sampler: fn sampling_context ->
    case sampling_context.transaction_context.op do
      "http.server" -> 0.1           # 10% of HTTP requests
      "db.query"    -> 0.01          # 1% of DB queries
      _             -> false         # drop everything else
    end
  end

Drop specific transaction names

Use the built-in drop option of Sentry.OpenTelemetry.Sampler:

config :opentelemetry,
  sampler: {Sentry.OpenTelemetry.Sampler, [drop: ["health_check", "liveness_check"]]}

Phoenix Auto-Instrumentation

opentelemetry_phoenix automatically creates spans for each Phoenix request. Setup in Application.start/2:

# lib/my_app/application.ex
def start(_type, _args) do
  Logger.add_handlers(:my_app)
  OpentelemetryPhoenix.setup()    # instruments Phoenix controllers and LiveView (requires opentelemetry_phoenix)
  OpentelemetryEcto.setup([:my_app, :repo])   # instruments Ecto queries (requires opentelemetry_ecto)

  children = [
    MyApp.Repo,
    MyAppWeb.Endpoint
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

How Spans Map to Sentry

Root spans are created when:

• An HTTP request arrives with no sentry-trace parent (or sampling says yes)
• A LiveView mounts (since v12.0.0)
• You manually start a root-level OTel span

Custom Spans

Use the standard OpenTelemetry API for custom instrumentation:

require OpenTelemetry.Tracer, as: Tracer

def process_order(order_id) do
  Tracer.with_span "process_order", %{attributes: [{"order.id", order_id}]} do
    # All work done inside this block is a child span
    validate_order(order_id)
    charge_payment(order_id)
    send_confirmation(order_id)
  end
end

def validate_order(order_id) do
  Tracer.with_span "validate_order", %{kind: :internal} do
    # Nested child span
    # ...
  end
end

Setting span attributes

Tracer.with_span "db.query" do
  Tracer.set_attributes([
    {"db.system", "postgresql"},
    {"db.statement", "SELECT * FROM orders WHERE id = $1"},
    {"db.rows_affected", 1}
  ])
  # run query
end

Propagating context through async code

OTel context must be explicitly propagated when crossing process boundaries:

# Capture current context before spawning
ctx = OpenTelemetry.Ctx.get_current()

Task.start(fn ->
  # Attach parent context in the new process
  OpenTelemetry.Ctx.attach(ctx)

  Tracer.with_span "async.work" do
    perform_work()
  end
end)

OpenTelemetry Components Reference

Best Practices

• Set traces_sample_rate: 1.0 in development and 0.1–0.2 in production; adjust per route with traces_sampler
• Use the drop: option in Sentry.OpenTelemetry.Sampler to exclude health check endpoints from tracing
• Always call OpentelemetryPhoenix.setup() and OpentelemetryEcto.setup/1 in Application.start/2 before the supervision tree starts
• Propagate OTel context explicitly when spawning tasks or sending messages to other processes
• Add Sentry.OpenTelemetry.Propagator for distributed tracing across services — without it, backend traces won't link to browser Sentry events

Troubleshooting