api: clean up trace docs (open-telemetry#765)

Author: jtescher

opentelemetry-api/src/baggage.rs

@@ -1,9 +1,13 @@
-//! Primitives for sending name-value data across system boundaries.
+//! Primitives for sending name/value data across system boundaries.
+//!
+//! Baggage is used to annotate telemetry, adding context and information to
+//! metrics, traces, and logs. It is a set of name/value pairs describing
+//! user-defined properties. Each name in Baggage is associated with exactly one
+//! value.
 //!
 //! Main types in this module are:
 //!
-//! * [`Baggage`]: Baggage is used to annotate telemetry, adding context and
-//!   information to metrics, traces, and logs.
+//! * [`Baggage`]: A set of name/value pairs describing user-defined properties.
 //! * [`BaggageExt`]: Extensions for managing `Baggage` in a [`Context`].
 //!
 //! Baggage can be sent between systems using a baggage propagator in
@@ -22,7 +26,7 @@ const MAX_KEY_VALUE_PAIRS: usize = 180;
 const MAX_BYTES_FOR_ONE_PAIR: usize = 4096;
 const MAX_LEN_OF_ALL_PAIRS: usize = 8192;
 
-/// A set of name-value pairs describing user-defined properties.
+/// A set of name/value pairs describing user-defined properties.
 ///
 /// ### Baggage Names
 ///
@@ -35,14 +39,14 @@ const MAX_LEN_OF_ALL_PAIRS: usize = 8192;
 /// ### Baggage Value Metadata
 ///
 /// Additional metadata can be added to values in the form of a property set,
-/// represented as semi-colon `;` delimited list of names and/or name-value pairs,
+/// represented as semi-colon `;` delimited list of names and/or name/value pairs,
 /// e.g. `;k1=v1;k2;k3=v3`.
 ///
 /// ### Limits
 ///
-/// * Maximum number of name-value pairs: `180`.
-/// * Maximum number of bytes per a single name-value pair: `4096`.
-/// * Maximum total length of all name-value pairs: `8192`.
+/// * Maximum number of name/value pairs: `180`.
+/// * Maximum number of bytes per a single name/value pair: `4096`.
+/// * Maximum total length of all name/value pairs: `8192`.
 ///
 /// [RFC2616, Section 2.2]: https://tools.ietf.org/html/rfc2616#section-2.2
 #[derive(Debug, Default)]
@@ -92,7 +96,7 @@ impl Baggage {
         self.inner.get(&key.into())
     }
 
-    /// Inserts a name-value pair into the baggage.
+    /// Inserts a name/value pair into the baggage.
     ///
     /// If the name was not present, [`None`] is returned. If the name was present,
     /// the value is updated, and the old value is returned.
@@ -116,7 +120,7 @@ impl Baggage {
             .map(|pair| pair.0)
     }
 
-    /// Inserts a name-value pair into the baggage.
+    /// Inserts a name/value pair into the baggage.
     ///
     /// Same with `insert`, if the name was not present, [`None`] will be returned.
     /// If the name is present, the old value and metadata will be returned.
@@ -279,7 +283,7 @@ impl FromIterator<KeyValueMetadata> for Baggage {
 
 /// Methods for sorting and retrieving baggage data in a context.
 pub trait BaggageExt {
-    /// Returns a clone of the given context with the included name-value pairs.
+    /// Returns a clone of the given context with the included name/value pairs.
     ///
     /// # Examples
     ///
@@ -299,7 +303,7 @@ pub trait BaggageExt {
         baggage: T,
     ) -> Self;
 
-    /// Returns a clone of the current context with the included name-value pairs.
+    /// Returns a clone of the current context with the included name/value pairs.
     ///
     /// # Examples
     ///
@@ -317,7 +321,7 @@ pub trait BaggageExt {
         baggage: T,
     ) -> Self;
 
-    /// Returns a clone of the given context with the included name-value pairs.
+    /// Returns a clone of the given context with the included name/value pairs.
     ///
     /// # Examples
     ///
@@ -370,7 +374,7 @@ impl BaggageExt for Context {
 /// An optional property set that can be added to [`Baggage`] values.
 ///
 /// `BaggageMetadata` can be added to values in the form of a property set,
-/// represented as semi-colon `;` delimited list of names and/or name-value
+/// represented as semi-colon `;` delimited list of names and/or name/value
 /// pairs, e.g. `;k1=v1;k2;k3=v3`.
 #[derive(Clone, Debug, PartialOrd, PartialEq, Default)]
 pub struct BaggageMetadata(String);
@@ -394,7 +398,7 @@ impl From<&str> for BaggageMetadata {
     }
 }
 
-/// [`Baggage`] name-value pairs with their associated metadata.
+/// [`Baggage`] name/value pairs with their associated metadata.
 #[derive(Clone, Debug, PartialEq)]
 pub struct KeyValueMetadata {
     /// Dimension or event key

opentelemetry-api/src/common.rs

@@ -1,7 +1,11 @@
 use std::borrow::Cow;
 use std::fmt;
 
-/// Key used for metric `AttributeSet`s and trace `Span` attributes.
+/// The key part of attribute [KeyValue] pairs.
+///
+/// See the [attribute naming] spec for guidelines.
+///
+/// [attribute naming]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/common/attribute-naming.md
 #[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Key(Cow<'static, str>);
 
@@ -89,7 +93,7 @@ impl fmt::Display for Key {
     }
 }
 
-/// Array of homogeneous values
+/// A [Value::Array] containing homogeneous values.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Array {
     /// Array of bools
@@ -152,7 +156,7 @@ into_array!(
     (Vec<Cow<'static, str>>, Array::String),
 );
 
-/// Value types for use in `KeyValue` pairs.
+/// The value part of attribute [KeyValue] pairs.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Value {
     /// bool values
@@ -231,12 +235,13 @@ impl fmt::Display for Value {
     }
 }
 
-/// `KeyValue` pairs are used by `AttributeSet`s and `Span` attributes.
+/// A key-value pair describing an attribute.
 #[derive(Clone, Debug, PartialEq)]
 pub struct KeyValue {
-    /// Dimension or event key
+    /// The attribute name
     pub key: Key,
-    /// Dimension or event value
+
+    /// The attribute value
     pub value: Value,
 }
 
@@ -260,26 +265,43 @@ pub trait ExportError: std::error::Error + Send + Sync + 'static {
     fn exporter_name(&self) -> &'static str;
 }
 
-/// InstrumentationLibrary contains information about instrumentation library.
+/// Information about a library or crate providing instrumentation.
 ///
-/// See `Instrumentation Libraries` for more information.
+/// An instrumentation library should be named to follow any naming conventions
+/// of the instrumented library (e.g. 'middleware' for a web framework).
 ///
-/// [`Instrumentation Libraries`](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries)
+/// See the [instrumentation libraries] spec for more information.
+///
+/// [instrumentation libraries]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/overview.md#instrumentation-libraries
 #[derive(Debug, Default, Hash, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub struct InstrumentationLibrary {
-    /// instrumentation library name, cannot be empty
+    /// The library name.
+    ///
+    /// This should be the name of the crate providing the instrumentation.
     pub name: Cow<'static, str>,
-    /// instrumentation library version, can be empty
+
+    /// The library version.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let library = opentelemetry_api::InstrumentationLibrary::new(
+    ///     "my-crate",
+    ///     Some(env!("CARGO_PKG_VERSION")),
+    ///     None,
+    /// );
+    /// ```
     pub version: Option<Cow<'static, str>>,
-    /// [Schema url] of spans and their events.
+
+    /// [Schema url] used by this library.
     ///
-    /// [Schema url]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#schema-url
+    /// [Schema url]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/schemas/overview.md#schema-url
     pub schema_url: Option<Cow<'static, str>>,
 }
 
 impl InstrumentationLibrary {
-    /// Create an InstrumentationLibrary from name and version.
+    /// Create an new instrumentation library.
     pub fn new<T>(name: T, version: Option<T>, schema_url: Option<T>) -> InstrumentationLibrary
     where
         T: Into<Cow<'static, str>>,

opentelemetry-api/src/global/mod.rs

@@ -22,6 +22,7 @@
 //! use opentelemetry_api::global;
 //!
 //! fn init_tracer() {
+//!     // Swap this no-op provider for your tracing service of choice (jaeger, zipkin, etc)
 //!     let provider = NoopTracerProvider::new();
 //!
 //!     // Configure the global `TracerProvider` singleton when your app starts
@@ -39,7 +40,7 @@
 //! }
 //!
 //! // in main or other app start
-//! let _ = init_tracer();
+//! init_tracer();
 //! do_something_tracked();
 //! # }
 //! ```

opentelemetry-api/src/trace/mod.rs

@@ -11,6 +11,37 @@
 //!
 //! ## Getting Started
 //!
+//! In application code:
+//!
+//! ```
+//! use opentelemetry_api::trace::{Tracer, noop::NoopTracerProvider};
+//! use opentelemetry_api::global;
+//!
+//! fn init_tracer() {
+//!     // Swap this no-op provider for your tracing service of choice (jaeger, zipkin, etc)
+//!     let provider = NoopTracerProvider::new();
+//!
+//!     // Configure the global `TracerProvider` singleton when your app starts
+//!     // (there is a no-op default if this is not set by your application)
+//!     let _ = global::set_tracer_provider(provider);
+//! }
+//!
+//! fn do_something_tracked() {
+//!     // Then you can get a named tracer instance anywhere in your codebase.
+//!     let tracer = global::tracer("my-component");
+//!
+//!     tracer.in_span("doing_work", |cx| {
+//!         // Traced app logic here...
+//!     });
+//! }
+//!
+//! // in main or other app start
+//! init_tracer();
+//! do_something_tracked();
+//! ```
+//!
+//! In library code:
+//!
 //! ```
 //! use opentelemetry_api::{global, trace::{Span, Tracer, TracerProvider}};
 //!

opentelemetry-api/src/trace/tracer.rs

@@ -373,25 +373,28 @@ impl SpanBuilder {
     }
 }
 
-/// The result of sampling logic for a given `Span`.
+/// The result of sampling logic for a given span.
 #[derive(Clone, Debug, PartialEq)]
 pub struct SamplingResult {
-    /// `SamplingDecision` reached by this result
+    /// The decision about whether or not to sample.
     pub decision: SamplingDecision,
-    /// Extra attributes added by this result
+
+    /// Extra attributes to be added to the span by the sampler
     pub attributes: Vec<KeyValue>,
-    /// Trace state from parent context, might be modified by sampler
+
+    /// Trace state from parent context, may be modified by samplers.
     pub trace_state: TraceState,
 }
 
 /// Decision about whether or not to sample
 #[derive(Clone, Debug, PartialEq)]
 pub enum SamplingDecision {
-    /// `is_recording() == false`, span will not be recorded and all events and
-    /// attributes will be dropped.
+    /// Span will not be recorded and all events and attributes will be dropped.
     Drop,
-    /// `is_recording() == true`, but `Sampled` flag MUST NOT be set.
+
+    /// Span data wil be recorded, but not exported.
     RecordOnly,
-    /// `is_recording() == true` AND `Sampled` flag` MUST be set.
+
+    /// Span data will be recorded and exported.
     RecordAndSample,
 }