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

[dependencies.emit_term]
version = "1.13.1"

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

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

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

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

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.

Macros

emit makes extensive use of procedural macros for reducing boilerplate when producing and emitting diagnostics. Its macros can be grouped based on the kind of diagnostic signal they relate to.

Logging macros

• emit: Emit an event.
• debug: Emit an event at the debug level.
• info: Emit an event at the info level.
• warn: Emit an event at the warning level.
• error: Emit an event at the error level.

Tracing macros

• span: Trace the execution of a function.
• debug_span: Trace the execution of a function at the debug level.
• info_span: Trace the execution of a function at the info level.
• warn_span: Trace the execution of a function at the warning level.
• error_span: Trace the execution of a function at the error level.
• new_span: Create a span that can be started and completed manually.
• new_debug_span: Create a span at the debug 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_warn_span: Create a span at the warning 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.

Metrics macros

• sample: Emit a metric sample.
• count_sample: Emit a metric sample with a monotonic count.
• sum_sample: Emit a metric sample with a non-monotonic sum.
• min_sample: Emit a metric sample with the minimum value.
• max_sample: Emit a metric sample with the maximum value.
• last_sample: Emit a metric sample with the latest value.
• metric: Construct a metric sample.
• count_metric: Construct a metric sample with a monotonic count.
• sum_metric: Construct a metric sample with a non-monotonic sum.
• min_metric: Construct a metric sample with the minimum value.
• max_metric: Construct a metric sample with the maximum value.
• last_metric: Construct a metric sample with the latest value.

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.
• web (default): Use JavaScript built-in APIs on WebAssembly targets for platform support. This feature is a no-op outside of wasm32-unknown-unknown.
• rand (default): Use rand as the default source of randomness on targets with a default provider. The specific version of rand is not guaranteed to remain the same. This feature is a no-op outside of the following targets:
  • linux
  • windows
  • macos
  • ios
  • android
  • wasi

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

count_metric

Construct a metric sample with count as its aggregation.

count_sample

Emit a metric sample with count as its aggregation.

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.

last_metric

Construct a metric sample with last as its aggregation.

last_sample

Emit a metric sample with last as its aggregation.

max_metric

Construct a metric sample with max as its aggregation.

max_sample

Emit a metric sample with max as its aggregation.

mdl

Get a Path of the executing module for use in Event::mdl.

metric

Construct a metric sample.

min_metric

Construct a metric sample with min as its aggregation.

min_sample

Emit a metric sample with min as its aggregation.

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.

sample

Emit a metric sample.

sum_metric

Construct a metric sample with sum as its aggregation.

sum_sample

Emit a metric sample with sum as its aggregation.

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.

sample

Sample a metric source.

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.