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"}
  ]
end

Fetch the dependencies:

mix 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]
  ]
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]
  ]

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export 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 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}]"

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.

Bugsink preview

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__)
end

The exception remains handled by the application and appears as a separate issue in Bugsink.

Bugsink preview

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

Bugsink preview

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)

Bugsink preview

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"})

Bugsink preview: component tag
Bugsink preview

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

Bugsink preview: order context
Bugsink preview

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"
})

Bugsink preview: order breadcrumb
Bugsink preview

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.