rust-umami 0.1.1

An ergonomic Rust client for Umami Analytics event ingestion
Documentation

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

[dependencies]
rust-umami = "0.1"
serde_json = "1"
use rust_umami::{Client, Result};
use serde_json::json;

async fn track() -> Result<()> {
    let umami = Client::new(
        "https://analytics.example.com",
        "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    )?;

    umami.pageview("/docs").title("Documentation").send().await?;

    umami
        .event("signup")
        .url("/pricing")
        .data(json!({ "plan": "pro", "revenue": 49.0, "currency": "USD" }))
        .send()
        .await?;

    Ok(())
}

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 rust_umami::{Client, Context, Result};
use std::net::{IpAddr, Ipv4Addr};

async fn track_request() -> Result<()> {
    let context = Context::new()
        .hostname("example.com")
        .language("en-US")
        .ip(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 10)))
        .user_agent("Mozilla/5.0 ...");

    let umami = Client::builder(
        "https://analytics.example.com",
        "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    )
    .default_context(context)
    .build()?;

    umami.event("payment-received").url("/checkout").send().await?;
    Ok(())
}

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 rust_umami::{Client, Result};
use serde_json::json;

async fn track_visitor(umami: &Client) -> Result<()> {
    let visitor = umami.session().distinct_id("user-123");

    visitor.pageview("/").send().await?;
    visitor
        .identify("user-123")
        .data(json!({ "plan": "pro" }))
        .send()
        .await?;
    visitor
        .event("download")
        .data(json!({ "format": "pdf" }))
        .send()
        .await?;

    Ok(())
}

Create a separate session for each visitor. Cloning a session intentionally shares its cache state.

Performance and batches

use rust_umami::{Client, Result};
use serde_json::json;

async fn send_metrics(umami: &Client) -> Result<()> {
    umami
        .performance("/pricing")
        .lcp(1_250.0)
        .inp(80.0)
        .cls(0.03)
        .fcp(620.0)
        .ttfb(140.0)
        .send()
        .await?;

    let result = umami
        .batch()
        .push(umami.pageview("/one"))
        .push(umami.event("download").data(json!({ "format": "pdf" })))
        .send()
        .await?;

    assert!(result.is_success());
    Ok(())
}

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:

git tag v0.2.0
git push origin v0.2.0

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.