mirror of https://github.com/tokio-rs/tracing.git synced 2025-10-02 15:24:47 +00:00

History

error: add error instrumentation type and traits (#574 )

## Motivation

The tracing_error crate should provide some basic functionality for
instrumenting Errors with `SpanTraces` generically. The goal is to make
it easy for users to instrument their errors without needing to add a
`SpanTrace` to every error they construct.

## Solution

Critically this trait provides 3 traits for instrumenting errors,
`InstrumentResult`, `InstrumentError`, and `ExtractSpanTrace`. The first
two traits expose a `in_current_span()` method that can work on a
`Result<T, E: InstrumentError>` and an `Error`, respectively, that wraps
the error type in a `TracedError` that stores the inner error and a
SpanTrace. The third trait, `ExtractSpanTrace`, is used to retrieve the
span_trace member of a `TracedError` from a `&dyn Error` trait object.

This is done by downcasting the error to a `TracedError` and returning
the inner `span_trace` if it is successful. By default this only works
because the inner error is stored in a Box as a trait object, which
prevents it from being part of the type signature for `TracedError`.

However, this crate also exposes a second version of `TracedError` that
does not box the inner error, thus avoiding the need for heap
allocation, which it accomplishes by type erasing the `TracedError<E>`
into a `TracedError<()>` while iterating through the error `source()`
chain.

2020-02-24 16:00:10 -08:00

examples

error: add error instrumentation type and traits (#574 )

2020-02-24 16:00:10 -08:00

Cargo.toml

subscriber: prepare to release 0.2.1 (#586 )

2020-02-14 10:56:03 -08:00

README.md

Fix small typos (#405 )

2019-10-24 15:12:52 -07: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-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.
- 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.
tracing-futures:
- futures-proxy-server: Demonstrates the use of tracing-futures by implementing a simple proxy server, based on this example from tokio.
- futures-spawn: A simple demonstration of the relationship between the spans representing spawned futures.
tracing-tower:
- tower-h2-client: Demonstrates the use of tracing-tower to instrument a simple tower-h2 HTTP/2 client (based on this example from tower-h2).
- tower-h2-server: Demonstrates the use of tracing-tower to instrument a simple tower-h2 HTTP/2 server (based on this example from tower-h2).
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.

The nightly-examples directory contains examples of how tracing can be used with async/await. These are kept separate as async/await is currently only available on nightly Rust toolchains.