emit

Developer-first diagnostics for Rust applications

emit is a stable, complete, and capable framework for adding structured diagnostics to your Rust applications with a simple, powerful data model and an expressive syntax inspired by Message Templates. emit's guiding design principle is low ceremony, low cognitive-load.

This readme covers just enough to give you an idea of what emit is. For a proper treatment, see:

• the guide.
• a set of task-oriented examples.
• the API docs.

Getting started

Add emit to your Cargo.toml:

[dependencies.emit]
version = "1.7.0"
# Optional
features = ["serde"]

# Optional
[dependencies.emit_term]
version = "1.7.0"

# Optional
[dependencies.serde]
version = "1"
features = ["derive"]

Initialize emit in your main.rs and start peppering diagnostics throughout your application:

fn main() {
    // Configure `emit` to write events to the console
    let rt = emit::setup()
        .emit_to(emit_term::stdout())
        .init();

    // Your app code goes here
    {
        // `emit` supports fully structured data
        // See the `#[emit::as_serde]` attribute in our `greet` function below
        #[derive(serde::Serialize)]
        struct User<'a> {
            id: u32,
            name: &'a str,
        }

        // Annotate functions with `#[emit::span]` to produce traces
        #[emit::span("Greet {user}", #[emit::as_serde] user)]
        fn greet(user: &User) {
            // Use `emit::info` to produce log events
            emit::info!("Hello, {user: user.name}!");
        }

        greet(&User { id: 1, name: "Rust" });
    }

    // Flush any remaining events before `main` returns
    rt.blocking_flush(std::time::Duration::from_secs(5));
}

emit has a capable syntax for writing events that's different from the standard format! trait. You can read more about it in the guide.

Tracing

emit can produce trace data that's compatible with OpenTelemetry and standard tracing tools, like Zipkin.

The above screenshot was generated by this example application.

See the guide for details.

Metrics

emit can produce metric data that's compatible with OpenTelemetry and standard metric tools, like Prometheus.

The above screenshot was generated by this example application.

See the guide for details.

Quick debugging

emit has a dbg! macro like the standard library's which you can use for quick-and-dirty debugging:

#[derive(Debug)]
pub struct User<'a> {
    id: u32,
    name: &'a str,
}

emit::dbg!(&User { id: 1, name: "Rust" });

See the guide for details.

Stability

emit has a complete and stable API that's suitable for production environments.