Elixir Error Tracking installation

Add the PostHog Elixir SDK to your list of dependencies in mix.exs:

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

Then run:

mix deps.get

Add your project token and host to your config:

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 :posthog,
  api_host: "https://us.i.posthog.com",
  api_key: "<ph_project_token>",
  in_app_otp_apps: [:my_app]

Error Tracking is enabled by default. The SDK hooks into Elixir's built-in Logger 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.

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:

plug PostHog.Integrations.Plug
plug MyAppWeb.Router

For Plug apps, add it to your router:

defmodule MyRouter do
  use Plug.Router

  plug PostHog.Integrations.Plug
  plug :match
  plug :dispatch

  # ... routes
end

This automatically includes $current_url, $host, $pathname, and $ip on every error event that occurs during request processing.

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:

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:

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
end

Then add it to your router pipeline:

pipeline :browser do
  # ... other plugs
  plug MyAppWeb.Plugs.SetPostHogContext
end

The SDK supports several configuration options for Error Tracking:

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]

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

Step 2: Package source code before building your release:

mix posthog.package_source_code
mix release

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.

Configuration options

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

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