Crate emit

Expand description

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 = "1.9.0"

[dependencies.emit_term]
version = "1.9.0"

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 event as a quick-and-dirty debugging aid.
debug: Emit an event at the debug level.
debug_evt: Construct an event at the debug level that can be emitted manually.
emit: Emit an event.
error: Emit an event at the error level.
error_evt: Construct an event at the error level that can be emitted manually.
evt: Construct an event that can be emitted manually.
format: Format a template.
info: Emit an event at the info level.
info_evt: Construct an event at the info level that can be emitted manually.
mdl: Get a Path of the executing module for use in Event::mdl.
new_debug_span: Create a span at the debug level that can be started and completed manually.
new_error_span: Create a span at the error level that can be started and completed manually.
new_info_span: Create a span at the info level that can be started and completed manually.
new_span: Create a span that can be started and completed manually.
new_warn_span: Create a span at the warn level that can be started and completed manually.
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 an event at the warn level.
warn_evt: Construct an event at the warn level that can be emitted manually.

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: Trace the execution of a function at the debug level.
error_span: Trace the execution of a function at the error level.
fmt: Specify Rust format flags to use when rendering a property in a template.
info_span: Trace the execution of a function at the info level.
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: Trace the execution of a function.
warn_span: Trace the execution of a function at the warn level.

Crate emitCopy item path