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 Event
s 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. Impliesalloc
.alloc
: Enable APIs that require an allocator.implicit_rt
(default): Enable configuring the default shared runtime and callingemit
andspan
without needing to specify a runtime manually.implicit_internal_rt
(default): Enable configuring the internal runtime foremit
’s own diagnostics.sval
: Enable capturing complex properties usingsval
.serde
: Enable capturing complex properties usingserde
.
§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 inEvent::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 inEvent::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 ofTimestamp
s 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
Event
s. - Props
- A collection of
Str
andValue
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 asnull
. - span
- Wrap an operation in a span.
- warn_
span - Wrap an operation in a warn span.