AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-error-tracking

Add PostHog error tracking to capture and monitor exceptions. Use after implementing features or reviewing PRs to ensure errors are tracked with stack traces and source maps. Also handles initial PostHog SDK setup if not yet installed.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-error-tracking at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 30

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.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

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

    Then run:

    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

    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

    config :posthog,
      api_host: "https://us.i.posthog.com",
      api_key: "<ph_project_token>",
      in_app_otp_apps: [:my_app]
    
  3. 3

    Errors are captured automatically

    Required

    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.

    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

    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. 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 on the frontend, configure tracing_headers for your Phoenix or Plug backend hostname. For more details, see the Elixir request context docs.

  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:

    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
    end
    

    Then add it to your router pipeline:

    pipeline :browser do
      # ... other plugs
      plug MyAppWeb.Plugs.SetPostHogContext
    end
    
  6. 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 or nil | :error | Minimum log level to capture. Crashes with crash_reason are always captured. Set to nil to only capture crashes. | | metadata | list of atoms or :all | [] | Logger metadata keys to include as event properties. | | enable_error_tracking | boolean | true | Set to false to disable automatic Error Tracking entirely. | | global_properties | map | %{} | Properties added to all captured events (not just errors). |

  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

    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.

    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

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