rust-umami
An ergonomic async Rust client for Umami's public analytics ingestion API.
This crate is deliberately small: it sends pageviews, custom events, identify/session properties, performance metrics, and batches. It does not log in, manage bearer tokens or API keys, or expose Umami's reporting/admin API.
Usage
[]
= "0.1"
= "1"
use ;
use json;
async
Client::new accepts an instance root, an /api URL, or the exact /api/send endpoint. Use Client::cloud(website_id) for Umami Cloud's collection gateway.
Server-side tracking
When a Rust server sends an event, Umami otherwise sees the server's IP and user-agent. Forward the original visitor context when it matters for attribution and session detection:
use ;
use ;
async
The client always sends a valid HTTP User-Agent (rust-umami/<version> by default), as required by Umami. The visitor user-agent above is a separate value inside the analytics payload.
Visitor sessions
A Client is stateless and can be shared across visitors. For several calls from one visitor, Session automatically carries Umami's cache value forward:
use ;
use json;
async
Create a separate session for each visitor. Cloning a session intentionally shares its cache state.
Performance and batches
use ;
use json;
async
Umami accepts at most 500 items per batch; the crate checks that limit locally. Partial batch failures are returned in BatchResponse::details rather than converted into an HTTP error.
Error behavior
Non-2xx responses retain Umami's status, error code, message, and JSON body. Error::is_retryable() recognizes transport failures, rate limits, and server errors, but the crate never retries automatically because that could duplicate an event.
The API targets the current Umami v3 /api/send and /api/batch contract. Basic pageview/custom-event sending remains compatible with Umami v2 instances that expose /api/send.
Publishing
Publishing is automated by .github/workflows/publish.yml using crates.io trusted publishing, so the repository does not store a registry token.
Trusted publishing can only be configured after the crate exists. Publish the first version manually with cargo publish --locked, then add a GitHub trusted publisher in the crate's crates.io settings with these values:
- Repository owner:
egoist - Repository:
rust-umami - Workflow:
publish.yml - Environment:
crates-io
For later versions, bump Cargo.toml, commit it, and push a matching v<version> tag:
The workflow verifies the tag, runs formatting, tests, Clippy, docs, and a package dry run, publishes with a short-lived credential, then creates the GitHub Release with generated notes.