Crate umbral_analytics 

umbral-analytics — product-analytics event capture for umbral.

Analytics instrumentation, the umbral way: declare the plugin, call capture / identify from any handler or service, and analytics failures never break a request. The PostHog backend is fire-and-forget; every send is spawned on a background task so the caller returns immediately.

Quick start

// Wire in main
App::builder()
    .plugin(
        AnalyticsPlugin::new("phc_your_api_key")
            .capture_requests(), // optional: auto pageview per request
    )
    .build()
    .await?;

// In a handler
use umbral_analytics::{capture, identify};

async fn signup(/* ... */) -> impl IntoResponse {
    identify("user_42", serde_json::json!({ "$set": { "email": "a@b.com" } })).await;
    capture("user_42", "signup", serde_json::json!({ "plan": "pro" })).await;
    StatusCode::CREATED
}

Settings keys

Read from UMBRAL_POSTHOG_API_KEY / UMBRAL_POSTHOG_HOST env vars or umbral.toml extra keys posthog_api_key / posthog_host. Builder overrides win over environment.

• posthog_api_key / UMBRAL_POSTHOG_API_KEY. Your project API key. When absent the plugin is a no-op: captures are dropped with a one-time warning. Never panics, never blocks.
• posthog_host / UMBRAL_POSTHOG_HOST. Ingest host (default https://us.i.posthog.com).

Surface

• AnalyticsPlugin. The plugin; registers the ambient client at boot.
• capture. Fire-and-forget event capture (free function, ambient).
• identify. Fire-and-forget $identify person update (free function, ambient).
• AnalyticsClient. The typed PostHog client. Public so callers can build one directly for testing or send with an explicit client.

Structs

AnalyticsClient

A configured PostHog client. Owns an API key + host; reuses the process-wide http_client connection pool.

AnalyticsPlugin

The analytics plugin. Carries no models, no persistent routes — just an AnalyticsClient it installs as the ambient handle at boot so capture / identify work anywhere in the process.

Constants

DEFAULT_POSTHOG_HOST

Default PostHog ingest host (US region).

Functions

ambient_client

Return the ambient client, or None if the plugin isn’t registered / no API key was configured.

capture

Fire-and-forget event capture. Sends event with properties attributed to distinct_id to PostHog. The HTTP send happens in a background task; this function returns immediately and analytics failures never affect the caller.

http_client

Returns a clone of the process-wide shared HTTP client.

identify

Fire-and-forget person identification. Sends a PostHog $identify event with person properties under $set. Use this to associate a distinct_id with user properties (name, email, plan, etc.).