mirror of https://github.com/tokio-rs/tracing.git synced 2026-03-20 06:34:00 +00:00

Files

Eliza Weisman e3d29ac4dd chore: move examples to a central crate (#316 )

## Motivation

Currently, most crates in this repository have `examples` directories
that contain demonstrations of how to use that crate. In many cases,
these examples also use APIs from _other_ crates in this repository ---
for example, the `tracing-subscriber` `FmtSubscriber` is used by many
examples to format the output generated by instrumentation APIs, so that
users can see the generated output.

The disadvantage to this approach is that it requires crates in this
repository to have dev-dependencies on each other. This is problematic
for a few reasons:

* It makes it easy to inadvertently create cyclic dependencies between
  `tracing` crates.
* When building a crate that depends on a crate with dev-dependencies,
  those dev-dependencies are downloaded and compiled, despite not being
  linked into the dependent crate. This means that users depending on a
  tracing crate will pull in a larger dependency tree, since the
  dev-dependencies used by examples are also downloaded, although they 
  are not required by the dependent. This makes the tracing crate 
  appear to be a much larger dependency than it actually is, and can 
  make users' build times slower.
* Finally, it means that the examples are scattered throughout the 
  repository. In some cases, the examples demonstrate the functionality
  of multiple crates, but only live in one crate's `examples` dir. This
  can hurt the discoverability of the examples, especially for new 
  users.

## Solution

This branch moves all the examples out of individual crates and into a
new `examples` crate (which is otherwise empty and cannot be published
to crates.io). The `examples` crate is part of the root `tracing` 
workspace, so it's still possible to `cargo run --example WHATEVER`.
Similarly, `cargo test --all` will still build the examples.

All dev-dependencies which were only required by examples and not tests
have been removed, which has a drastic impact on the dependency 
footprint of some crates.

Finally, I've added a README to the `examples` crate, listing the 
available examples and what functionality they demonstrate.

Refs: #315, #308

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

2019-09-03 13:35:29 -07:00

2.9 KiB

Raw Permalink Blame History

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 Fibbonacci 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.

2.9 KiB Raw Permalink Blame History

Tracing Examples

2.9 KiB

Raw Permalink Blame History