telemetry-kit

Quick Start Guide

Get telemetry-kit integrated into your Rust application in 5 minutes

5-Minute Integration for OSS Projects

Add privacy-first usage analytics to your Rust CLI tool, library, or application. Perfect for open source maintainers who want to understand real-world usage without compromising user privacy.

Prerequisites: Rust 1.70+ and Cargo installed

For OSS Maintainers: This guide shows you how to add transparent, privacy-respecting telemetry that your users will trust.

Add Dependency

Add telemetry-kit to your Cargo.toml:

[dependencies]
telemetry-kit = { version = "0.3", features = ["privacy", "sync"] }
tokio = { version = "1", features = ["full"] }

Feature flags:

  • privacy - GDPR-compliant privacy controls (recommended)
  • sync - Auto-sync to backend server (optional)
  • cli - CLI tools and interactive prompts (optional)

Initialize Telemetry

In your main.rs:

use telemetry_kit::prelude::*;
 
#[tokio::main]
async fn main() -> telemetry_kit::Result<()> {
    // Check if user opted out
    if TelemetryKit::is_do_not_track_enabled() {
        // User has DO_NOT_TRACK=1 set - respect their choice
        return Ok(());
    }
 
    // Initialize telemetry
    let telemetry = TelemetryKit::builder()
        .service_name("my-awesome-app")?
        .service_version(env!("CARGO_PKG_VERSION"))
        .build()?;
 
    // Your application code here
    run_app(&telemetry).await?;
 
    // Clean shutdown (flushes events)
    telemetry.shutdown().await?;
    Ok(())
}

Track Events

Track command execution, errors, and custom events:

async fn run_app(telemetry: &TelemetryKit) -> telemetry_kit::Result<()> {
    // Track a command
    telemetry.track_command("build", |event| {
        event
            .flag("--release")
            .flag("--target=wasm32")
            .success(true)
            .duration_ms(1234)
    }).await?;
 
    // Track an error
    if let Err(e) = risky_operation() {
        telemetry.track_error(&e, |event| {
            event.context("operation", "risky_operation")
        }).await?;
    }
 
    // Track a custom event
    telemetry.track_event("user_action", |event| {
        event
            .property("action", "file_open")
            .property("file_type", "rust")
            .success(true)
    }).await?;
 
    Ok(())
}
 
fn risky_operation() -> Result<(), Box<dyn std::error::Error>> {
    // Your code here
    Ok(())
}

Test It

Run your application:

cargo run

Your events are now stored locally in ~/.telemetry-kit/events.db. You can verify:

# Install CLI (optional)
cargo install telemetry-kit-cli
 
# View events
telemetry-kit events list --limit 5
 
# Export events
telemetry-kit events export --format json > events.json

Use strict privacy mode for GDPR compliance:

let telemetry = TelemetryKit::builder()
    .service_name("my-awesome-app")?
    .service_version(env!("CARGO_PKG_VERSION"))
    .strict_privacy()  // Enables strictest privacy settings
    .build()?;

Or prompt users for consent:

// Requires "cli" feature
let telemetry = TelemetryKit::builder()
    .service_name("my-awesome-app")?
    .service_version(env!("CARGO_PKG_VERSION"))
    .prompt_for_consent()?  // Shows interactive prompt
    .build()?;

Enable Sync (Optional)

Auto-sync events to your backend server:

let telemetry = TelemetryKit::builder()
    .service_name("my-awesome-app")?
    .service_version(env!("CARGO_PKG_VERSION"))
    .endpoint("https://telemetry.example.com")?
    .token("your-api-token")?
    .secret("your-hmac-secret")?
    .enable_auto_sync()  // Enable automatic syncing
    .build()?;

See Auto-Sync Guide for details.

To collect and analyze telemetry data from your users, you need a backend server to receive events. You have two options:

  1. Managed Service (Recommended) - Use our hosted service at telemetry-kit.dev. Get started instantly with a dashboard, analytics, and zero infrastructure to maintain.

  2. Self-Hosted - Deploy your own telemetry server using our production-ready server implementation. Full control over your data, but requires infrastructure management.

Without a server configured, events are stored locally on each user's machine in ~/.telemetry-kit/.

What You Get

After completing this quick start, you have:

  • ✅ Local event storage - All events stored in SQLite
  • ✅ Privacy-first - Respects DO_NOT_TRACK by default
  • ✅ Automatic sanitization - Paths and emails are sanitized
  • ✅ Offline-first - Works without network connectivity
  • ✅ Type-safe API - Compile-time safety with Rust

Next Steps

Privacy Controls

Learn about GDPR compliance, consent management, and data sanitization

Auto-Sync

Set up automatic syncing to your backend server

Best Practices

Patterns for CLI apps, libraries, and web services

API Reference

Complete API documentation

Common Issues

Events Not Appearing

Problem: Events aren't showing up in the database.

Solutions:

  1. Check if DO_NOT_TRACK=1 is set: echo $DO_NOT_TRACK
  2. Verify consent wasn't denied: telemetry-kit consent status
  3. Ensure you're calling .await? on tracking methods
  4. Call telemetry.shutdown().await? to flush events

Build Errors

Problem: Compilation fails with feature errors.

Solution: Ensure you have the required features enabled:

[dependencies]
telemetry-kit = { version = "0.3", features = ["privacy"] }

Permission Denied

Problem: Can't write to database.

Solution: Check permissions on ~/.telemetry-kit/:

chmod 755 ~/.telemetry-kit/
chmod 644 ~/.telemetry-kit/events.db

Complete Example

Here's a complete, copy-paste example:

use telemetry_kit::prelude::*;
 
#[tokio::main]
async fn main() -> telemetry_kit::Result<()> {
    // Respect user privacy
    if TelemetryKit::is_do_not_track_enabled() {
        println!("Telemetry disabled (DO_NOT_TRACK=1)");
        return Ok(());
    }
 
    // Initialize with privacy
    let telemetry = TelemetryKit::builder()
        .service_name("my-awesome-app")?
        .service_version(env!("CARGO_PKG_VERSION"))
        .strict_privacy()
        .build()?;
 
    // Track application startup
    telemetry.track_event("app_start", |event| {
        event.success(true)
    }).await?;
 
    // Run your application
    match run_app().await {
        Ok(_) => {
            telemetry.track_event("app_success", |event| {
                event.success(true)
            }).await?;
        }
        Err(e) => {
            telemetry.track_error(&e, |event| {
                event.context("phase", "runtime")
            }).await?;
            return Err(e.into());
        }
    }
 
    // Clean shutdown
    telemetry.shutdown().await?;
    Ok(())
}
 
async fn run_app() -> Result<(), Box<dyn std::error::Error>> {
    // Your application logic here
    println!("Running application...");
    Ok(())
}

Need Help?

Time to integrate: ~5 minutes Lines of code: ~15 Privacy: Built-in, GDPR-compliant

Previous

Getting Started

Next

Auto-Sync

On this page

5-Minute Integration for OSS ProjectsAdd DependencyInitialize TelemetryTrack EventsTest ItAdd Privacy (Optional but Recommended)Enable Sync (Optional)What You GetNext StepsCommon IssuesEvents Not AppearingBuild ErrorsPermission DeniedComplete ExampleNeed Help?