mirror of https://github.com/tokio-rs/tracing.git synced 2025-09-30 22:40:34 +00:00

History

core: record Valuable values as valuable::Value (#1881 )

This changes the `valuable` integration so that `record_value` takes
instances of `valuable::Value<'_>`, rather than `&dyn
valuable::Valuable` trait objects. The primary advantage of this is that
a `Value` can be produced by calling `Valuable::as_value`, so it allows
users to write code like this:

```rust
#[derive(Valuable, Debug)]
struct Foo {
    // ...
}

tracing::trace!(foo = foo.as_value());
```

rather than this:

```rust
#[derive(Valuable, Debug)]
struct Foo {
    // ...
}

tracing::trace!(foo = tracing::field::valuable(&foo));
```

which feels a bit more ergonomic. It also simplifies the code in
`tracing-core`, since we no longer need our own `ValuableValue` wrapper
type to turn things into trait objects.

It might also reduce boilerplate a bit on the visitor side, as
`as_value()` doesn't have to be called on the trait object, although
that's probably not as big a deal.

I didn't remove the `field::valuable` function, as I thought it was nice
to have for consistency with the existing `field::debug` and
`field::display` functions.

## Performance Considerations

@carllerche pointed out that a `Value<'_>` might be slightly more bytes
to pass on the stack than a trait object (always two words). I believe
this is only the case when the `Value` is a `Listable`, `Enumerable`,
`Structable`, `Mappable`, or `Tupleable`, where the `Value` would be an
enum descriminant _and_ a wide pointer to a trait object. However, in
the cases where the value is a primitive, `Value` will be two words if
the primitive is word-sized (e.g. `u64` on 64-bit platforms), for the
enum descriminant + the value, or one word if the primitive is smaller
than word size (`bool`, `char`, etc). Also, for primitive `Value`s,
there's no pointer dereference, which the trait object always requires.

I'm not sure how the enum dispatch compares to vtable dispatch when
calling `visit` on the value. However, if the `tracing` visitor is going
to call `as_value()` on the recorded value, this approach is better,
because calling `as_value()` in the macro _prior_ to recording the
span/event will use the statically dispatched `as_value()` impl on a
known type, rather than the the dynamically dispatched `as_value()` impl
on the trait object. Since `as_value` impls are generally quite trivial,
I'd guess they usually (always?) will get inlined, which is never
possible with the dynamically dispatched call after passing a trait
object into `tracing`.

In practice I'm not sure if there's a huge perf diff either way, but it
was interesting to think through the implications.

2022-02-02 22:07:44 +00:00

examples

core: record Valuable values as valuable::Value (#1881 )

2022-02-02 22:07:44 +00:00

Cargo.toml

core: add initial support for valuable field values (#1608 )

2022-01-21 21:29:38 +00:00

README.md

subscriber: add Format::with_file and with_line_number (#1773 )

2022-01-14 12:12:09 -08:00

README.md

Tracing Examples

This directory contains a collection of examples that demonstrate the use of the tracing ecosystem:

tracing:
- counters: Implements a very simple metrics system to demonstrate how subscribers can consume field values as typed data.
- sloggish: A demo Subscriber implementation that mimics the output of slog-term's Compact formatter.
tracing-attributes:
- attrs-basic: A simple example of the #[instrument] attribute.
- attrs-literal-field-names: Demonstrates using literal field names rather than rust tokens..
- attrs-args: An example implementing a simple recursive calculation of Fibonacci numbers, to demonstrate how the #[instrument] attribute can record function arguments.
tracing-subscriber:
- fmt: Demonstrates the use of the fmt module in tracing-subscriber, which provides a subscriber implementation that logs traces to the console.
- fmt-stderr: Demonstrates overriding the output stream used by the fmt subscriber.
- fmt-custom-field: Demonstrates overriding how the fmt subscriber formats fields on spans and events.
- fmt-custom-event: Demonstrates overriding how the fmt subscriber formats events.
- fmt-multiple-writers.rs: demonstrates how fmt::Layer can write to multiple destinations (in this instance, stdout and a file) simultaneously.
- fmt-source-locations.rs: demonstrates displaying source code locations with fmt::Layer.
- subscriber-filter: Demonstrates the tracing-subscriber::filter module, which provides a layer which adds configurable filtering to a subscriber implementation.
- tower-load: Demonstrates how dynamically reloadable filters can be used to debug a server under load in production.
- journald: Demonstrates how to use fmt and journald layers to output to both the terminal and the system journal.
- toggle-layers : Demonstrates how Layers can be wrapped with an Option allowing them to be dynamically toggled.
tracing-futures:
- spawny-thing: Demonstrates the use of the #[instrument] attribute macro asynchronous functions.
- tokio-spawny-thing.rs: Similar to spawny-thingy, but with the additional demonstration instrumenting concurrent tasks created with tokio::spawn.
- futures-proxy-server: Demonstrates the use of tracing-futures by implementing a simple proxy server, based on this example from tokio.
- async_fn: Demonstrates how asynchronous functions can be instrumented.
- echo: Demonstrates a tracing-instrumented variant of Tokio's echo example.
tracing-flame:
- infero-flame: Demonstrates the use of tracing-flame to generate a flamegraph from spans.
tracing-tower:
- tower-client: Demonstrates the use of tracing-tower to instrument a simple tower HTTP/1.1 client.
- tower-server: Demonstrates the use of tracing-tower to instrument a simple tower HTTP/1.1 server.
tracing-serde:
- serde-yak-shave: Demonstrates the use of tracing-serde by implementing a subscriber that emits trace output as JSON.
tracing-log:
- hyper-echo: Demonstrates how tracing-log can be used to record unstructured logs from dependencies as tracing events, by instrumenting this example from hyper, and using tracing-log to record logs emitted by hyper.
tracing-opentelemetry:
- opentelemetry: Demonstrates how tracing-opentelemetry can be used to export and visualize tracing span data.
- opentelemetry-remote-context: Demonstrates how tracing-opentelemetry can be used to extract and inject remote context when traces span multiple systems.