references/elixir.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Elixir Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/elixir
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install with the wizard
- Install the Elixir SDK
- Configure PostHog
- Errors are captured automatically
- Add Phoenix/Plug integration (recommended)
- Identify users on errors (recommended)
- Configure error tracking options (optional)
- Enable source code context (optional)
- Verify error tracking
Install with the wizard
Run this command in your project directory to add PostHog to your Elixir project. The wizard detects your framework, installs the SDK, and sets up your first events.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
-
1
Install the Elixir SDK
Required
Add the PostHog Elixir SDK to your list of dependencies in
mix.exs:def deps do [ {:posthog, "~> 2.5"} ] endThen run:
mix deps.getSource code context
The Elixir SDK supports displaying the surrounding lines of source code in the Error Tracking UI. Since Elixir is a compiled language, source files must be packaged at build time. See the source context step below for setup instructions.
-
2
Configure PostHog
Required
Add your project token and host to your config:
config/config.exs
config :posthog, api_host: "https://us.i.posthog.com", api_key: "<ph_project_token>"To get the most out of Error Tracking, set
in_app_otp_appsto your application name. This marks stack trace frames from your code as "in-app", making it easier to identify relevant frames in the PostHog UI:config/config.exs
config :posthog, api_host: "https://us.i.posthog.com", api_key: "<ph_project_token>", in_app_otp_apps: [:my_app] -
3
Errors are captured automatically
Required
Error Tracking is enabled by default. The SDK hooks into Elixir's built-in
Loggerhandler system, so it automatically captures:- Unhandled exceptions – crashes in GenServers, Tasks, and other OTP processes
- Logger.error calls – any
Logger.error/1message at or above the configured level
No additional code is needed. Any crash or error log in your application is sent to PostHog as a
$exceptionevent with full stack traces.What gets captured
The handler captures log messages based on two rules:
- Crash reasons are always captured – any log with a
crash_reasonmetadata (e.g., GenServer/Task crashes) is captured regardless of log level. - Log level filtering – other messages at or above the configured
capture_level(default::error) are captured.
-
4
Add Phoenix/Plug integration (recommended)
Recommended
If you're using Phoenix or Plug, add the
PostHog.Integrations.Plugmiddleware to automatically attach HTTP context (URL, host, path, IP) to error events.For Phoenix, add it to your
endpoint.exbefore the router:lib/my_app_web/endpoint.ex
plug PostHog.Integrations.Plug plug MyAppWeb.RouterFor Plug apps, add it to your router:
defmodule MyRouter do use Plug.Router plug PostHog.Integrations.Plug plug :match plug :dispatch # ... routes endThis automatically includes
$current_url,$host,$pathname, and$ipon every error event that occurs during request processing. It also readsX-PostHog-Distinct-IdandX-PostHog-Session-Idtracing headers, so errors can link back to frontend users and sessions when your client SDK sends those headers.If you're using PostHog JS on the frontend, configure
tracing_headersfor your Phoenix or Plug backend hostname. For more details, see the Elixir request context docs. -
5
Identify users on errors (recommended)
Recommended
By default, errors are attributed to
"unknown". To associate errors with specific users, set a context with adistinct_idearly in your request lifecycle – for example, in a Plug pipeline after authentication:PostHog.set_context(%{distinct_id: current_user.id})This is process-scoped, so any error that occurs in the same process (i.e., the same request) will include the user's distinct ID.
For Phoenix apps, a common pattern is to add this in a plug or controller action:
lib/my_app_web/plugs/set_posthog_context.ex
defmodule MyAppWeb.Plugs.SetPostHogContext do import Plug.Conn def init(opts), do: opts def call(conn, _opts) do if user = conn.assigns[:current_user] do PostHog.set_context(%{distinct_id: user.id}) end conn end endThen add it to your router pipeline:
pipeline :browser do # ... other plugs plug MyAppWeb.Plugs.SetPostHogContext end -
6
Configure error tracking options (optional)
Optional
The SDK supports several configuration options for Error Tracking:
config/config.exs
config :posthog, api_host: "https://us.i.posthog.com", api_key: "<ph_project_token>", # Mark your app's stacktrace frames as "in_app" in_app_otp_apps: [:my_app], # Minimum log level to capture (default: :error) # Set to :warning to also capture warnings, or nil to only capture crashes capture_level: :error, # Logger metadata keys to include in error events (default: []) # Set to :all to include all metadata metadata: [:request_id, :user_id]| Option | Type | Default | Description | | --- | --- | --- | --- | |
in_app_otp_apps| list of atoms |[]| OTP app names whose stacktrace frames are marked as "in_app" in the UI. | |capture_level| log level ornil|:error| Minimum log level to capture. Crashes withcrash_reasonare always captured. Set tonilto only capture crashes. | |metadata| list of atoms or:all|[]| Logger metadata keys to include as event properties. | |enable_error_tracking| boolean |true| Set tofalseto disable automatic Error Tracking entirely. | |global_properties| map |%{}| Properties added to all captured events (not just errors). | -
7
Enable source code context (optional)
Optional
Since Elixir is a compiled language, source files aren't available at runtime by default. To display the surrounding lines of code in PostHog's Error Tracking UI, you need to package your source code at build time.
Step 1: Enable source context in your config:
config/config.exs
config :posthog, api_host: "https://us.i.posthog.com", api_key: "<ph_project_token>", enable_source_code_context: true, root_source_code_paths: [File.cwd!()], context_lines: 5Step 2: Package source code before building your release:
mix posthog.package_source_code mix releaseThis reads all
.exfiles from your project, compresses them intopriv/posthog_source.map, and bundles them with your release. When an error occurs, the SDK matches stack trace frames to the packaged source and includespre_context,context_line, andpost_contextin each frame.Development mode
In development, if
root_source_code_pathsis set and source files are accessible on disk, the SDK reads them directly at startup – no packaging step needed.Configuration options
| Option | Type | Default | Description | | --- | --- | --- | --- | |
enable_source_code_context| boolean |false| Enable source code context in stack frames. | |root_source_code_paths| list of strings |[]| Root paths to scan for source files. | |source_code_path_pattern| string |"**/*.ex"| Glob pattern for files to include. | |source_code_exclude_patterns| list of regexes |[~r"^_build/", ~r"^priv/", ~r"^test/"]| Patterns to exclude. | |context_lines| integer |5| Number of lines to include before and after the error line. | |source_code_map_path| string |nil| Custom path to a packaged source map file. |Mix task options
# Custom output path mix posthog.package_source_code --output path/to/output.map # Custom root paths (overrides config) mix posthog.package_source_code --root-path /app/lib --root-path /app/src -
Verify error tracking
Recommended
Trigger a test exception to confirm errors are being sent to PostHog. You should see them appear in the Error Tracking tab.
# In an IEx session or a test route require Logger Logger.error("Test error from Elixir")Or raise an exception in a controller or GenServer to test crash capture:
# In a Phoenix controller def test_error(conn, _params) do raise "Test exception from Phoenix" end