# `PostHog.Config`
[🔗](https://github.com/posthog/posthog-elixir/blob/v2.18.0/lib/posthog/config.ex#L1)

PostHog configuration

## Configuration Schema

### Application Configuration

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

* `:enable` (`t:boolean/0`) - Automatically start PostHog? The default value is `true`.

* `:enable_error_tracking` (`t:boolean/0`) - Automatically start the logger handler for error tracking? The default value is `true`.

* `:test_mode` (`t: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` (`t: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` (`t: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` (`t:atom/0`) - API client to use The default value is `PostHog.API.Client`.

* `:feature_flags_request_max_retries` (`t:non_neg_integer/0`) - Number of retries for /flags requests after network, transport, or timeout failures. Set to 0 to disable retries. The default value is `1`.

* `:secret_key` - A privileged project secret (`phs_`) or appropriately scoped personal API key (`phx_`)
  required only to fetch local feature flag definitions directly from PostHog. A configured
  `flag_definition_cache_provider` can supply definitions without this key. The default value is `nil`.

* `:enable_local_evaluation` (`t:boolean/0`) - Enable local feature flag evaluation when a non-empty `secret_key` or a `flag_definition_cache_provider` is configured. The default value is `true`.

* `:feature_flags_poll_interval_ms` (`t:pos_integer/0`) - Interval in milliseconds between local feature flag definition refreshes. The default value is `30000`.

* `:flag_definition_cache_provider` - Optional `{module, state}` implementing `PostHog.FeatureFlags.FlagDefinitionCacheProvider`. The default value is `nil`.

* `:flag_definition_cache_provider_timeout_ms` (`t:pos_integer/0`) - Maximum time in milliseconds allowed for each definition cache provider callback. The default value is `5000`.

* `:flag_definition_request_timeout_ms` (`t:pos_integer/0`) - Maximum time in milliseconds allowed for a local feature flag definition request. The default value is `10000`.

* `:supervisor_name` (`t: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` (`t:map/0`) - Map of properties that should be added to all events The default value is `%{}`.

* `:before_send` - Callback invoked with the fully enriched event before it is queued. Return the event to send a modified version, or nil to drop it. The default value is `nil`.

* `:is_server` (`t: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 `t: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` (`t: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 `t: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` (`t: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` (`t: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` (`t:String.t/0`) - Custom path to a packaged source map file. Defaults to `priv/posthog_source.map` in the `:posthog` application directory.

* `:test_mode` (`t:boolean/0`) - Test mode keeps captured events in memory for assertions instead of sending them to PostHog. The default value is `false`.

# `config`

```elixir
@opaque config()
```

Map containing validated configuration for a PostHog supervision tree.

It mostly follows `t: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`

```elixir
@type options() ::
  {:api_host, binary()}
  | {:api_key, binary()}
  | {:api_client_module, atom()}
  | {:feature_flags_request_max_retries, non_neg_integer()}
  | {:secret_key, binary() | nil}
  | {:enable_local_evaluation, boolean()}
  | {:feature_flags_poll_interval_ms, pos_integer()}
  | {:flag_definition_cache_provider, {atom(), term()} | nil}
  | {:flag_definition_cache_provider_timeout_ms, pos_integer()}
  | {:flag_definition_request_timeout_ms, pos_integer()}
  | {:supervisor_name, atom()}
  | {:metadata, [atom()] | term()}
  | {:capture_level, term() | nil}
  | {:global_properties, map()}
  | {:before_send, (term() -> term()) | nil}
  | {: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.

# `validate`

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

Validates configuration against the supervisor schema.

## Parameters

- `options` - keyword list matching `t:options/0`.

## Returns

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

## Remarks

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

# `validate!`

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

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*