Cleanup crate documentation (open-telemetry#1278)

* Cleanup crate documentation - mainly this removes circular dev-dependencies between the api, sdk, and stdout crates. * Some things need to be behind "trace" feature
lumeohq · Sep 23, 2023 · bea0aa5 · bea0aa5
1 parent f7684b0
commit bea0aa5
Show file tree

Hide file tree

Showing 9 changed files with 52 additions and 62 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -25,10 +25,13 @@
     // these are words that are always correct and can be thought of as our
     // workspace dictionary.
     "words": [
+        "deque",
         "hasher",
+        "msrv",
         "opentelemetry",
         "OTLP",
         "quantile",
+        "rustc",
         "zipkin"
     ],
     "enabledLanguageIds": [
@@ -63,4 +66,4 @@
             ]
         }
     ]
-}
+}
diff --git a/opentelemetry-sdk/CHANGELOG.md b/opentelemetry-sdk/CHANGELOG.md
@@ -24,6 +24,8 @@
 - Return error earlier if readers are shut down (#1266)
 - Add `/` to valid characters for instrument names (#1269)
 - Increase instrument name maximum length from 63 to 255 (#1269)
+- Updated crate documentation and examples.
+  [#1256](https://github.com/open-telemetry/opentelemetry-rust/issues/1256)
 
 ### Removed
 

diff --git a/opentelemetry-sdk/src/lib.rs b/opentelemetry-sdk/src/lib.rs
@@ -1,6 +1,10 @@
-//! OpenTelemetry is a collection of tools, APIs, and SDKs. Use it to
-//! instrument, generate, collect, and export telemetry data (metrics, logs, and
-//! traces) to help you analyze your software's performance and behavior.
+//! Implements the [`SDK`] component of [OpenTelemetry].
+//!
+//! *Compiler support: [requires `rustc` 1.64+][msrv]*
+//!
+//! [`SDK`]: https://opentelemetry.io/docs/specs/otel/overview/#sdk
+//! [OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
+//! [msrv]: #supported-rust-versions
 //!
 //! # Getting Started
 //!

diff --git a/opentelemetry/CHANGELOG.md b/opentelemetry/CHANGELOG.md
@@ -8,6 +8,8 @@
 - `opentelemetry` crate now only carries the API types #1186. Use the `opentelemetry_sdk` crate for the SDK types. 
 - `trace::noop::NoopSpan` no longer implements `Default` and instead exposes
   a `const DEFAULT` value. [#1270](https://github.com/open-telemetry/opentelemetry-rust/pull/1270)
+- Updated crate documentation and examples.
+  [#1256](https://github.com/open-telemetry/opentelemetry-rust/issues/1256)
 
 ## [v0.20.0](https://github.com/open-telemetry/opentelemetry-rust/compare/v0.19.0...v0.20.0)
 This release should been seen as 1.0-rc3 following 1.0-rc2 in v0.19.0. Refer to CHANGELOG.md in individual creates for details on changes made in different creates.

diff --git a/opentelemetry/Cargo.toml b/opentelemetry/Cargo.toml
@@ -32,10 +32,6 @@ urlencoding = "2.1.2"
 [target.'cfg(all(target_arch = "wasm32", not(target_os = "wasi")))'.dependencies]
 js-sys = "0.3.63"
 
-[dev-dependencies]
-opentelemetry_sdk = { version = "0.20", path = "../opentelemetry-sdk" }
-opentelemetry-stdout = { version = "0.1", path = "../opentelemetry-stdout", features = ["trace"] }
-
 [features]
 default = ["trace"]
 trace = ["pin-project-lite"]

diff --git a/opentelemetry/src/context.rs b/opentelemetry/src/context.rs
@@ -1,3 +1,4 @@
+#[cfg(feature = "trace")]
 use crate::trace::context::SynchronizedSpan;
 use std::any::{Any, TypeId};
 use std::cell::RefCell;
@@ -75,6 +76,7 @@ thread_local! {
 /// ```
 #[derive(Clone, Default)]
 pub struct Context {
+    #[cfg(feature = "trace")]
     pub(super) span: Option<Arc<SynchronizedSpan>>,
     entries: HashMap<TypeId, Arc<dyn Any + Sync + Send>, BuildHasherDefault<IdHasher>>,
 }
@@ -306,13 +308,15 @@ impl Context {
         }
     }
 
+    #[cfg(feature = "trace")]
     pub(super) fn current_with_synchronized_span(value: SynchronizedSpan) -> Self {
         Context {
             span: Some(Arc::new(value)),
             entries: Context::map_current(|cx| cx.entries.clone()),
         }
     }
 
+    #[cfg(feature = "trace")]
     pub(super) fn with_synchronized_span(&self, value: SynchronizedSpan) -> Self {
         Context {
             span: Some(Arc::new(value)),

diff --git a/opentelemetry/src/lib.rs b/opentelemetry/src/lib.rs
@@ -1,37 +1,22 @@
-//! OpenTelemetry provides a single set of APIs, libraries, agents, and collector
-//! services to capture distributed traces and metrics from your application. You
-//! can analyze them using [Prometheus], [Jaeger], and other observability tools.
+//! Implements the [`API`] component of [OpenTelemetry].
 //!
 //! *Compiler support: [requires `rustc` 1.64+][msrv]*
 //!
-//! [Prometheus]: https://prometheus.io
-//! [Jaeger]: https://www.jaegertracing.io
+//! [`API`]: https://opentelemetry.io/docs/specs/otel/overview/#api
+//! [OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
 //! [msrv]: #supported-rust-versions
 //!
 //! # Getting Started
 //!
 //! ```no_run
 //! # #[cfg(feature = "trace")]
 //! # {
-//! use opentelemetry::{
-//!     global,
-//!     trace::{Tracer, TracerProvider as _},
-//! };
-//! use opentelemetry_sdk::trace::TracerProvider;
-//!
-//! fn main() {
-//!     // Create a new trace pipeline that prints to stdout
-//!     let provider = TracerProvider::builder()
-//!         .with_simple_exporter(opentelemetry_stdout::SpanExporter::default())
-//!         .build();
-//!     let tracer = provider.tracer("readme_example");
-//!
-//!     tracer.in_span("doing_work", |cx| {
-//!         // Traced app logic here...
-//!     });
-//!
-//!     // Shutdown trace pipeline
-//!     global::shutdown_tracer_provider();
+//! use opentelemetry::{global, trace::{TraceContextExt, Tracer}, Context };
+//!
+//! fn do_something() {
+//!     let tracer = global::tracer("my_component");
+//!     let _guard = Context::current_with_span(tracer.start("my_span")).attach();
+//!     // do work tracked by the now current span
 //! }
 //! # }
 //! ```
@@ -109,18 +94,9 @@
 //!
 //! The following core crate feature flags are available:
 //!
-//! * `trace`: Includes the trace API and SDK (enabled by default).
-//! * `metrics`: Includes the unstable metrics API and SDK.
-//!
-//! Support for recording and exporting telemetry asynchronously can be added
-//! via the following flags:
-//!
-//! * `rt-tokio`: Spawn telemetry tasks using [tokio]'s multi-thread runtime.
-//! * `rt-tokio-current-thread`: Spawn telemetry tasks on a separate runtime so that the main runtime won't be blocked.
-//! * `rt-async-std`: Spawn telemetry tasks using [async-std]'s runtime.
-//!
-//! [tokio]: https://crates.io/crates/tokio
-//! [async-std]: https://crates.io/crates/async-std
+//! * `trace`: Includes the trace API (enabled by default).
+//! * `metrics`: Includes the unstable metrics API.
+//! * `logs`: Includes the logs bridge API.
 //!
 //! ## Related Crates
 //!
@@ -133,6 +109,7 @@
 //!
 //! In particular, the following crates are likely to be of interest:
 //!
+//! - [`opentelemetry_sdk`] provides the SDK used to configure providers.
 //! - [`opentelemetry-http`] provides an interface for injecting and extracting
 //!   trace information from [`http`] headers.
 //! - [`opentelemetry-jaeger`] provides a pipeline and exporter for sending
@@ -167,31 +144,31 @@
 //! If you're the maintainer of an `opentelemetry` ecosystem crate not listed
 //! above, please let us know! We'd love to add your project to the list!
 //!
-//! [`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
-//! [`opentelemetry-jaeger`]: https://crates.io/crates/opentelemetry-jaeger
+//! [`actix-web-opentelemetry`]: https://crates.io/crates/actix-web-opentelemetry
+//! [`actix-web`]: https://crates.io/crates/actix-web
+//! [`Datadog`]: https://www.datadoghq.com
+//! [`http`]: https://crates.io/crates/http
 //! [`Jaeger`]: https://www.jaegertracing.io
-//! [`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp
-//! [`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http
-//! [`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus
+//! [`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
+//! [`opentelemetry_sdk`]: https://crates.io/crates/opentelemetry_sdk
+//! [`opentelemetry-application-insights`]: https://crates.io/crates/opentelemetry-application-insights
 //! [`opentelemetry-aws`]: https://crates.io/crates/opentelemetry-aws
-//! [`Prometheus`]: https://prometheus.io
-//! [`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
-//! [`http`]: https://crates.io/crates/http
-//! [`Zipkin`]: https://zipkin.io
 //! [`opentelemetry-contrib`]: https://crates.io/crates/opentelemetry-contrib
 //! [`opentelemetry-datadog`]: https://crates.io/crates/opentelemetry-datadog
-//! [`Datadog`]: https://www.datadoghq.com
+//! [`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http
+//! [`opentelemetry-jaeger`]: https://crates.io/crates/opentelemetry-jaeger
+//! [`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp
+//! [`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus
 //! [`opentelemetry-semantic-conventions`]: https://crates.io/crates/opentelemetry-semantic-conventions
-//!
+//! [`opentelemetry-stackdriver`]: https://crates.io/crates/opentelemetry-stackdriver
+//! [`opentelemetry-tide`]: https://crates.io/crates/opentelemetry-tide
+//! [`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
+//! [`Prometheus`]: https://prometheus.io
+//! [`Tide`]: https://crates.io/crates/tide
 //! [`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
 //! [`tracing`]: https://crates.io/crates/tracing
-//! [`actix-web-opentelemetry`]: https://crates.io/crates/actix-web-opentelemetry
-//! [`actix-web`]: https://crates.io/crates/actix-web
-//! [`opentelemetry-application-insights`]: https://crates.io/crates/opentelemetry-application-insights
+//! [`Zipkin`]: https://zipkin.io
 //! [Azure Application Insights]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview
-//! [`opentelemetry-tide`]: https://crates.io/crates/opentelemetry-tide
-//! [`Tide`]: https://crates.io/crates/tide
-//! [`opentelemetry-stackdriver`]: https://crates.io/crates/opentelemetry-stackdriver
 //! [Cloud Trace]: https://cloud.google.com/trace/
 //!
 //! ## Supported Rust Versions

diff --git a/opentelemetry/src/testing/mod.rs b/opentelemetry/src/testing/mod.rs
@@ -1 +1,3 @@
+#[cfg(feature = "trace")]
+#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
 pub mod trace;
diff --git a/opentelemetry/src/trace/mod.rs b/opentelemetry/src/trace/mod.rs
@@ -7,7 +7,7 @@
 //! through a system. This module implements the OpenTelemetry [trace
 //! specification].
 //!
-//! [trace specification]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.3.0/specification/trace/api.md
+//! [trace specification]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md
 //!
 //! ## Getting Started
 //!