README.md
1# Tracing Examples
2
3This directory contains a collection of examples that demonstrate the use of the
4`tracing` ecosystem:
5
6- **tracing**:
7 + `counters`: Implements a very simple metrics system to demonstrate how
8 subscribers can consume field values as typed data.
9 + `sloggish`: A demo `Subscriber` implementation that mimics the output of
10 `slog-term`'s `Compact` formatter.
11- **tracing-attributes**:
12 + `attrs-basic`: A simple example of the `#[instrument]` attribute.
13 + `attrs-literal-field-names`: Demonstrates using literal field names rather
14 than rust tokens..
15 + `attrs-args`: An example implementing a simple recursive calculation of
16 Fibonacci numbers, to demonstrate how the `#[instrument]` attribute can
17 record function arguments.
18- **tracing-subscriber**:
19 + `fmt`: Demonstrates the use of the [`fmt`] module in `tracing-subscriber`,
20 which provides a subscriber implementation that logs traces to the console.
21 This example uses the default formatter ([`format::Full`]).
22 + `fmt-stderr`: Demonstrates overriding the output stream used by the `fmt`
23 subscriber.
24 + `fmt-pretty`: Demonstrates the output of the [`format::Pretty`] formatter in
25 [`tracing-subscriber::fmt`][`fmt`].
26 + `fmt-compact`: Demonstrates the output of the [`format::Compact`] formatter in
27 [`tracing-subscriber::fmt`][`fmt`].
28 + `fmt-json`: Demonstrates the output of the [`format::Json`] formatter in
29 [`tracing-subscriber::fmt`][`fmt`].
30 + `fmt-custom-field`: Demonstrates overriding how the [`fmt`] subscriber formats
31 fields on spans and events.
32 + `fmt-custom-event`: Demonstrates overriding how the [`fmt`] subscriber formats
33 events.
34 + `fmt-multiple-writers`: demonstrates how [`fmt::Layer`] can write
35 to multiple destinations (in this instance, stdout and a file) simultaneously.
36 + `fmt-source-locations`: demonstrates displaying source code locations
37 with [`fmt::Layer`].
38 + `subscriber-filter`: Demonstrates the `tracing-subscriber::filter` module,
39 which provides a layer which adds configurable filtering to a subscriber
40 implementation.
41 + `tower-load`: Demonstrates how dynamically reloadable filters can be used to
42 debug a server under load in production.
43 + `journald`: Demonstrates how to use [`fmt`] and `journald` layers to output to
44 both the terminal and the system journal.
45 + `toggle-layers` : Demonstrates how Layers can be wrapped with an `Option` allowing
46 them to be dynamically toggled.
47- **tracing-futures**:
48 + `spawny-thing`: Demonstrates the use of the `#[instrument]` attribute macro
49 asynchronous functions.
50 + `tokio-spawny-thing.rs`: Similar to `spawny-thingy`, but with the additional
51 demonstration instrumenting [concurrent tasks][tasks] created with
52 `tokio::spawn`.
53 + `futures-proxy-server`: Demonstrates the use of `tracing-futures` by
54 implementing a simple proxy server, based on [this example][tokio-proxy]
55 from `tokio`.
56 + `async_fn`: Demonstrates how asynchronous functions can be
57 instrumented.
58 + `echo`: Demonstrates a `tracing`-instrumented variant of Tokio's `echo` example.
59- **tracing-flame**:
60 + `infero-flame`: Demonstrates the use of `tracing-flame` to generate a flamegraph
61 from spans.
62- **tracing-tower**:
63 + `tower-client`: Demonstrates the use of `tracing-tower` to instrument a
64 simple `tower` HTTP/1.1 client.
65 + `tower-server`: Demonstrates the use of `tracing-tower` to instrument a
66 simple `tower` HTTP/1.1 server.
67- **tracing-serde**:
68 + `serde-yak-shave`: Demonstrates the use of `tracing-serde` by implementing a
69 subscriber that emits trace output as JSON.
70- **tracing-log**:
71 + `hyper-echo`: Demonstrates how `tracing-log` can be used to record
72 unstructured logs from dependencies as `tracing` events, by instrumenting
73 [this example][echo] from `hyper`, and using `tracing-log` to record logs
74 emitted by `hyper`.
75- **tracing-opentelemetry**:
76 + `opentelemetry`: Demonstrates how `tracing-opentelemetry` can be used to
77 export and visualize `tracing` span data.
78 + `opentelemetry-remote-context`: Demonstrates how `tracing-opentelemetry`
79 can be used to extract and inject remote context when traces span multiple
80 systems.
81
82[tasks]: (https://docs.rs/tokio/0.2.21/tokio/task/index.html)
83[tokio-proxy]: https://github.com/tokio-rs/tokio/blob/v0.1.x/tokio/examples/proxy.rs
84[echo]: https://github.com/hyperium/hyper/blob/0.12.x/examples/echo.rs
85[`fmt`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/index.html
86[`format::Full`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Full.html
87[`format::Pretty`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Pretty.html
88[`format::Compact`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Compact.html
89[`format::Json`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Json.html
90[`fmt::Layer`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Layer.html