cleanup readme

README.md

@@ -1,6 +1,8 @@
 [![Documentation (master)](https://img.shields.io/badge/docs-master-brightgreen)](https://inanna-malick.github.io/honeycomb-tracing/honeycomb_tracing) [![Build Status](https://circleci.com/gh/inanna-malick/honeycomb-tracing/tree/master.svg?style=shield)](https://circleci.com/gh/inanna-malick/honeycomb-tracing/tree/master) [![License](https://img.shields.io/badge/license-MIT-green.svg)](../LICENSE-MIT)
 
-Provides `TelemetryLayer`, a composable `tracing` layer that publishes spans and events to honeycomb.io, with support for arbitrary backends. Also provides utilities for distributed tracing. As a tracing layer, it can be composed with other layers. However, the underlying subscriber must be `tracing_subscriber::registry::Registry`. The following example shows how to create and register a subscriber created by composing `TelemetryLayer` (as provided by this crate) with other layers and a subscriber. 
+Provides `TelemetryLayer`, a composable `tracing` layer that publishes spans and events to honeycomb.io, with support for arbitrary backends. Also provides utilities for implementing distributed tracing for arbitrary backends, with a concrete implementation using honeycomb.io as a backend in `tracing-honeycomb`. Each implementation can provide its own `TraceId` and `SpanId` types, with the goal of allowing the underlying machinery provided by `tracing-distributed`.
+
+As a tracing layer, `TelemetryLayer` can be composed with other layers to provide stdout logging, filtering, etc. However, the underlying subscriber must be `tracing_subscriber::registry::Registry`. The following example shows how to create and register a subscriber created by composing `TelemetryLayer` (as provided by this crate) with other layers and a registry subscriber. 
 
 ```rust
 let honeycomb_config = libhoney::Config {
@@ -12,21 +14,18 @@ let honeycomb_config = libhoney::Config {
     transmission_options: libhoney::transmission::Options::default(),
 };
 
-let telemetry_layer = TelemetryLayer::new(
-    "my-service-name".to_string(),
-    HoneycombTelemetry::new(honeycomb_config),
-);
+let telemetry_layer = mk_honeycomb_tracing_layer("my-service-name", honeycomb_config);
 
 let subscriber = telemetry_layer // publish to tracing
     .and_then(tracing_subscriber::fmt::Layer::builder().finish()) // log events to stdout
-    .and_then(LevelFilter::INFO) // omit low-level debug tracing (eg tokio executor)
+    .and_then(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
     .with_subscriber(registry::Registry::default()); // provide underlying span data store
 
 tracing::subscriber::set_global_default(subscriber).expect("setting global default failed");
 ```
 
-A `TraceCtx` uniquely identifies the current trace via a u128 `TraceId` and also contains an optional parent `SpanId`. `TelemetryLayer`, provides out-of-band functionality for establishing and fetching trace contexts:
-- `TraceCtx::current_trace_ctx() -> Result<TraceCtx, TraceCtxError)` makes the current span's 'TraceCtx', if any, available outside of `tracing` contexts. For example, an application that makes RPC requests (eg, a GRPC client) might use this to include a 'TraceCtx' in the metadata of an RPC request.
+A `TraceCtx` uniquely identifies the current trace via some `TraceId` and an optional parent `SpanId`. `TelemetryLayer` provides out-of-band functionality for recording and retreiving trace contexts:
+- `TraceCtx::current_trace_ctx() -> Result<TraceCtx, TraceCtxError)` makes the current span's 'TraceCtx', if any, available outside of `tracing` contexts. For example, an application that makes RPC requests (eg, a GRPC client) might use this to include a 'TraceCtx' in the metadata of an RPC request, such that tracing info is propagated across RPC request boundaries.
 - `TraceCtx::record_on_current_span(self) -> Result<(), TraceCtxError)` associates a 'TraceCtx' with the current span. For example, an application that handles RPC requests (eg, a GRPC server) might use it to mark some span as the root of a trace or to register a span as being part of a distributed trace by parsing a 'TraceCtx' from RPC metadata. 
 
 
@@ -78,10 +77,7 @@ Since `TraceCtx::current_trace_ctx` and `TraceCtx::record_on_current_span` can b
 This library provides a `BlackholeTelemetry` `Telemetry` instance for use in test code, so you can exercise code that uses trace ctxs in tests without publishing telemetry to any backend. Use as:
 
 ```rust
-let telemetry_layer = TelemetryLayer::new(
-    "test-service".to_string(),
-    BlackholeTelemetry,
-);
+let telemetry_layer = mk_honeycomb_blackhole_tracing_layer(); 
 
 let subscriber = telemetry_layer
     .and_then(tracing_subscriber::fmt::Layer::builder().finish()) // log events to stdout

tracing-distributed/src/telemetry_layer.rs

@@ -299,25 +299,6 @@ impl SpanInitAt {
     }
 }
 
-#[derive(Debug)]
-struct PathToRoot<'a, S> {
-    registry: &'a S,
-    next: Option<Id>,
-}
-
-impl<'a, S> Iterator for PathToRoot<'a, S>
-where
-    S: registry::LookupSpan<'a>,
-{
-    type Item = registry::SpanRef<'a, S>;
-    fn next(&mut self) -> Option<Self::Item> {
-        let id = self.next.take()?;
-        let span = self.registry.span(&id)?;
-        self.next = span.parent().map(|parent| parent.id());
-        Some(span)
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

tracing-honeycomb/examples/async_tracing.rs

@@ -90,12 +90,11 @@ fn register_global_subscriber() {
         transmission_options: libhoney::transmission::Options::default(),
     };
 
-    // TODO: helper fn for this exported by honeycomb tracing lib
     let telemetry_layer = mk_honeycomb_tracing_layer("async-tracing_example", honeycomb_config);
 
     let subscriber = telemetry_layer // publish to tracing
         .and_then(tracing_subscriber::fmt::Layer::builder().finish()) // log to stdout
-        .and_then(LevelFilter::INFO) // omit low-level debug tracing (eg tokio executor)
+        .and_then(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
         .with_subscriber(registry::Registry::default()); // provide underlying span data store
 
     tracing::subscriber::set_global_default(subscriber).expect("setting global default failed");