Connect an Elixir application to Bugsink
When an Elixir process fails, Bugsink gives you the exception, stack trace, and context you need to investigate it.
This guide covers the initial setup, automatic OTP crash reporting, other ways to capture errors, and the useful context you can attach to them. You’ll start by connecting the SDK and crashing one process deliberately to confirm that the error reaches Bugsink.
To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.
Install the SDK
Add the open-source Sentry Elixir SDK and its Finch HTTP client to your Mix dependencies. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:
defp deps do [ # Your existing dependencies... {:finch, "~> 0.21"}, {:jason, "~> 1.4"}, {:sentry, "~> 14.0"} ] enddefp deps do [ # Your existing dependencies... {:finch, "~> 0.21"}, {:jason, "~> 1.4"}, {:sentry, "~> 14.0"} ] end
Fetch the dependencies:
mix deps.getmix deps.get
Make sure :sentry starts with your application. In most applications it can
sit alongside :logger in extra_applications:
def application do [ mod: {InventoryCli.Application, []}, extra_applications: [:logger, :sentry] ] enddef application do [ mod: {InventoryCli.Application, []}, extra_applications: [:logger, :sentry] ] end
Configure the SDK
Configure the DSN early, before the :sentry application starts. Reading it
from the environment keeps the project key out of source control. The logs
option attaches the SDK’s Erlang logger handler; here it reports process
crashes and standalone messages at :error or above:
import Config config :sentry, dsn: System.get_env("SENTRY_DSN"), environment_name: System.get_env("SENTRY_ENVIRONMENT", "production"), release: System.get_env("SENTRY_RELEASE", "inventory_cli@1.0.0"), enable_source_code_context: true, root_source_code_paths: [File.cwd!()], logs: [ capture_log_messages: true, capture_level: :error, capture_metadata: [:order_id] ]import Config config :sentry, dsn: System.get_env("SENTRY_DSN"), environment_name: System.get_env("SENTRY_ENVIRONMENT", "production"), release: System.get_env("SENTRY_RELEASE", "inventory_cli@1.0.0"), enable_source_code_context: true, root_source_code_paths: [File.cwd!()], logs: [ capture_log_messages: true, capture_level: :error, capture_metadata: [:order_id] ]
Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the
application:
export SENTRY_DSN=https://key@bugsink.example/1export SENTRY_DSN=https://key@bugsink.example/1
If you build a Mix release, package the application source before mix release.
That lets Bugsink show the lines around an Elixir stack frame as well as its
filename and line number:
mix sentry.package_source_code mix releasemix sentry.package_source_code mix release
Send a test error
Temporarily raise an exception inside a supervised process or task. The normal OTP crash report is what the logger handler captures; your business code does not need a reporting call:
raise InvalidOrder, "Quantity must be positive [#{order_id}]"raise InvalidOrder, "Quantity must be positive [#{order_id}]"
Run that path once. The process still crashes normally, while the SDK reports its unhandled exception to Bugsink.
See the error in Bugsink
Open your Bugsink project. The new InventoryCli.InvalidOrder issue points at
the application line that raised it and marks the exception as unhandled.
InventoryCli.InvalidOrder
That’s it: unhandled OTP process crashes will now be reported to Bugsink. Remove the deliberate exception and leave the logger handler configured.
Capture other kinds of errors
Automatic crash reporting covers failures which reach Erlang’s logger. You can also report exceptions that your code handles, error-level log messages, and exceptional conditions which do not have an exception.
Handled exceptions
Handled exceptions let your application recover while preserving the original
stack trace in Bugsink. Call capture_exception/2 inside rescue, and pass
__STACKTRACE__ from that same block so the event points to the place where
the exception was raised:
try do InventoryCli.process_order(order_id, 0) rescue exception in InvalidOrder -> Sentry.capture_exception(exception, stacktrace: __STACKTRACE__) endtry do InventoryCli.process_order(order_id, 0) rescue exception in InvalidOrder -> Sentry.capture_exception(exception, stacktrace: __STACKTRACE__) end
The exception remains handled by the application and appears as a separate issue in Bugsink.
InventoryCli.InvalidOrder
Logger messages
Logger messages turn an error your application already records into a Bugsink
event. This is useful for failures such as an unavailable payment provider
which your code cannot sensibly raise. With capture_log_messages: true, an
:error call is captured and the selected metadata travels with it:
Logger.error("Payment provider unavailable", order_id: "elixir-logging")Logger.error("Payment provider unavailable", order_id: "elixir-logging")
error Payment provider unavailableLog Entry
Messages without exceptions
A captured message records an exceptional condition without inventing an
exception. Use capture_message/2 for a failed health check or stalled queue,
and set the level Bugsink should display. There is no exception stack, so use
an exception or normal logging when either describes the failure better:
Sentry.capture_message("Order queue is not responding", level: :error)Sentry.capture_message("Order queue is not responding", level: :error)
error Order queue is not respondingLog Entry
Add useful context
An exception tells you what failed; context helps explain why. Elixir’s SDK keeps this context in logger process metadata, so set it in the same process that captures or logs the error.
Tags
Tags add short, searchable key/value pairs to later events from the current
process. Bugsink already records values such as environment and release; use
your own tags for a component, region, plan, or feature flag. This call makes
order failures searchable as component:orders:
Sentry.Context.set_tags_context(%{component: "orders"})Sentry.Context.set_tags_context(%{component: "orders"})
ordersBugsink preview: component tag
Tags
Extra context
Extra context attaches diagnostic values which you want to inspect but not
search. set_extra_context/1 merges a map into the current process context;
here Bugsink keeps the order identifier and invalid quantity next to the
exception:
Sentry.Context.set_extra_context(%{order_id: order_id, quantity: 0})Sentry.Context.set_extra_context(%{order_id: order_id, quantity: 0})
elixir-handledBugsink preview: order context
Extra
Breadcrumbs
Breadcrumbs record the steps which happened before an error. Add one for an application action the SDK cannot infer, such as beginning an order or retrying an external call. The call does not create an event; its category, message, level, and data appear with the next event from that process:
Sentry.Context.add_breadcrumb(%{ category: "order", message: "Starting order processing", data: %{order_id: order_id}, level: "info" })Sentry.Context.add_breadcrumb(%{ category: "order", message: "Starting order processing", data: %{order_id: order_id}, level: "info" })
Bugsink preview: order breadcrumb
order
Starting order processing
event time
Release and environment
Release and environment identify where a failure happened and which build
introduced it. Set SENTRY_RELEASE and SENTRY_ENVIRONMENT in your deployment,
or provide stable defaults in configuration as above. Bugsink adds both values
to every later event and makes them available for search and grouping context.
Flush before a short-lived process exits
Sentry.flush/1 waits for buffered telemetry to be sent. Long-running OTP
applications normally shut down cleanly without an extra call, but a Mix task,
CLI command, or test process may finish immediately after reporting. Call
Sentry.flush() before that short-lived process exits when delivery matters.
Elixir frameworks and jobs
Phoenix captures unhandled request failures from the Plug pipeline, while Oban reports failed jobs automatically with their worker and queue data.
