From 73819dc76582dbf617f65074ac51ed3aa2567903 Mon Sep 17 00:00:00 2001 From: Catalin Irimie Date: Thu, 25 Jun 2026 01:21:53 +0300 Subject: [PATCH] docs: update Rust SDK docs for posthog-rs v0.14 (fire-and-forget capture) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v0.14 (the runtime-independent background transport) made `capture` and `capture_batch` non-blocking and infallible — no `async`, no `Result`; they enqueue onto a background worker. Update the docs to match: - Drop `.await.unwrap()` from every `capture` / `capture_batch` example (they now return `()`). `capture_exception` keeps `.await.unwrap()` — still fallible. - Bump the install version pin 0.13.1 -> 0.14. - Rewrite the install-snippet's blocking-mode note: `capture` is non-blocking in both modes (background worker), not a synchronous network call. - Add a "Flushing events" section to the send-events snippet documenting `flush()` / `shutdown()` and the need to flush before process exit so buffered events aren't lost. --- .../docs/experiments/installation/rust.mdx | 2 +- .../_snippets/user-properties-how-to-set.mdx | 2 +- .../docs/integrate/_snippets/install-rust.mdx | 6 +++--- .../_snippets/feature-flags-code-rust.mdx | 8 ++++---- .../_snippets/send-events-rust.mdx | 20 ++++++++++++++++--- ...w-to-capture-anonymous-backend-and-api.mdx | 2 +- ...w-to-capture-identified-events-backend.mdx | 2 +- contents/docs/product-analytics/identify.mdx | 4 ++-- 8 files changed, 30 insertions(+), 16 deletions(-) diff --git a/contents/docs/experiments/installation/rust.mdx b/contents/docs/experiments/installation/rust.mdx index a59bdbbe67f0..ed18927ebfc2 100644 --- a/contents/docs/experiments/installation/rust.mdx +++ b/contents/docs/experiments/installation/rust.mdx @@ -30,7 +30,7 @@ For this tutorial, let's report a conversion event when a user clicks a CTA. In use posthog_rs::Event; let event = Event::new("cta clicked", "user_distinct_id"); -client.capture(event).await.unwrap(); +client.capture(event); ``` diff --git a/contents/docs/getting-started/_snippets/user-properties-how-to-set.mdx b/contents/docs/getting-started/_snippets/user-properties-how-to-set.mdx index 48a183fc2534..6070d379f9c6 100644 --- a/contents/docs/getting-started/_snippets/user-properties-how-to-set.mdx +++ b/contents/docs/getting-started/_snippets/user-properties-how-to-set.mdx @@ -100,7 +100,7 @@ let mut set_once = HashMap::new(); set_once.insert("initial_url", "/blog"); event.insert_prop("$set_once", set_once).unwrap(); -client.capture(event).await.unwrap(); +client.capture(event); ``` ```bash diff --git a/contents/docs/integrate/_snippets/install-rust.mdx b/contents/docs/integrate/_snippets/install-rust.mdx index a5b43a5aad8b..ecb4c2bcbb96 100644 --- a/contents/docs/integrate/_snippets/install-rust.mdx +++ b/contents/docs/integrate/_snippets/install-rust.mdx @@ -2,7 +2,7 @@ Install the `posthog-rs` crate by adding it to your `Cargo.toml`. ```toml file=Cargo.toml [dependencies] -posthog-rs = "0.13.1" +posthog-rs = "0.14" ``` Next, set up the client with your PostHog project key. @@ -19,7 +19,7 @@ If you need to use a synchronous client instead – like we do in our [CLI](http ```toml [dependencies] -posthog-rs = { version = "0.13.1", default-features = false } +posthog-rs = { version = "0.14", default-features = false } ``` -In blocking mode, calls to `capture` and related methods will block until the PostHog event capture API returns – generally this is on the order of tens of milliseconds, but you may want to `thread::spawn` a background thread when you send an event. \ No newline at end of file +With the blocking client, the same methods are available without `.await`. Either way, `capture` is non-blocking: it hands the event to a background worker that batches and sends it, so it returns immediately instead of waiting on the network. Because delivery happens in the background, call `flush()` or `shutdown()` before your program exits, or buffered events may be lost. \ No newline at end of file diff --git a/contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-rust.mdx b/contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-rust.mdx index 1c4670843f8e..811708818ad6 100644 --- a/contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-rust.mdx +++ b/contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-rust.mdx @@ -69,7 +69,7 @@ if flags.is_enabled("flag-key") { let mut event = Event::new("event_name", "distinct_id_of_your_user"); event.with_flags(&flags); -client.capture(event).await.unwrap(); +client.capture(event); ``` By default, this attaches every flag in the snapshot using `$feature/` properties and `$active_feature_flags`. @@ -80,12 +80,12 @@ To reduce event property bloat, pass a filtered snapshot: // Attach only flags accessed with is_enabled() or get_flag() before this call let mut event = Event::new("event_name", "distinct_id_of_your_user"); event.with_flags(&flags.only_accessed()); -client.capture(event).await.unwrap(); +client.capture(event); // Attach only specific flags let mut event = Event::new("event_name", "distinct_id_of_your_user"); event.with_flags(&flags.only(&["checkout-flow", "new-dashboard"])); -client.capture(event).await.unwrap(); +client.capture(event); ``` `only_accessed()` is order-dependent. If you call it before accessing any flags with `is_enabled()` or `get_flag()`, no feature flag properties are attached. @@ -99,7 +99,7 @@ use posthog_rs::Event; let mut event = Event::new("event_name", "distinct_id_of_your_user"); event.insert_prop("$feature/feature-flag-key", "variant-key").unwrap(); -client.capture(event).await.unwrap(); +client.capture(event); ``` ### Evaluating only specific flags diff --git a/contents/docs/integrate/send-events/_snippets/send-events-rust.mdx b/contents/docs/integrate/send-events/_snippets/send-events-rust.mdx index 6cd419fc6de7..9cf3d5f1e159 100644 --- a/contents/docs/integrate/send-events/_snippets/send-events-rust.mdx +++ b/contents/docs/integrate/send-events/_snippets/send-events-rust.mdx @@ -6,7 +6,7 @@ import Intro from "./intro.mdx" ```rust let mut event = Event::new("user_signed_up", "distinct_id_of_the_user"); -client.capture(event).await.unwrap(); +client.capture(event); ``` @@ -19,7 +19,7 @@ let mut event = Event::new("user_signed_up", "distinct_id_of_the_user"); event.insert_prop("login_type", "email").unwrap(); event.insert_prop("is_free_trial", true).unwrap(); -client.capture(event).await.unwrap(); +client.capture(event); ``` ### Batching events @@ -30,5 +30,19 @@ To capture multiple events at once, use `capture_batch()`: let event1 = posthog_rs::Event::new("event 1", "distinct_id_of_user_A"); let event2 = posthog_rs::Event::new("event 2", "distinct_id_of_user_B"); -client.capture_batch(vec![event1, event2], false).await.unwrap(); +client.capture_batch(vec![event1, event2], false); ``` + +### Flushing events + +`capture` and `capture_batch` return as soon as the event is queued. A background worker batches and sends events for you, so capturing never blocks on the network. Because delivery happens in the background, flush before your program exits or buffered events may be lost: + +```rust +// Send queued events now (one delivery attempt per pending batch) +client.flush().await; + +// Or flush, stop the background worker, and wait for it to finish (for example, on shutdown) +client.shutdown().await; +``` + +With the blocking client (`default-features = false`), call `flush()` and `shutdown()` without `.await`. diff --git a/contents/docs/product-analytics/_snippets/how-to-capture-anonymous-backend-and-api.mdx b/contents/docs/product-analytics/_snippets/how-to-capture-anonymous-backend-and-api.mdx index 19d0777fe24d..1bae2ab3b22e 100644 --- a/contents/docs/product-analytics/_snippets/how-to-capture-anonymous-backend-and-api.mdx +++ b/contents/docs/product-analytics/_snippets/how-to-capture-anonymous-backend-and-api.mdx @@ -64,7 +64,7 @@ let mut event = Event::new("your_event_name", "distinct_id_of_the_user"); event.insert_prop("$process_person_profile", false).unwrap(); -client.capture(event).await.unwrap(); +client.capture(event); ``` ```elixir diff --git a/contents/docs/product-analytics/_snippets/how-to-capture-identified-events-backend.mdx b/contents/docs/product-analytics/_snippets/how-to-capture-identified-events-backend.mdx index 6b091fc25fd5..43d06d858590 100644 --- a/contents/docs/product-analytics/_snippets/how-to-capture-identified-events-backend.mdx +++ b/contents/docs/product-analytics/_snippets/how-to-capture-identified-events-backend.mdx @@ -44,7 +44,7 @@ posthog.capture("distinct_id_of_the_user", "your_event_name", new HashMap @@ -341,7 +341,7 @@ use posthog_rs::Event; let mut event = Event::new("$create_alias", "frontend_id"); event.insert_prop("alias", "backend_id").unwrap(); -client.capture(event).await.unwrap(); +client.capture(event); ``` ```bash