PostHog.Config (posthog v2.9.1)

PostHog configuration

Configuration Schema

Application Configuration

These are convenience options that only affect how PostHog's own application behaves.

:enable (boolean/0) - Automatically start PostHog? The default value is true.
:enable_error_tracking (boolean/0) - Automatically start the logger handler for error tracking? The default value is true.
:test_mode (boolean/0) - Test mode keeps captured events in memory for assertions instead of sending them to PostHog. The default value is false.

Supervisor Configuration

This is the main options block that configures each supervision tree instance.

:api_host (String.t/0) - https://us.i.posthog.com for US cloud or https://eu.i.posthog.com for EU cloud The default value is "https://us.i.posthog.com".
:api_key (String.t/0) - Your PostHog Project API key. Find it in your project's settings under the Project ID section. If omitted or empty after trimming whitespace, PostHog starts in disabled/no-op mode. The default value is "".
:api_client_module (atom/0) - API client to use The default value is PostHog.API.Client.
:supervisor_name (atom/0) - Name of the supervisor process running PostHog The default value is PostHog.
:metadata - List of Logger metadata keys to include in event properties. Set to :all to include all metadata. This only affects Error Tracking events. The default value is [].
:capture_level - Minimum level for logs that should be captured as errors. Errors with crash_reason are always captured. The default value is :error.
:global_properties (map/0) - Map of properties that should be added to all events The default value is %{}.
:is_server (boolean/0) - Whether this SDK runs as a server. When true (the default), a $is_server: true property is added to all events so PostHog attributes them as server-side. Set to false when using posthog-elixir as a client/CLI so the device OS is attributed normally. The default value is true.
:in_app_otp_apps (list of atom/0) - List of OTP app names of your applications. Stacktrace entries that belong to these apps will be marked as "in_app". The default value is [].
:enable_source_code_context (boolean/0) - Enable source code context in error tracking stack frames. Requires source code to be available at runtime or packaged via mix posthog.package_source_code. The default value is false.
:root_source_code_paths (list of String.t/0) - List of root paths to scan for source files. Used by the source context feature and mix posthog.package_source_code. The default value is [].
:source_code_path_pattern (String.t/0) - Glob pattern for source files to include in source context. The default value is "**/*.ex".
:source_code_exclude_patterns (list of struct of type Regex) - List of regex patterns to exclude from source context. Defaults to excluding _build/, priv/, and test/ directories. The default value is [~r/^_build\//, ~r/^priv\//, ~r/^test\//].
:context_lines (non_neg_integer/0) - Number of source lines to include before and after the error line in stack frames. The default value is 5.
:source_code_map_path (String.t/0) - Custom path to a packaged source map file. Defaults to priv/posthog_source.map in the :posthog application directory.
:test_mode (boolean/0) - Test mode keeps captured events in memory for assertions instead of sending them to PostHog. The default value is false.

Summary

Types

config()

Map containing validated configuration for a PostHog supervision tree.

options()

Keyword options accepted by validate/1 and validate!/1.

Functions

validate(options)

Validates configuration against the supervisor schema.

validate!(options)

Validates configuration and returns a config/0, raising if validation fails.

Types

config()

@opaque config()

Map containing validated configuration for a PostHog supervision tree.

It mostly follows options/0, but also includes runtime values such as the initialized API client, resolved in-app modules, and system global properties. The internal structure should not be relied upon outside of starting PostHog.Supervisor or reading values through PostHog.config/1.

options()

@type options() ::
  {:api_host, binary()}
  | {:api_key, binary()}
  | {:api_client_module, atom()}
  | {:supervisor_name, atom()}
  | {:metadata, [atom()] | term()}
  | {:capture_level, term() | nil}
  | {:global_properties, map()}
  | {:is_server, boolean()}
  | {:in_app_otp_apps, [atom()]}
  | {:enable_source_code_context, boolean()}
  | {:root_source_code_paths, [binary()]}
  | {:source_code_path_pattern, binary()}
  | {:source_code_exclude_patterns, [struct()]}
  | {:context_lines, non_neg_integer()}
  | {:source_code_map_path, binary()}
  | {:test_mode, boolean()}

Keyword options accepted by validate/1 and validate!/1.

See the module documentation for the full schema, defaults, and remarks for each configuration option.

Functions

validate(options)

@spec validate(options()) ::
  {:ok, config()} | {:error, NimbleOptions.ValidationError.t()}

Validates configuration against the supervisor schema.

Parameters

options - keyword list matching options/0.

Returns

Returns {:ok, config} with a normalized config/0 on success, or {:error, %NimbleOptions.ValidationError{}} when the options are invalid.

Remarks

String :api_key and :api_host values are trimmed before validation. A blank :api_host falls back to the default PostHog US ingestion host.

validate!(options)

@spec validate!(options()) :: config()

Validates configuration and returns a config/0, raising if validation fails.

See validate/1 for the accepted options and return shape.