Elixir

1. 1

   Install the Elixir SDK

   Required

   Add the PostHog Elixir SDK (opens in a new tab) to your list of dependencies in mix.exs:

   Elixir

   elixirCopy

   def deps do
     [
       {:posthog, "~> 2.5"}
     ]
   end

   Then run:

   Terminal

   bashCopy

   mix deps.get

   Source 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. 2

   Configure PostHog

   Required

   Add your project token and host to your config:

   config/config.exs

   elixirCopy

   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_apps to 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

   elixirCopy

   config :posthog,
     api_host: "https://us.i.posthog.com",
   
   

3. 3

   Errors are captured automatically

   Required

   Error Tracking is enabled by default. The SDK hooks into Elixir’s built-in Logger (opens in a new tab) handler system, so it automatically captures:

   • Unhandled exceptions – crashes in GenServers, Tasks, and other OTP processes
   • Logger.error calls – any Logger.error/1 message 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 $exception event with full stack traces.

   What gets captured

   The handler captures log messages based on two rules:

   1. Crash reasons are always captured – any log with a crash_reason metadata (e.g., GenServer/Task crashes) is captured regardless of log level.
   2. Log level filtering – other messages at or above the configured capture_level (default: :error) are captured.

4. 4

   Add Phoenix/Plug integration (recommended)

   Recommended

   If you’re using Phoenix or Plug, add the PostHog.Integrations.Plug middleware to automatically attach HTTP context (URL, host, path, IP) to error events.

   For Phoenix, add it to your endpoint.ex before the router:

   lib/my_app_web/endpoint.ex

   elixirCopy

   plug PostHog.Integrations.Plug
   plug MyAppWeb.Router

   For Plug apps, add it to your router:

   Elixir

   elixirCopy

   defmodule MyRouter do
     use
   
   
   
   
   
   
   

5. 5

   Identify users on errors (recommended)

   Recommended

   By default, errors are attributed to "unknown". To associate errors with specific users, set a context with a distinct_id early in your request lifecycle – for example, in a Plug pipeline after authentication:

   Elixir

   elixirCopy

   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

   elixirCopy

   defmodule MyAppWeb.Plugs.
   
   
   
   
   
   
   
   
   
   
   
   

6. 6

   Configure error tracking options (optional)

   Optional

   The SDK supports several configuration options for Error Tracking:

   config/config.exs

   elixirCopy

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

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

   elixirCopy

   config :posthog,
     api_host: "https://us.i.posthog.com",
     api_key: "<ph_project_token>",
     enable_source_code_context: true,
     root_source_code_paths: [File.
   

8. 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 (opens in a new tab) tab.

   Elixir

   elixirCopy

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

   Elixir

   elixirCopy

Still have questions?

Ask PostHog AI

Was this page useful?

HelpfulCould be better

This automatically includes $current_url, $host, $pathname, and $ip on every error event that occurs during request processing. It also reads X-PostHog-Distinct-Id and X-PostHog-Session-Id tracing headers, so errors can link back to frontend users and sessions when your client SDK sends those headers.

If you’re using PostHog JS (opens in a new tab) on the frontend, configure tracing_headers (opens in a new tab) for your Phoenix or Plug backend hostname. For more details, see the Elixir request context docs (opens in a new tab).

Then add it to your router pipeline:

Elixir

Step 2: Package source code before building your release:

Terminal

This reads all .ex files from your project, compresses them into priv/posthog_source.map, and bundles them with your release. When an error occurs, the SDK matches stack trace frames to the packaged source and includes pre_context, context_line, and post_context in each frame.

Development mode

In development, if root_source_code_paths is set and source files are accessible on disk, the SDK reads them directly at startup – no packaging step needed.

Configuration options

Mix task options

Terminal