Struct Client 

pub struct Client { /* private fields */ }

A Client facilitates interactions with the PostHog API over HTTP.

Implementations

impl Client

pub fn capture(&self, event: Event)

Capture the provided event, sending it to PostHog.

Parameters

• event: Event name, distinct ID, properties, timestamp, groups, and optional feature flag state to send.

Remarks

Fire-and-forget: the event is handed to the background worker, which batches, sends, and retries it. Returns once the event is queued — not once it is delivered, and delivery failures are not surfaced to the caller. Disabled clients and a full queue drop the event (the latter with a single warning).

pub async fn flush(&self)

Flush queued events, returning once the worker has attempted delivery of everything queued before this call. Transient failures are kept for retry (the call still returns without error). A no-op for disabled clients.

pub async fn shutdown(&self)

Flush, stop the background worker, and join it. Idempotent: subsequent calls are no-ops. After shutdown, capture drops events. A no-op for disabled clients.

pub async fn capture_exception<E>(&self, error: &E) -> Result<(), Error>

where E: StdError + ?Sized,

Capture a Rust error personlessly, sending it to PostHog Error Tracking.

The error’s type, message, and full source() chain are sent as $exception_list, with a stacktrace of the capture site attached to the first entry (see ErrorTrackingOptions::capture_stacktrace).

Accepts any std::error::Error, including &dyn Error. A Box<dyn Error> does not implement Error itself, so pass the dereferenced trait object: capture_exception(&*boxed).

To associate the exception with a person or attach custom properties, groups, a fingerprint, or a severity level, use Client::capture_exception_with.

Examples

let client = posthog_rs::client("phc_project_api_key").await;
let error = std::io::Error::other("checkout failed");

client.capture_exception(&error).await?;

pub async fn capture_exception_with<E>( &self, error: &E, options: CaptureExceptionOptions, ) -> Result<(), Error>

where E: StdError + ?Sized,

Capture a Rust error with optional context, sending it to PostHog Error Tracking.

Set CaptureExceptionOptions::distinct_id to associate the exception with a person; without it the exception is captured personlessly.

Examples

use posthog_rs::CaptureExceptionOptions;

let client = posthog_rs::client("phc_project_api_key").await;
let error = std::io::Error::other("checkout failed");

client
    .capture_exception_with(
        &error,
        CaptureExceptionOptions::new()
            .distinct_id("user-123")
            .property("route", "/checkout")?,
    )
    .await?;

pub fn capture_batch(&self, events: Vec<Event>, historical_migration: bool)

Capture a collection of events with a single request.

Events are sent to the /batch/ endpoint.

Parameters

• events: Events to send in the batch.
• historical_migration: Set to true to route events to the historical ingestion topic, bypassing the main pipeline.

Remarks

Fire-and-forget, like Client::capture. The batch is enqueued per event rather than atomically, so if the bounded queue fills partway through, the remaining events are dropped (with the usual single full-queue warning).

pub async fn capture_immediate( &self, event: Event, ) -> Result<CaptureSummary, Error>

Capture a single event and await confirmation that the request completed.

The immediate-delivery counterpart to Client::capture. This is a convenience wrapper over Client::capture_batch_immediate with a one-event batch; see it for full semantics.

pub async fn capture_batch_immediate( &self, events: Vec<Event>, historical_migration: bool, ) -> Result<CaptureSummary, Error>

Capture a batch of events and await confirmation that the request completed, returning a CaptureSummary describing the outcome.

The immediate-delivery counterpart to Client::capture_batch. Prefer the fire-and-forget Client::capture/Client::capture_batch for normal analytics; reach for this only when the caller must know the batch persisted before advancing its own durable state.

Parameters

• events: Events to send in a single request.
• historical_migration: Route events to the historical ingestion topic.

Behavior

Sends inline (bypassing the background worker) and retries transient failures per the client’s retry configuration. On the capture-v1 pipeline a returned Ok can still report unpersisted events — inspect CaptureSummary::all_persisted. Does NOT fire on_error hooks: the returned Result is the delivery signal. Disabled clients and an empty (or fully before_send-filtered) batch return a default CaptureSummary.

Errors

Returns Error when the request is rejected with a terminal status or the retry budget is exhausted without a successful response.

pub async fn get_feature_flags<S: Into<String>>( &self, distinct_id: S, groups: Option<HashMap<String, String>>, person_properties: Option<HashMap<String, Value>>, group_properties: Option<HashMap<String, HashMap<String, Value>>>, ) -> Result<(HashMap<String, FlagValue>, HashMap<String, Value>), Error>

Get all remote feature flags and payloads for a user.

For new code, prefer Client::evaluate_flags so flag reads are deduplicated and can be attached to captured events with Event::with_flags.

Parameters

• distinct_id: User distinct ID.
• groups: Optional group keys for group-targeted flags.
• person_properties: Optional person properties for release conditions.
• group_properties: Optional group properties for group-targeted release conditions.

Returns

A tuple of (feature_flags, feature_flag_payloads), each keyed by flag key. Disabled clients return two empty maps.

Errors

Returns Error::Connection for request failures or non-success HTTP statuses, and Error::Serialization when the response cannot be parsed.

pub async fn get_feature_flag<K: Into<String>, D: Into<String>>( &self, key: K, distinct_id: D, groups: Option<HashMap<String, String>>, person_properties: Option<HashMap<String, Value>>, group_properties: Option<HashMap<String, HashMap<String, Value>>>, ) -> Result<Option<FlagValue>, Error>

👎Deprecated since 0.6.0:

Use Client::evaluate_flags() to fetch a snapshot, then call .get_flag(key) on it. The snapshot deduplicates $feature_flag_called events and supports attaching rich metadata to captured events via Event::with_flags().

Get a specific feature flag value for a user.

Parameters

• key: Feature flag key.
• distinct_id: User distinct ID.
• groups: Optional group keys for group-targeted flags.
• person_properties: Optional person properties for release conditions.
• group_properties: Optional group properties for group-targeted release conditions.

Returns

Ok(Some(value)) when the flag is returned, Ok(None) when it is not returned or local-only evaluation cannot resolve it.

Errors

Returns errors from remote /flags requests or response parsing.

pub async fn is_feature_enabled<K: Into<String>, D: Into<String>>( &self, key: K, distinct_id: D, groups: Option<HashMap<String, String>>, person_properties: Option<HashMap<String, Value>>, group_properties: Option<HashMap<String, HashMap<String, Value>>>, ) -> Result<bool, Error>

👎Deprecated since 0.6.0:

Use Client::evaluate_flags() to fetch a snapshot, then call .is_enabled(key) on it. The snapshot deduplicates $feature_flag_called events and supports attaching rich metadata to captured events via Event::with_flags().

Check if a feature flag is enabled for a user.

Returns

true for FlagValue::Boolean(true) or any multivariate variant, false for disabled or missing flags.

Errors

Returns errors from Client::get_feature_flag.

pub async fn get_feature_flag_payload<K: Into<String>, D: Into<String>>( &self, key: K, distinct_id: D, ) -> Result<Option<Value>, Error>

👎Deprecated since 0.6.0:

Use Client::evaluate_flags() to fetch a snapshot, then call .get_flag_payload(key) on it. Reading the payload from a snapshot is event-free, matching this method’s behavior, and avoids the per-call /flags request.

Get a feature flag payload for a user.

Parameters

• key: Feature flag key.
• distinct_id: User distinct ID.

Returns

The JSON payload for the flag, if one was returned. This method does not emit $feature_flag_called events.

Errors

Returns Error::Connection for request failures and Error::Serialization when the response cannot be parsed.

pub fn evaluate_feature_flag_locally( &self, flag: &FeatureFlag, distinct_id: &str, person_properties: &HashMap<String, Value>, groups: &HashMap<String, String>, group_properties: &HashMap<String, HashMap<String, Value>>, ) -> Result<FlagValue, Error>

Evaluate a supplied feature flag definition locally.

groups and group_properties are only consulted when the flag (or one of its conditions) targets a group; pass empty maps for person flags.

Parameters

• flag: Feature flag definition to evaluate.
• distinct_id: User distinct ID.
• person_properties: Person properties available to release conditions.
• groups: Group keys for group-targeted flags.
• group_properties: Group properties for group-targeted release conditions.

Errors

Returns Error::InconclusiveMatch when the flag cannot be evaluated locally with the supplied context.

pub async fn evaluate_flags<S: Into<String>>( &self, distinct_id: S, options: EvaluateFlagsOptions, ) -> Result<FeatureFlagEvaluations, Error>

Evaluate feature flags for distinct_id, returning a FeatureFlagEvaluations snapshot.

Each is_enabled / get_flag call on the returned snapshot fires a dedup-aware $feature_flag_called event with full metadata, and the snapshot can be passed to Event::with_flags so a downstream Client::capture inherits $feature/<key> and $active_feature_flags without an extra /flags request.

Parameters

• distinct_id: User distinct ID. Empty values return an empty snapshot.
• options: Optional groups, properties, GeoIP override, local-only mode, and flag-key filtering.

Errors

Returns Error::Connection or Error::Serialization when remote evaluation is required and the /flags request fails before any local results are available.

Trait Implementations

impl Drop for Client

fn drop(&mut self)

Best-effort flush and worker join on drop. A blocking drain (the async shutdown can’t run in a destructor), so dropping a Client inside an async task blocks that executor thread until the drain completes (up to shutdown_timeout_ms plus any in-flight request) — prefer an explicit shutdown().await first, which makes this a no-op.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.