Struct ClientOptionsBuilder

Source

pub struct ClientOptionsBuilder { /* private fields */ }

Expand description

Builder for ClientOptions.

Implementations§

Source §

impl ClientOptionsBuilder

Source

pub fn host<VALUE: Into<String>>(&mut self, value: VALUE) -> &mut Self

Host URL for the PostHog API. Defaults to the US ingestion endpoint. App hosts such as https://eu.posthog.com are normalized to ingestion hosts before requests are sent.

Source

pub fn api_key(&mut self, value: String) -> &mut Self

PostHog project API key (project token). If missing or blank, the client is disabled.

Source

pub fn request_timeout_seconds(&mut self, value: u64) -> &mut Self

Request timeout in seconds for capture, batch, and local evaluation definition requests. Defaults to 30.

Source

pub fn secret_key<VALUE: Into<String>>(&mut self, value: VALUE) -> &mut Self

Secret key used for local feature flag evaluation and remote config.

Accepts either a Personal API Key (phx_...) or a Project Secret API Key (phs_...). Required when enable_local_evaluation is true.

Source

pub fn enable_local_evaluation(&mut self, value: bool) -> &mut Self

Enable local evaluation of feature flags using a background definitions poller.

Source

pub fn poll_interval_seconds(&mut self, value: u64) -> &mut Self

Interval for polling flag definitions, in seconds. Defaults to 30.

Source

pub fn disabled(&mut self, value: bool) -> &mut Self

Disable tracking and remote flag requests. Useful for development and tests.

Source

pub fn disable_geoip(&mut self, value: bool) -> &mut Self

Disable automatic GeoIP enrichment for capture and flag requests.

Source

pub fn is_server(&mut self, value: bool) -> &mut Self

Whether events originate from a server-side runtime. Defaults to true, which stamps $is_server: true so PostHog won’t attribute the host OS to the user. Set false for client/CLI use (the property is then omitted).

Source

pub fn feature_flags_request_timeout_seconds(&mut self, value: u64) -> &mut Self

Timeout in seconds for remote /flags requests. Defaults to 3.

Source

pub fn feature_flags_request_max_retries(&mut self, value: u32) -> &mut Self

Maximum number of retries after a transient remote /flags failure (transport error or HTTP 502/504). Defaults to 1. Set to 0 to disable retries.

Source

pub fn error_tracking(&mut self, value: ErrorTrackingOptions) -> &mut Self

Error tracking stacktrace and frame classification options

Source

pub fn local_evaluation_only(&mut self, value: bool) -> &mut Self

When true, never fall back to the remote API for flag evaluation. If local evaluation is inconclusive (flag not cached or missing properties), the SDK returns Ok(None) instead of making a network call. Only meaningful when enable_local_evaluation is also true.

Source

pub fn max_capture_attempts(&mut self, value: u32) -> &mut Self

Maximum number of attempts for V1 capture requests (default: 3). Includes the initial attempt, so 3 means 1 initial + 2 retries.

Source

pub fn retry_initial_backoff_ms(&mut self, value: u64) -> &mut Self

Initial retry backoff duration in milliseconds (default: 200)

Source

pub fn retry_max_backoff_ms(&mut self, value: u64) -> &mut Self

Maximum retry backoff duration in milliseconds (default: 30000)

Source

pub fn flush_at(&mut self, value: usize) -> &mut Self

Number of buffered events that triggers an automatic flush (default: 100).

Source

pub fn max_batch_size(&mut self, value: usize) -> &mut Self

Maximum number of events sent in a single batch request (default: 100). A flush of more than this many events is split into multiple requests.

Source

pub fn flush_interval_ms(&mut self, value: u64) -> &mut Self

Interval between automatic time-based flushes, in milliseconds (default: 5000).

Source

pub fn max_queue_size(&mut self, value: usize) -> &mut Self

Maximum number of events buffered before new events are dropped (default: 10000). A single warning is logged while the queue is full.

Source

pub fn shutdown_timeout_ms(&mut self, value: u64) -> &mut Self

Maximum time shutdown() and Drop spend draining buffered and retrying events before abandoning the rest, in milliseconds (default: 30000). This bounds the drain itself, including any delivery the drain starts. It does not bound work already underway: the single background worker performs one blocking send at a time, so an automatic flush or drain in progress when shutdown is requested runs to completion first — up to request_timeout_seconds per in-flight batch, so a large auto-drain can delay teardown by several request timeouts. flush() is unaffected.

Source

pub fn capture_compression(&mut self, value: CaptureCompression) -> &mut Self

Optional request-body compression. When None (default), bodies are sent uncompressed. The V0 pipeline supports Gzip only; V1 supports all variants.

Source §

impl ClientOptionsBuilder

Source

pub fn before_send<F>(&mut self, hook: F) -> &mut Self
where F: FnMut(Event) -> Option<Event> + Send + 'static,

Add a hook that can modify or discard events before they are sent.

Hooks should avoid panicking. Panics are caught and drop the current event, but any mutable state captured by the hook may be left partially updated and will be reused on subsequent calls.

Source

pub fn on_error<F>(&mut self, hook: F) -> &mut Self
where F: Fn(&PostHogError<'_>) + Send + Sync + 'static,

Add a hook invoked once per terminal failure on an SDK network surface.

The hook receives a PostHogError for a capture batch the SDK gave up delivering, a failed remote /flags request, or a failed local-evaluation poll. Multiple hooks fire in registration order.

§Observability only — never emit from the hook

The hook MUST NOT call back into the SDK (capture/capture_batch/ capture_exception, flush, or shutdown): emitting an event while handling a capture failure forms an amplification loop. The hook is Fn + Send + Sync and invoked without holding any SDK lock, so it may run concurrently on multiple threads and must be internally thread-safe. Keep it cheap and non-blocking; the capture hook runs on the background transport thread. Panics are caught and ignored.

Registering a hook silences the default WARN for terminal capture reject/exhaustion and serialization failures (the caller now owns that signal). Shutdown-timeout, queue-full, and before_send drops keep their WARN logs and do not fire the hook — they are not delivery failures. The existing /flags and poller WARN logs are unaffected.

Source

pub fn build(&self) -> Result<ClientOptions, ClientOptionsBuilderError>

Build sanitized ClientOptions.

Missing or whitespace-only API keys are allowed and disable the client so SDK initialization remains infallible while avoiding requests with an empty API key.