Crate emit

Source
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 = "0.11.8"

[dependencies.emit_term]
version = "0.11.8"
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.