Merge branch 'main' into fix-changelogs

cijothomas · web-flow · commit 6a323452b12f · 2024-02-29T08:45:52.000-08:00
diff --git a/README.md b/README.md
@@ -100,10 +100,14 @@ The following crates are maintained in this repo:
 * [`opentelemetry-sdk`] This is the OpenTelemetry SDK crate, and contains the
   official OpenTelemetry SDK implementation. It contains Logging SDK, Metrics
   SDK, and Tracing SDK. It also contains propagator implementations.
-* [`opentelemetry-otlp`] exporter for sending logs, metrics and traces in the
-  OTLP format to an endpoint accepting OTLP, like the [OpenTelemetry
-  collector](https://opentelemetry.io/docs/collector/), or [vendor specific
-  endpoints](https://opentelemetry.io/ecosystem/vendors/).
+* [`opentelemetry-otlp`] - exporter to send telemetry (logs, metrics and traces)
+  in the [OTLP
+  format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol)
+  to an endpoint accepting OTLP. This could be the [OTel
+  Collector](https://github.com/open-telemetry/opentelemetry-collector),
+  telemetry backends like [Jaeger](https://www.jaegertracing.io/),
+  [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver)
+  or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/).
 * [`opentelemetry-stdout`] exporter for sending logs, metrics and traces to
   stdout, for learning/debugging purposes.  
 * [`opentelemetry-http`] This crate contains utility functions to help with
diff --git a/opentelemetry-jaeger/src/exporter/thrift/agent.rs b/opentelemetry-jaeger/src/exporter/thrift/agent.rs
@@ -3,7 +3,7 @@
 
 #![allow(unused_imports)]
 #![allow(unused_extern_crates)]
-#![cfg_attr(feature = "cargo-clippy", allow(clippy::too_many_arguments, clippy::type_complexity))]
+#![cfg_attr(clippy, allow(clippy::too_many_arguments, clippy::type_complexity))]
 #![cfg_attr(rustfmt, rustfmt_skip)]
 
 extern crate thrift;
diff --git a/opentelemetry-jaeger/src/exporter/thrift/jaeger.rs b/opentelemetry-jaeger/src/exporter/thrift/jaeger.rs
@@ -3,7 +3,7 @@
 
 #![allow(unused_imports)]
 #![allow(unused_extern_crates)]
-#![cfg_attr(feature = "cargo-clippy", allow(clippy::too_many_arguments, clippy::type_complexity))]
+#![cfg_attr(clippy, allow(clippy::too_many_arguments, clippy::type_complexity))]
 #![cfg_attr(rustfmt, rustfmt_skip)]
 
 extern crate thrift;
diff --git a/opentelemetry-jaeger/src/exporter/thrift/zipkincore.rs b/opentelemetry-jaeger/src/exporter/thrift/zipkincore.rs
@@ -3,7 +3,7 @@
 
 #![allow(unused_imports)]
 #![allow(unused_extern_crates)]
-#![cfg_attr(feature = "cargo-clippy", allow(clippy::too_many_arguments, clippy::type_complexity))]
+#![cfg_attr(clippy, allow(clippy::too_many_arguments, clippy::type_complexity))]
 #![cfg_attr(rustfmt, rustfmt_skip)]
 
 extern crate thrift;
diff --git a/opentelemetry-otlp/CHANGELOG.md b/opentelemetry-otlp/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## vNext
 
+### Added
+
+- Added `DeltaTemporalitySelector` ([#1568])
+
+[#1568]: https://github.com/open-telemetry/opentelemetry-rust/pull/1568
+
 ## v0.15.0
 
 ### Added
diff --git a/opentelemetry-otlp/src/metric.rs b/opentelemetry-otlp/src/metric.rs
@@ -169,6 +169,16 @@ where
         }
     }
 
+    /// Build with delta temporality selector.
+    ///
+    /// This temporality selector is equivalent to OTLP Metrics Exporter's
+    /// `Delta` temporality preference (see [its documentation][exporter-docs]).
+    ///
+    /// [exporter-docs]: https://github.com/open-telemetry/opentelemetry-specification/blob/a1c13d59bb7d0fb086df2b3e1eaec9df9efef6cc/specification/metrics/sdk_exporters/otlp.md#additional-configuration
+    pub fn with_delta_temporality(self) -> Self {
+        self.with_temporality_selector(DeltaTemporalitySelector)
+    }
+
     /// Build with the given aggregation selector
     pub fn with_aggregation_selector<T: AggregationSelector + 'static>(self, selector: T) -> Self {
         OtlpMetricPipeline {
@@ -248,6 +258,35 @@ impl<RT, EB: Debug> Debug for OtlpMetricPipeline<RT, EB> {
     }
 }
 
+/// A temporality selector that returns [`Delta`][Temporality::Delta] for all
+/// instruments except `UpDownCounter` and `ObservableUpDownCounter`.
+///
+/// This temporality selector is equivalent to OTLP Metrics Exporter's
+/// `Delta` temporality preference (see [its documentation][exporter-docs]).
+///
+/// [exporter-docs]: https://github.com/open-telemetry/opentelemetry-specification/blob/a1c13d59bb7d0fb086df2b3e1eaec9df9efef6cc/specification/metrics/sdk_exporters/otlp.md#additional-configuration
+#[derive(Debug)]
+struct DeltaTemporalitySelector;
+
+impl TemporalitySelector for DeltaTemporalitySelector {
+    #[rustfmt::skip]
+    fn temporality(&self, kind: InstrumentKind) -> Temporality {
+        match kind {
+            InstrumentKind::Counter
+            | InstrumentKind::Histogram
+            | InstrumentKind::ObservableCounter
+            | InstrumentKind::Gauge
+            | InstrumentKind::ObservableGauge => {
+                Temporality::Delta
+            }
+            InstrumentKind::UpDownCounter
+            | InstrumentKind::ObservableUpDownCounter => {
+                Temporality::Cumulative
+            }
+        }
+    }
+}
+
 /// An interface for OTLP metrics clients
 #[async_trait]
 pub trait MetricsClient: fmt::Debug + Send + Sync + 'static {
diff --git a/opentelemetry/Cargo.toml b/opentelemetry/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "opentelemetry"
 version = "0.22.0"
-description = "A metrics collection and distributed tracing framework"
+description = "OpenTelemetry API for Rust"
 homepage = "https://github.com/open-telemetry/opentelemetry-rust"
 repository = "https://github.com/open-telemetry/opentelemetry-rust"
 readme = "README.md"
diff --git a/opentelemetry/README.md b/opentelemetry/README.md
@@ -1,10 +1,6 @@
-![OpenTelemetry — An observability framework for cloud-native software.][splash]
-
-[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png
-
 # OpenTelemetry Rust
 
-The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
+This crate contains the [OpenTelemetry](https://opentelemetry.io/) API for Rust.
 
 [![Crates.io: opentelemetry](https://img.shields.io/crates/v/opentelemetry.svg)](https://crates.io/crates/opentelemetry)
 [![Documentation](https://docs.rs/opentelemetry/badge.svg)](https://docs.rs/opentelemetry)
@@ -15,124 +11,120 @@ The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
 
 ## Overview
 
-OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument,
-generate, collect, and export telemetry data (metrics, logs, and traces) for
-analysis in order to understand your software's performance and behavior. You
-can export and analyze them using [Prometheus], [Jaeger], and other
-observability tools.
+OpenTelemetry is an Observability framework and toolkit designed to create and
+manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
+vendor- and tool-agnostic, meaning that it can be used with a broad variety of
+Observability backends, including open source tools like [Jaeger] and
+[Prometheus], as well as commercial offerings.
+
+OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
+commercial vendors. OpenTelemetry is focused on the generation, collection,
+management, and export of telemetry. A major goal of OpenTelemetry is that you
+can easily instrument your applications or systems, no matter their language,
+infrastructure, or runtime environment. Crucially, the storage and visualization
+of telemetry is intentionally left to other tools.
 
 *Compiler support: [requires `rustc` 1.64+][msrv]*
 
 [Prometheus]: https://prometheus.io
 [Jaeger]: https://www.jaegertracing.io
 [msrv]: #supported-rust-versions
 
-## Getting Started
-
-```rust
-use opentelemetry::{
-    global,
-    sdk::trace::TracerProvider,
-    trace::{Tracer, TracerProvider as _},
-};
-
-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();
-}
-```
-
-See the [examples](../examples) directory for different integration patterns.
-
-## Ecosystem
-
-### Related Crates
-
-In addition to `opentelemetry`, which only carries the API, the
-[`open-telemetry/opentelemetry-rust`] repository contains several additional
-crates designed to be used with the `opentelemetry` ecosystem. This includes a
-collection of trace `SpanExporter` and metrics pull and push controller
-implementations, as well as utility and adapter crates to assist in propagating
-state and instrumenting applications.
-
-In particular, the following crates are likely to be of interest:
-
-- [`opentelemetry-aws`] provides unofficial propagators for AWS X-ray.
-- [`opentelemetry-contrib`] provides additional exporters and propagators that
-  are experimental.
-- [`opentelemetry-datadog`] provides additional exporters to [`Datadog`].
-- [`opentelemetry-dynatrace`] *Deprecated, last release 0.4.0* provides additional exporters to [`Dynatrace`]. See [README][`opentelemetry-dynatrace-readme`]
-- [`opentelemetry-http`] provides an interface for injecting and extracting
-  trace information from [`http`] headers.
-- [`opentelemetry-jaeger`] provides a pipeline and exporter for sending trace
-  information to [`Jaeger`].
-- [`opentelemetry-otlp`] exporter for sending trace and metric data in the OTLP
-  format to the OpenTelemetry collector.
-- [`opentelemetry-prometheus`] provides a pipeline and exporter for sending
-  metrics information to [`Prometheus`].
-- [`opentelemetry_sdk`] provides the standard reference implementation of
-  opentelemetry.
-- [`opentelemetry-semantic-conventions`] provides standard names and semantic
-  otel conventions.
-- [`opentelemetry-stackdriver`] provides an exporter for Google's [Cloud Trace]
-  (which used to be called StackDriver).
-- [`opentelemetry-zipkin`] provides a pipeline and exporter for sending trace
-  information to [`Zipkin`].
-
-Additionally, there are also several third-party crates which are not
-maintained by the `opentelemetry` project. These include:
-
-- [`tracing-opentelemetry`] provides integration for applications instrumented
-  using the [`tracing`] API and ecosystem.
-- [`actix-web-opentelemetry`] provides integration for the [`actix-web`] web
-  server and ecosystem.
-- [`opentelemetry-application-insights`] provides an unofficial [Azure
-  Application Insights] exporter.
-- [`opentelemetry-tide`] provides integration for the [`Tide`] web server and
-  ecosystem.
-
-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
-[`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
-[`opentelemetry-aws`]: https://crates.io/crates/opentelemetry-aws
-[`Prometheus`]: https://prometheus.io
-[`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
-[`Zipkin`]: https://zipkin.io
-[`opentelemetry-contrib`]: https://crates.io/crates/opentelemetry-contrib
-[`Datadog`]: https://www.datadoghq.com
-[`Dynatrace`]: https://www.dynatrace.com
-[`opentelemetry-datadog`]: https://crates.io/crates/opentelemetry-datadog
-[`opentelemetry-dynatrace`]: https://crates.io/crates/opentelemetry-dynatrace
-[`opentelemetry-dynatrace-readme`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/blob/main/opentelemetry-dynatrace/README.md
-[`opentelemetry-semantic-conventions`]: https://crates.io/crates/opentelemetry-semantic-conventions
-[`http`]: https://crates.io/crates/http
-
-[`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
-[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/
+### What does this crate contain?
+
+This crate is basic foundation for integrating OpenTelemetry into libraries and
+applications, encompassing several aspects of OpenTelemetry, such as context
+management and propagation, baggage, logging, tracing, and metrics. It follows
+the [OpenTelemetry
+specification](https://github.com/open-telemetry/opentelemetry-specification).
+Here's a breakdown of its components:
+
+- **[Context
+  API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):**
+  Provides a way to manage and propagate context, which is essential for keeping
+  track of trace execution across asynchronous tasks.
+- **[Propagators
+  API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):**
+  Defines how context can be shared across process boundaries, ensuring
+  continuity across microservices or distributed systems.
+- **[Baggage
+  API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):**
+  Allows for the attachment of metadata (baggage) to telemetry, which can be
+  used for sharing application-specific information across service boundaries.
+- **[Logs Bridge
+  API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md):**
+  Allows to bridge existing logging mechanisms with OpenTelemetry logging. This
+  is **NOT** meant for end users to call, instead it is meant to enable writing
+  bridges/appenders for existing logging mechanisms such as
+  [log](https://crates.io/crates/log) or
+  [tracing](https://crates.io/crates/tracing).
+- **[Tracing
+  API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):**
+  Offers a set of primitives to produce distributed traces to understand the
+  flow of a request across system boundaries.
+- **[Metrics
+  API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):**
+  Offers a set of primitives to produce measurements of operational metrics like
+  latency, throughput, or error rates.
+
+This crate serves as a facade or no-op implementation, meaning it defines the
+traits for instrumentation but does not itself implement the processing or
+exporting of telemetry data. This separation of concerns allows library authors
+to depend on the API crate without tying themselves to a specific
+implementation.
+
+Actual implementation and the heavy lifting of telemetry data collection,
+processing, and exporting are delegated to the
+[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) crate and
+various exporter crates such as
+[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). This
+architecture ensures that the final application can light up the instrumentation
+by integrating an SDK implementation.
+
+Library authors are recommended to depend on this crate *only*. This approach is
+also aligned with the design philosophy of existing telemetry solutions in the
+Rust ecosystem, like `tracing` or `log`, where these crates only offer a facade
+and the actual functionality is enabled through additional crates.
+
+### Related crates
+
+Unless you are a library author, you will almost always need to use additional
+crates along with this. Given this crate has no-op implementation only, an
+OpenTelemetry SDK is always required.
+[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) is the official
+SDK implemented by OpenTelemetry itself, though it is possible to use a
+different sdk.
+
+Additionally one or more exporters are also required to export telemetry to a
+destination. OpenTelemetry provides the following exporters:
+
+- **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):**
+  Prints telemetry to stdout, primarily used for learning/debugging purposes.
+- **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports
+  telemetry (logs, metrics and traces) in the [OTLP
+  format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol)
+  to an endpoint accepting OTLP. This could be the [OTel
+  Collector](https://github.com/open-telemetry/opentelemetry-collector),
+  telemetry backends like [Jaeger](https://www.jaegertracing.io/),
+  [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver)
+  or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/).
+- **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):**
+  Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin
+  specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md)
+- **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):**
+  Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to
+  Prometheus
+  specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md)
+
+OpenTelemetry Rust also has a [contrib
+repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where
+additional exporters could be found. Check [OpenTelemetry
+Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for
+additional exporters and other related components as well.
+
+## Getting started
+
+See [docs](https://docs.rs/opentelemetry).
 
 ## Supported Rust Versions
 
@@ -146,7 +138,3 @@ version is 1.49, the minimum supported version will not be increased past 1.46,
 three minor versions prior. Increasing the minimum supported compiler version
 is not considered a semver breaking change as long as doing so complies with
 this policy.
-
-## Contributing
-
-See the [contributing file](../CONTRIBUTING.md).
