feat: add manual rust error tracking (#129)

* feat: add manual rust error tracking

* test: align error tracking payload assertions

* fix: address error tracking review comments

* feat: add anonymous error capture helper

* docs: use version placeholder in README quickstart

* refactor: remove public exception_from_error helper

Callers build payloads with ExceptionCapture::from_error directly;
capture_error/capture_error_anon keep applying client-level Error
Tracking options internally.

* refactor: make Exception payload-only and apply client options at capture

Exceptions are now plain events: Exception holds only exception-specific
data (items, fingerprint, level) and converts into an Event via
into_event/into_event_anon, so distinct ID, props, groups, flags, and
timestamps use the standard Event API instead of duplicated builders.

Raw frames are captured unclassified at construction and client-level
ErrorTrackingOptions (stacktrace opt-out, in-app classification, frame
and source limits) are applied at capture time in the v0/v1 prep paths,
so free-standing constructors always honor the capturing client's
configuration.

* refactor: unify error capture under capture_exception

Replace capture_error/capture_error_anon and the personless
capture_exception(Exception) with capture_exception(&error, distinct_id)
and capture_exception_anon(&error) across the async, blocking, and global
APIs, matching the capture_exception entry point of other PostHog SDKs.
Built Exception payloads now go through Exception::into_event + capture.

* refactor: adopt options-based capture_exception API

capture_exception(&error) now captures personlessly, and
capture_exception_with(&error, CaptureExceptionOptions) carries the
optional context: distinct_id, custom properties, groups, fingerprint,
and severity level. capture_exception_anon is removed, and the
Exception payload type with its into_event conversions is no longer
exported - python/node expose no payload tier either, keeping the
public surface to two methods plus one options struct.

* refactor: finalize exception events eagerly in build_exception_event

Exception construction is now reachable only through client methods that
hold the client's ErrorTrackingOptions, so client policy (stack walk gating,
in-app classification, frame and source-chain limits, reserved $exception_*
properties) is applied when the event is built instead of at capture time.
Disabling capture_stacktrace now skips the stack walk entirely rather than
discarding the captured frames at send.

This removes the pending-exception staging field from Event and reverts
prepare_event/build_events to main's exception-agnostic shapes.

* refactor: make frame and source-chain limits internal constants

max_frames and max_error_sources leave ErrorTrackingOptions: no other SDK
exposes them, nobody asked for tunability, and the configurable source cap
silently clamped to the build-time bound anyway. The caps remain as
MAX_FRAMES/MAX_ERROR_SOURCES; re-adding knobs later is non-breaking.

* feat: emit one frame per inlined function

resolve_frame yields a symbol per logical layer when the compiler inlined
functions into a physical frame; the previous first-symbol-only guard kept
the innermost layer and silently dropped the inline ancestry, which exists
in no other frame. Emit each layer as its own frame (innermost first,
matching current-first capture order), like the Go runtime does for our Go
SDK. MAX_FRAMES now counts logical frames.

* refactor: mark exception internals pub(crate)

The error_tracking module is private, so these were never reachable, but
the bare pub kept reading as public API in review diffs. Make the
crate-internal surface explicit; the public ET API stays exactly
capture_exception/_with, CaptureExceptionOptions, and ErrorTrackingOptions.

* docs: document the error tracking public surface

/// docs with examples on capture_exception/_with, CaptureExceptionOptions,
and every ErrorTrackingOptions field (derive_builder copies field docs onto
the generated setters), including the capture-site-vs-origin stacktrace
caveat and crate-prefix in-app patterns. README gains the configuration
example and a captured-properties table.

* test: split error tracking integration tests by capture transport

test_error_tracking.rs asserts the V0 wire shape, so it is gated out under
capture-v1; test_error_tracking_v1.rs adds V1-envelope twins (single-attempt
clients against an empty-results 2xx, asserting one well-formed request).
Fixes the error-tracking + capture-v1 combo failing with 404s against
v0-shaped mocks.

* fix: clean up lints surfaced by feature-combo clippy

before_send on the flag-event hosts is only read by the v0 ship path, so
scope a dead_code allow under capture-v1 (the v1 flag path does not apply
before_send hooks today). Restructure the blocking capture cfg splits as
tail blocks so needless_return doesn't fire under capture-v1.

* ci: run error tracking feature combinations

The matrix never enabled error-tracking, so every ET test compiled to
nothing in CI; cover it alone and combined with capture-v1, on both
clients.

* build: drop the backtrace version pin

The pin guarded the declared 1.78 MSRV, but every toolchain it could help
(1.78-1.84) is already locked out by edition-2024 transitive manifests
(idna_adapter via reqwest->url, present on main's lockfile too), so it
protects nothing reachable while exporting =0.3.74 resolution conflicts to
any consumer tree wanting backtrace ^0.3.75. Verified against 0.3.76 across
all feature combos. Whether to restore the 1.78 floor or bump rust-version
is left as a separate decision.

* feat: enable error tracking by default

Every other PostHog SDK ships error tracking in the box; with the backtrace
pin gone there is no resolution cost to carry it as a default feature, and
capture_exception works out of the box. Opt out with default-features =
false. The CI matrix collapses accordingly: the default and capture-v1 steps
now cover error tracking on the async client, keeping explicit steps only
for the blocking client.

Author: cat-ph

.github/workflows/ci.yaml

@@ -143,6 +143,12 @@ jobs:
           - name: Unit test (capture-v1, blocking client)
             cache-key: capture-v1-blocking-client
             command: cargo test --verbose --no-default-features --features capture-v1
+          - name: Unit test (error-tracking, blocking client)
+            cache-key: error-tracking-blocking-client
+            command: cargo test --verbose --no-default-features --features error-tracking
+          - name: Unit test (error-tracking + capture-v1, blocking client)
+            cache-key: error-tracking-capture-v1-blocking-client
+            command: cargo test --verbose --no-default-features --features error-tracking,capture-v1
           - name: E2E test
             cache-key: e2e
             command: cargo test --verbose --features e2e-test --no-default-features

.sampo/changesets/rust-error-tracking.md

@@ -0,0 +1,5 @@
+---
+cargo/posthog-rs: minor
+---
+
+Add manual Rust error tracking capture APIs, enabled by default via the `error-tracking` feature.

Cargo.lock

@@ -21,6 +21,7 @@ serde_json = "1.0.64"
 semver = "1.0.24"
 derive_builder = "0.20.2"
 uuid = { version = "1.13.2", features = ["serde", "v7"] }
+backtrace = { version = "0.3.74", optional = true }
 os_info = "3.14"
 sha1 = "0.10"
 regex = "1.10"
@@ -45,11 +46,12 @@ futures = "0.3"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
 [features]
-default = ["async-client"]
+default = ["async-client", "error-tracking"]
 e2e-test = []
 async-client = ["tokio"]
 capture-v1 = ["brotli", "zstd"]
 test-harness = []
+error-tracking = ["dep:backtrace"]
 
 [workspace]
 members = [".", "compliance/adapter"]

Cargo.toml

@@ -9,6 +9,7 @@ The official Rust SDK for [PostHog](https://posthog.com). See the [PostHog docs]
 
 - **Event capture** - Send events to PostHog for product analytics
 - **Feature flags** - Evaluate feature flags with local or remote evaluation
+- **Error tracking** - Capture Rust errors with stack traces
 - **A/B testing** - Support for multivariate flags and experiments
 - **Group analytics** - Track events and flags for B2B use cases
 - **Async and sync clients** - Choose based on your runtime
@@ -19,7 +20,7 @@ Add `posthog-rs` to your `Cargo.toml`.
 
 ```toml
 [dependencies]
-posthog-rs = "0.3.7"
+posthog-rs = "$version"
 ```
 
 ```rust
@@ -46,6 +47,65 @@ if is_enabled {
 }
 ```
 
+## Error Tracking
+
+Capture Rust errors manually with stack traces and send them to PostHog Error Tracking.
+Error tracking ships enabled by default (the `error-tracking` feature); opt out
+with `default-features = false`.
+
+```rust
+use posthog_rs::{client, CaptureExceptionOptions};
+
+let client = client("your-api-key").await;
+let error = std::io::Error::new(std::io::ErrorKind::Other, "checkout failed");
+
+// Associate the exception with a person and attach optional context.
+client.capture_exception_with(
+    &error,
+    CaptureExceptionOptions::new()
+        .distinct_id("user-123")
+        .property("route", "/checkout").unwrap()
+        .fingerprint("checkout-error"),
+).await.unwrap();
+
+// Bare capture is personless.
+client.capture_exception(&error).await.unwrap();
+```
+
+`CaptureExceptionOptions` carries everything optional: `distinct_id` to
+associate a person, custom properties, groups, a custom `fingerprint`, and a
+severity `level` (defaults to `"error"`).
+
+The stacktrace is captured at the call site (a bubbled-up `Err` carries no
+stack of its own); the error's type, message, and `source()` chain are always
+sent regardless. Configure stacktrace capture and in-app frame classification
+through `ErrorTrackingOptionsBuilder` on `ClientOptions::error_tracking` —
+in-app patterns match both file paths and function symbols, so a crate prefix
+like `"other_crate::"` marks that crate's frames as library code:
+
+```rust
+use posthog_rs::{ClientOptionsBuilder, ErrorTrackingOptionsBuilder};
+
+let options = ClientOptionsBuilder::default()
+    .api_key("your-api-key".to_string())
+    .error_tracking(
+        ErrorTrackingOptionsBuilder::default()
+            .in_app_exclude_paths(vec!["other_crate::".to_string()])
+            .build()
+            .unwrap(),
+    )
+    .build()
+    .unwrap();
+```
+
+### Captured properties
+
+| Property | Contents |
+|---|---|
+| `$exception_list` | One entry per error in the `source()` chain: type, message, and mechanism, with the captured stacktrace attached to the first entry. |
+| `$exception_level` | `"error"` unless set via `CaptureExceptionOptions::level`. |
+| `$exception_fingerprint` | Only present when set via `CaptureExceptionOptions::fingerprint`; overrides server-side issue grouping. |
+
 ## Feature Flags
 
 The SDK now supports PostHog feature flags, allowing you to control feature rollout and run A/B tests.

README.md

@@ -1,6 +1,6 @@
 # PostHog Rust SDK Examples
 
-This directory contains example applications demonstrating how to use the PostHog Rust SDK, particularly the feature flags functionality.
+This directory contains example applications demonstrating how to use the PostHog Rust SDK, including feature flags, local evaluation, configuration, and manual error tracking.
 
 ## Running the Examples
 
@@ -56,6 +56,20 @@ Shows:
 - Production settings with timeouts and geoip configuration
 - High-performance local evaluation setup
 
+### 4. Error Tracking Example
+
+Demonstrates manual error tracking capture:
+
+```bash
+export POSTHOG_API_KEY=phc_your_project_key
+cargo run --example error_tracking
+```
+
+Shows:
+- Capturing a Rust error as a PostHog Error Tracking event
+- Attaching a distinct ID
+- Adding custom exception properties
+
 ## Key Concepts
 
 ### Feature Flag Types

examples/README.md

@@ -0,0 +1,37 @@
+//! Manual Error Tracking capture.
+//!
+//! Run with:
+//!   POSTHOG_API_KEY=phc_... cargo run --example error_tracking
+
+#[cfg(all(feature = "async-client", feature = "error-tracking"))]
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    use posthog_rs::{client, CaptureExceptionOptions};
+
+    let api_key = std::env::var("POSTHOG_API_KEY")?;
+    let host = std::env::var("POSTHOG_HOST").unwrap_or_else(|_| posthog_rs::DEFAULT_HOST.into());
+    let client = client((api_key.as_str(), host.as_str())).await;
+
+    let error = std::io::Error::other("checkout failed");
+
+    // Associate the error with a person and attach context.
+    client
+        .capture_exception_with(
+            &error,
+            CaptureExceptionOptions::new()
+                .distinct_id("user-123")
+                .property("route", "/checkout")?,
+        )
+        .await?;
+
+    // Personless capture.
+    client.capture_exception(&error).await?;
+
+    Ok(())
+}
+
+#[cfg(not(all(feature = "async-client", feature = "error-tracking")))]
+fn main() {
+    println!("This example requires the async-client and error-tracking features (both default).");
+    println!("Run with: cargo run --example error_tracking");
+}

examples/error_tracking.rs

@@ -1,4 +1,6 @@
 use std::collections::{HashMap, HashSet};
+#[cfg(feature = "error-tracking")]
+use std::error::Error as StdError;
 use std::sync::{Arc, OnceLock};
 use std::time::Duration;
 
@@ -11,6 +13,8 @@ use tracing::{debug, instrument, trace, warn};
 use uuid::Uuid;
 
 use crate::endpoints::Endpoint;
+#[cfg(feature = "error-tracking")]
+use crate::error_tracking::{build_exception_event, CaptureExceptionOptions};
 #[cfg(not(feature = "capture-v1"))]
 use crate::event::InnerEvent;
 #[cfg(feature = "capture-v1")]
@@ -66,6 +70,9 @@ struct AsyncFlagEventHost {
     http_client: HttpClient,
     options: ClientOptions,
     capture_url: String,
+    // Read by the v0 ship path only; unused under capture-v1, where the
+    // flag-event path does not currently apply before_send hooks.
+    #[cfg_attr(feature = "capture-v1", allow(dead_code))]
     before_send: Vec<BeforeSendHook>,
     dedup_cache: FlagEventDedupCache,
     /// Tokio runtime handle captured at host construction (which always runs
@@ -304,6 +311,88 @@ impl Client {
         self.capture_v0(event).await
     }
 
+    /// 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
+    ///
+    /// ```no_run
+    /// # async fn example() -> Result<(), posthog_rs::Error> {
+    /// let client = posthog_rs::client("phc_project_api_key").await;
+    /// let error = std::io::Error::other("checkout failed");
+    ///
+    /// client.capture_exception(&error).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    #[cfg(feature = "error-tracking")]
+    pub async fn capture_exception<E>(&self, error: &E) -> Result<(), Error>
+    where
+        E: StdError + ?Sized,
+    {
+        self.capture_exception_with(error, CaptureExceptionOptions::default())
+            .await
+    }
+
+    /// 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
+    ///
+    /// ```no_run
+    /// # async fn example() -> Result<(), posthog_rs::Error> {
+    /// 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?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    #[cfg(feature = "error-tracking")]
+    pub async fn capture_exception_with<E>(
+        &self,
+        error: &E,
+        options: CaptureExceptionOptions,
+    ) -> Result<(), Error>
+    where
+        E: StdError + ?Sized,
+    {
+        if self.options.is_disabled() {
+            trace!("Client is disabled, skipping exception capture");
+            return Ok(());
+        }
+
+        self.capture(build_exception_event(
+            error,
+            options,
+            self.options.error_tracking(),
+        )?)
+        .await
+    }
+
     /// Capture a collection of events with a single request.
     ///
     /// Events are sent to the `/batch/` endpoint.