diff --git a/examples/README.md b/examples/README.md index 311be7a1..82dfeb0f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -28,12 +28,20 @@ This directory contains a collection of examples that demonstrate the use of the + `tower-load`: Demonstrates how dynamically reloadable filters can be used to debug a server under load in production. - **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][tasks] created with + `tokio::spawn`. + `futures-proxy-server`: Demonstrates the use of `tracing-futures` by implementing a simple proxy server, based on [this example][tokio-proxy] 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. @@ -50,10 +58,10 @@ This directory contains a collection of examples that demonstrate the use of the - **tracing-opentelemetry**: + `opentelemetry`: Demonstrates how `tracing-opentelemetry` can be used to export and visualize `tracing` span data. - + `opentelemetry_remote_context`: Demonstrates how `tracing-opentelemetry` + + `opentelemetry-remote-context`: Demonstrates how `tracing-opentelemetry` can be used to extract and inject remote context when traces span multiple systems. - +[tasks]: (https://docs.rs/tokio/0.2.21/tokio/task/index.html) [tokio-proxy]: https://github.com/tokio-rs/tokio/blob/v0.1.x/tokio/examples/proxy.rs [echo]: https://github.com/hyperium/hyper/blob/0.12.x/examples/echo.rs diff --git a/examples/examples/async_fn.rs b/examples/examples/async-fn.rs similarity index 100% rename from examples/examples/async_fn.rs rename to examples/examples/async-fn.rs diff --git a/examples/examples/custom_error.rs b/examples/examples/custom-error.rs similarity index 100% rename from examples/examples/custom_error.rs rename to examples/examples/custom-error.rs diff --git a/examples/examples/inferno_flame.rs b/examples/examples/inferno-flame.rs similarity index 100% rename from examples/examples/inferno_flame.rs rename to examples/examples/inferno-flame.rs diff --git a/examples/examples/instrumented_error.rs b/examples/examples/instrumented-error.rs similarity index 100% rename from examples/examples/instrumented_error.rs rename to examples/examples/instrumented-error.rs diff --git a/examples/examples/opentelemetry_remote_context.rs b/examples/examples/opentelemetry-remote-context.rs similarity index 100% rename from examples/examples/opentelemetry_remote_context.rs rename to examples/examples/opentelemetry-remote-context.rs diff --git a/examples/examples/spawny_thing.rs b/examples/examples/spawny-thing.rs similarity index 95% rename from examples/examples/spawny_thing.rs rename to examples/examples/spawny-thing.rs index 3ce2cc38..2f166cec 100644 --- a/examples/examples/spawny_thing.rs +++ b/examples/examples/spawny-thing.rs @@ -5,7 +5,7 @@ /// You can run this example by running the following command in a terminal /// /// ``` -/// cargo +nightly run --example spawny_thing +/// cargo run --example spawny_thing /// ``` use futures::future::join_all; use std::error::Error; diff --git a/examples/examples/tokio-spawny-thing.rs b/examples/examples/tokio-spawny-thing.rs new file mode 100644 index 00000000..845b82d3 --- /dev/null +++ b/examples/examples/tokio-spawny-thing.rs @@ -0,0 +1,45 @@ +#![deny(rust_2018_idioms)] +/// This is a example showing how information is scoped with tokio's +/// `task::spawn`. +/// +/// You can run this example by running the following command in a terminal +/// +/// ``` +/// cargo run --example tokio-spawny-thing +/// ``` +use futures::future::try_join_all; +use tracing::{debug, info, instrument, span, Level}; +use tracing_futures::Instrument; + +type Error = Box; + +#[instrument] +async fn parent_task(subtasks: usize) -> Result<(), Error> { + info!("spawning subtasks..."); + let subtasks = (1..=subtasks) + .map(|number| { + let span = span!(Level::INFO, "subtask", %number); + debug!(message = "creating subtask;", number); + tokio::spawn(subtask(number).instrument(span)) + }) + .collect::>(); + + // the returnable error would be if one of the subtasks panicked. + let sum: usize = try_join_all(subtasks).await?.iter().sum(); + info!(%sum, "all subtasks completed; calculated sum"); + Ok(()) +} + +async fn subtask(number: usize) -> usize { + info!(%number, "polling subtask"); + number +} + +#[tokio::main] +async fn main() -> Result<(), Error> { + tracing_subscriber::fmt() + .with_max_level(tracing::Level::DEBUG) + .try_init()?; + parent_task(10).await?; + Ok(()) +}