examples: add tokio-spawny-thing; some chores (#759)

Chores consisted of:

- Updating examples/README.md to include recent additions
- Settle on hyphens in example names

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

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;

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<dyn std::error::Error + Send + Sync + 'static>;
+
+#[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::<Vec<_>>();
+
+    // 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(())
+}