Crate emit

Structured diagnostics for Rust applications.

emit is a framework for adding diagnostics to your Rust applications with a simple, powerful data model and an expressive syntax inspired by Message Templates.

These are the technical API docs for emit. Also see the guide for a complete introduction.

Getting started

[dependencies.emit]
version = "0.11.4"

[dependencies.emit_term]
version = "0.11.4"

fn main() {
    let rt = emit::setup()
        .emit_to(emit_term::stdout())
        .init();

    // Your app code goes here
    greet("Rust");

    rt.blocking_flush(std::time::Duration::from_secs(5));
}

#[emit::span("Greet {user}")]
fn greet(user: &str) {
    emit::info!("Hello, {user}!");
}

The setup() function configures emit with an Emitter to write Events to. The emit macro emits an event, capturing any ambient state referred to in its template. The span macro instruments a function, timing its execution and correlating any other events emitted within it together.

Stable vs nightly toolchains

emit works on stable versions of Rust, but can provide more accurate compiler messages on nightly toolchains.

Crate features

• std (default): Enable support for the standard library. Enable capturing properties as errors. Implies alloc.
• alloc: Enable APIs that require an allocator.
• implicit_rt (default): Enable configuring the default shared runtime and calling emit and span without needing to specify a runtime manually.
• implicit_internal_rt (default): Enable configuring the internal runtime for emit’s own diagnostics.
• sval: Enable capturing complex properties using sval.
• serde: Enable capturing complex properties using serde.

Troubleshooting

Emitters write their own diagnostics to an alternative emit runtime, which you can configure via Setup::init_internal to debug them:

fn main() {
    // Configure the internal runtime before your regular setup
    let internal_rt = emit::setup()
        .emit_to(emit_term::stdout())
        .init_internal();

    let rt = emit::setup()
        .emit_to(emit::emitter::from_fn(|evt| println!("{evt:#?}")))
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(5));

    // Flush the internal runtime after your regular setup
    internal_rt.blocking_flush(std::time::Duration::from_secs(5));
}

Re-exports

• pub use self::frame::Frame;
• pub use self::kind::Kind;
• pub use self::level::Level;
• pub use self::metric::Metric;
• pub use self::span::Span;
• pub use self::span::SpanCtxt;
• pub use self::span::SpanId;
• pub use self::span::TraceId;
• pub use self::timer::Timer;
• pub use setup::setup;
• pub use setup::Setup;

Modules

• and
  The And type.
• clock
  The Clock type.
• ctxt
  The Ctxt type.
• emitter
  The Emitter type.
• empty
  The Empty type.
• err
  Utilities for working with the err well-known property.
• event
  The Event type.
• extent
  The Extent type.
• filter
  The Filter type.
• frame
  The Frame type.
• kind
  The Kind type.
• level
  The Level type.
• metric
  The Metric type.
• or
  The Or type.
• path
  The Path type.
• platform
  Components provided by the underlying platform.
• props
  The Props type.
• rng
  The Rng type.
• runtime
  The Runtime type.
• setup
  The Setup type.
• span
  The Span type.
• str
  The Str type.
• template
  The Template type.
• timer
  The Timer type.
• timestamp
  The Timestamp type.
• value
  The Value type.
• well_known
  Extensions to the diagnostic model using well-known properties.

Macros

• dbg
  Emit a temporary debug event.
• debug
  Emit a debug event.
• debug_evt
  Construct a debug event.
• emit
  Emit an event.
• error
  Emit an error event.
• error_evt
  Construct an error event.
• evt
  Construct an event.
• format
  Format a template.
• info
  Emit an info event.
• info_evt
  Construct an info event.
• mdl
  Get a Path of the executing module for use in Event::mdl.
• new_debug_span
  Start a debug span.
• new_error_span
  Start an error span.
• new_info_span
  Start an info span.
• new_span
  Start a span.
• new_warn_span
  Start a warning span.
• path
  Construct a path.
• pkg
  Get a Path of the package name for use in Event::mdl.
• props
  Construct a set of properties.
• tpl
  Construct a template.
• warn
  Emit a warn event.
• warn_evt
  Construct a warn event.

Structs

• Empty
  A type that behaves like a default, empty, null value.
• Event
  A captured record of something significant that occurred during the operation of a system.
• Extent
  Either a single Timestamp for a point in time, or a pair of Timestamps for a range.
• Path
  A hierarchical identifier, such as a::b::c.
• Str
  A string value.
• Template
  A lazily evaluated text template with named holes for interpolating properties into.
• Timestamp
  A Unix timestamp with nanosecond precision.
• Value
  An anonymous captured value that can be serialized or formatted.

Traits

• Clock
  A service to get the current Timestamp.
• Ctxt
  Storage for ambient Props.
• Emitter
  An asynchronous destination for diagnostic data.
• Filter
  A filter over Events.
• Props
  A collection of Str and Value pairs.
• Rng
  A non-cryptographic source of randomness.

Functions

• blocking_flush
  Flush the runtime, ensuring all diagnostic events are fully processed.
• clock
  Get the shared clock.
• ctxt
  Get the shared context.
• emit
  Emit an event.
• emitter
  Get the shared emitter.
• filter
  Get the shared filter.
• rng
  Get the shared random generator.

Attribute Macros

• as_debug
  Capture a property using its Debug implementation.
• as_display
  Capture a property using its Display implementation.
• as_error
  Capture a property using its Error implementation.
• as_serde
  Capture a property using its serde::Serialize implementation.
• as_sval
  Capture a property using its sval::Value implementation.
• as_value
  Capture a property using its ToValue implementation.
• debug_span
  Wrap an operation in a debug span.
• error_span
  Wrap an operation in an error span.
• fmt
  Specify Rust format flags to use when rendering a property in a template.
• info_span
  Wrap an operation in an info span.
• key
  Specify the key for a property.
• optional
  Specify that a property value of None should not be captured, instead of being captured as null.
• span
  Wrap an operation in a span.
• warn_span
  Wrap an operation in a warn span.