Remove Tracer::with_span (open-telemetry#746)

* Remove `Tracer::with_span`

This method is not part of the trace spec and the same functionality can
be achieved with `mark_span_as_active` or
`Context::current_with_span(span).attach()`.

* Fix dynatrace clippy lints

* fix otlp external example lint

* Fix doc links

Author: jtescher

examples/external-otlp-tonic-tokio/src/main.rs

@@ -47,7 +47,7 @@ fn init_tracer() -> Result<sdktrace::Tracer, TraceError> {
         .map(|(name, value)| {
             let header_name = name
                 .strip_prefix(HEADER_PREFIX)
-                .map(|h| h.replace("_", "-"))
+                .map(|h| h.replace('_', "-"))
                 .map(|h| h.to_ascii_lowercase())
                 .unwrap();
             (header_name, value)

opentelemetry-api/src/trace/mod.rs

@@ -95,8 +95,8 @@
 //! drop(active)
 //! ```
 //!
-//! Additionally [`Tracer::with_span`] and [`Tracer::in_span`] can be used as shorthand to
-//! simplify managing the parent context.
+//! Additionally [`Tracer::in_span`] can be used as shorthand to simplify
+//! managing the parent context.
 //!
 //! ```
 //! use opentelemetry_api::{global, trace::Tracer};
@@ -109,12 +109,6 @@
 //! tracer.in_span("parent_span", |cx| {
 //!     // spans created here will be children of `parent_span`
 //! });
-//!
-//! // Use `with_span` to mark a span as active for a given period.
-//! let span = tracer.start("parent_span");
-//! tracer.with_span(span, |cx| {
-//!     // spans created here will be children of `parent_span`
-//! });
 //! ```
 //!
 //! #### Async active spans

opentelemetry-api/src/trace/tracer.rs

@@ -44,20 +44,6 @@ use std::time::SystemTime;
 ///     // child has ended, parent now the active span again
 /// });
 /// // parent has ended, no active spans
-///
-/// // -- OR --
-///
-/// // create complex spans with span builder and `with_span`
-/// let parent_span = tracer.span_builder("foo").with_kind(SpanKind::Server).start(&tracer);
-/// tracer.with_span(parent_span, |_foo_cx| {
-///     // parent span is active
-///     let child_span = tracer.span_builder("bar").with_kind(SpanKind::Client).start(&tracer);
-///     tracer.with_span(child_span, |_bar_cx| {
-///         // child span is now the active span and associated with the parent span
-///     });
-///     // child has ended, parent now the active span again
-/// });
-/// // parent has ended, no active spans
 /// ```
 ///
 /// Spans can also be marked as active, and the resulting guard allows for
@@ -228,46 +214,6 @@ pub trait Tracer {
         let _guard = cx.clone().attach();
         f(cx)
     }
-
-    /// Execute the given closure with reference to a context in which the span is
-    /// active.
-    ///
-    /// This sets the given span as active for the duration of the given function.
-    /// It then executes the body. It closes the span before returning the execution
-    /// result.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use opentelemetry_api::{global, trace::{Span, SpanKind, Tracer, get_active_span}, KeyValue};
-    ///
-    /// fn my_function() {
-    ///     let tracer = global::tracer("my-component");
-    ///     // start a span with custom attributes via span builder
-    ///     let span = tracer.span_builder("span-name").with_kind(SpanKind::Server).start(&tracer);
-    ///     // Mark the span as active for the duration of the closure
-    ///     global::tracer("my-component").with_span(span, |_cx| {
-    ///         // anything happening in functions we call can still access the active span...
-    ///         my_other_function();
-    ///     })
-    /// }
-    ///
-    /// fn my_other_function() {
-    ///     // call methods on the current span from
-    ///     get_active_span(|span| {
-    ///         span.add_event("An event!".to_string(), vec![KeyValue::new("happened", true)]);
-    ///     })
-    /// }
-    /// ```
-    fn with_span<T, F>(&self, span: Self::Span, f: F) -> T
-    where
-        F: FnOnce(Context) -> T,
-        Self::Span: Send + Sync + 'static,
-    {
-        let cx = Context::current_with_span(span);
-        let _guard = cx.clone().attach();
-        f(cx)
-    }
 }
 
 /// `SpanBuilder` allows span attributes to be configured before the span

opentelemetry-dynatrace/tests/http_test.rs

@@ -116,7 +116,7 @@ mod test {
         );
         assert_eq!(
             req.headers().get(AUTHORIZATION),
-            Some(&HeaderValue::from_str(&"Api-Token 1234567890".to_string()).unwrap()),
+            Some(&HeaderValue::from_str("Api-Token 1234567890").unwrap()),
         );
 
         let bytes = body::to_bytes(req.into_body())