Merge branch 'main' into cijothomas/029doc

Author: cijothomas

opentelemetry-otlp/src/lib.rs

@@ -103,7 +103,61 @@
 //! After running your application configured with the OTLP exporter, view traces at:
 //! `http://localhost:16686`
 //!
-//! ## Using with Prometheus (TODO)
+//! ## Using with Prometheus
+//!
+//! Prometheus natively supports accepting metrics via the OTLP protocol
+//! (HTTP/protobuf). You can [run
+//! Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) with
+//! the following command:
+//!
+//! ```shell
+//! docker run -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml --web.enable-otlp-receiver
+//! ```
+//!
+//! (An empty prometheus.yml file is sufficient for this example.)
+//!
+//! Modify your application to export metrics via OTLP:
+//!
+//! ```no_run
+//! # #[cfg(all(feature = "metrics", feature = "http-proto"))]
+//! # {
+//! use opentelemetry::global;
+//! use opentelemetry::metrics::Meter;
+//! use opentelemetry::KeyValue;
+//! use opentelemetry_otlp::Protocol;
+//! use opentelemetry_otlp::WithExportConfig;
+//!
+//! fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
+//!     // Initialize OTLP exporter using HTTP binary protocol
+//!     let exporter = opentelemetry_otlp::MetricExporter::builder()
+//!         .with_http()
+//!         .with_protocol(Protocol::HttpBinary)
+//!         .with_endpoint("http://localhost:9090/api/v1/otlp/v1/metrics")
+//!         .build()?;
+//!
+//!     // Create a meter provider with the OTLP Metric exporter
+//!     let meter_provider = opentelemetry_sdk::metrics::SdkMeterProvider::builder()
+//!         .with_periodic_exporter(exporter)
+//!         .build();
+//!     global::set_meter_provider(meter_provider.clone());
+//!
+//!     // Get a meter
+//!     let meter = global::meter("my_meter");
+//!
+//!     // Create a metric
+//!     let counter = meter.u64_counter("my_counter").build();
+//!     counter.add(1, &[KeyValue::new("key", "value")]);
+//!
+//!     // Shutdown the meter provider. This will trigger an export of all metrics.
+//!     meter_provider.shutdown()?;
+//!
+//!     Ok(())
+//! # }
+//! }
+//! ```
+//!
+//! After running your application configured with the OTLP exporter, view metrics at:
+//! `http://localhost:9090`
 //! ## Show Logs, Metrics too (TODO)
 //!
 //! ## Performance

opentelemetry-prometheus/README.md

@@ -6,8 +6,19 @@
 
 [`Prometheus`] integration for applications instrumented with [`OpenTelemetry`]. 
 
-**The development of prometheus exporter has halt until the Opentelemetry metrics API and SDK reaches 1.0. Current 
-implementation is based on Opentelemetry API and SDK 0.27**.
+**Warning: This crate is no longer recommended for use.**
+
+Development of the Prometheus exporter has been discontinued. See the related
+[issue](https://github.com/open-telemetry/opentelemetry-rust/issues/2451). This
+crate depends on the unmaintained `protobuf` crate and has unresolved security
+vulnerabilities. Version 0.29 will be the final release.
+
+For Prometheus integration, we strongly recommend using the [OTLP] exporter
+instead. Prometheus [natively supports
+OTLP](https://prometheus.io/docs/guides/opentelemetry/#enable-the-otlp-receiver),
+providing a more stable and actively maintained solution.
+
+[OTLP]: https://docs.rs/opentelemetry-otlp/latest/opentelemetry_otlp/
 
 [![Crates.io: opentelemetry-prometheus](https://img.shields.io/crates/v/opentelemetry-prometheus.svg)](https://crates.io/crates/opentelemetry-prometheus)
 [![Documentation](https://docs.rs/opentelemetry-prometheus/badge.svg)](https://docs.rs/opentelemetry-prometheus)

opentelemetry-prometheus/src/lib.rs

@@ -1,9 +1,19 @@
 //! An OpenTelemetry exporter for [Prometheus] metrics.
 //!
-//! <div class="warning"> The development of prometheus exporter has halt until the Opentelemetry metrics API and SDK reaches 1.0. Current
-//! implementation is based on Opentelemetry API and SDK 0.23.</div>
+//! <div class="warning">
+//! <strong>Warning: This crate is no longer recommended for use.</strong><br><br>
+//! Development of the Prometheus exporter has been discontinued. See the related 
+//! [issue](https://github.com/open-telemetry/opentelemetry-rust/issues/2451).
+//! This crate depends on the unmaintained `protobuf` crate and has unresolved 
+//! security vulnerabilities. Version 0.29 will be the final release.
+//!
+//! For Prometheus integration, we strongly recommend using the [OTLP] exporter instead.
+//! Prometheus [natively supports OTLP](https://prometheus.io/docs/guides/opentelemetry/#enable-the-otlp-receiver),
+//! providing a more stable and actively maintained solution.
+//! </div>
 //!
 //! [Prometheus]: https://prometheus.io
+//! [OTLP]: https://docs.rs/opentelemetry-otlp/latest/opentelemetry_otlp/
 //!
 //! ```
 //! use opentelemetry::{metrics::MeterProvider, KeyValue};

opentelemetry-zipkin/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## vNext
 
+- **Breaking** The `ZipkinExporterBuilder::build()` method now returns a
+  `Result<ZipkinExporter, ExporterBuildError>`. The `ExporterBuildError` enum
+  lists possible failures specific to the Zipkin exporter and was renamed from
+  `opentelemetry_zipkin::Error`. Previously, this method returned a `TraceError`
+  from the `opentelemetry_sdk` crate, which was unrelated to Zipkin builder
+  failures.
+  [2839](https://github.com/open-telemetry/opentelemetry-rust/pull/2839)
+
 ## 0.28.0
 
 Released 2025-Feb-10

opentelemetry-zipkin/examples/zipkin.rs

@@ -3,11 +3,8 @@ use opentelemetry::{
     trace::{Span, Tracer},
     InstrumentationScope, KeyValue,
 };
-use opentelemetry_sdk::{
-    trace::{SdkTracerProvider, TraceError},
-    Resource,
-};
-use opentelemetry_zipkin::ZipkinExporter;
+use opentelemetry_sdk::{trace::SdkTracerProvider, Resource};
+use opentelemetry_zipkin::{ExporterBuildError, ZipkinExporter};
 use std::thread;
 use std::time::Duration;
 
@@ -18,7 +15,7 @@ fn bar() {
     span.end()
 }
 
-fn init_traces() -> Result<SdkTracerProvider, TraceError> {
+fn init_traces() -> Result<SdkTracerProvider, ExporterBuildError> {
     let exporter = ZipkinExporter::builder().build()?;
 
     Ok(SdkTracerProvider::builder()

opentelemetry-zipkin/src/exporter/env.rs

@@ -6,7 +6,7 @@ const DEFAULT_COLLECTOR_ENDPOINT: &str = "http://127.0.0.1:9411/api/v2/spans";
 
 /// HTTP endpoint for Zipkin collector.
 /// e.g. "http://localhost:9411/api/v2/spans"
-const ENV_ENDPOINT: &str = "OTEL_EXPORTER_ZIPKIN_ENDPOINT";
+pub(crate) const ENV_ENDPOINT: &str = "OTEL_EXPORTER_ZIPKIN_ENDPOINT";
 
 /// Maximum time the Zipkin exporter will wait for each batch export
 const ENV_TIMEOUT: &str = "OTEL_EXPORTER_ZIPKIN_TIMEOUT";

opentelemetry-zipkin/src/exporter/mod.rs

@@ -6,8 +6,7 @@ use http::Uri;
 use model::endpoint::Endpoint;
 use opentelemetry_http::HttpClient;
 use opentelemetry_sdk::error::OTelSdkResult;
-use opentelemetry_sdk::trace::TraceError;
-use opentelemetry_sdk::{trace, ExportError};
+use opentelemetry_sdk::trace;
 use std::net::{AddrParseError, SocketAddr};
 use std::sync::Arc;
 
@@ -75,7 +74,7 @@ impl ZipkinExporterBuilder {
     /// Creates a new [ZipkinExporter] from this configuration.
     ///
     /// Returns error if the endpoint is not valid or if no http client is provided.
-    pub fn build(self) -> Result<ZipkinExporter, TraceError> {
+    pub fn build(self) -> Result<ZipkinExporter, ExporterBuildError> {
         let endpoint = Endpoint::new(self.service_addr);
 
         if let Some(client) = self.client {
@@ -84,15 +83,19 @@ impl ZipkinExporterBuilder {
                 client,
                 self.collector_endpoint
                     .parse()
-                    .map_err::<Error, _>(Into::into)?,
+                    .map_err(ExporterBuildError::InvalidUri)?,
             );
             Ok(exporter)
         } else {
-            Err(Error::NoHttpClient.into())
+            Err(ExporterBuildError::NoHttpClient)
         }
     }
 
     /// Assign client implementation
+    ///
+    /// When using this method, the export timeout will depend on the provided
+    /// client implementation and may not respect the timeout set via the
+    /// environment variable `OTEL_EXPORTER_ZIPKIN_TIMEOUT`.
     pub fn with_http_client<T: HttpClient + 'static>(mut self, client: T) -> Self {
         self.client = Some(Arc::new(client));
         self
@@ -105,6 +108,9 @@ impl ZipkinExporterBuilder {
     }
 
     /// Assign the Zipkin collector endpoint
+    ///
+    /// Note: Programmatically setting this will override any value
+    /// set via the environment variable `OTEL_EXPORTER_ZIPKIN_ENDPOINT`.
     pub fn with_collector_endpoint<T: Into<String>>(mut self, endpoint: T) -> Self {
         self.collector_endpoint = endpoint.into();
         self
@@ -134,30 +140,42 @@ impl trace::SpanExporter for ZipkinExporter {
 /// Wrap type for errors from opentelemetry zipkin
 #[derive(thiserror::Error, Debug)]
 #[non_exhaustive]
-pub enum Error {
+pub enum ExporterBuildError {
     /// No http client implementation found. User should provide one or enable features.
     #[error("http client must be set, users can enable reqwest feature to use http client implementation within create")]
     NoHttpClient,
 
-    /// Http requests failed
-    #[error("http request failed with {0}")]
-    RequestFailed(#[from] http::Error),
-
     /// The uri provided is invalid
     #[error("invalid uri")]
     InvalidUri(#[from] http::uri::InvalidUri),
 
     /// The IP/socket address provided is invalid
     #[error("invalid address")]
     InvalidAddress(#[from] AddrParseError),
-
-    /// Other errors
-    #[error("export error: {0}")]
-    Other(String),
 }
 
-impl ExportError for Error {
-    fn exporter_name(&self) -> &'static str {
-        "zipkin"
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::exporter::env::ENV_ENDPOINT;
+
+    #[test]
+    fn test_priority_of_code_based_config_over_envs_for_endpoint() {
+        temp_env::with_vars([(ENV_ENDPOINT, Some("http://127.0.0.1:1234"))], || {
+            let builder =
+                ZipkinExporterBuilder::default().with_collector_endpoint("http://127.0.0.1:2345");
+            assert_eq!(builder.collector_endpoint, "http://127.0.0.1:2345");
+        });
+    }
+
+    #[test]
+    fn test_use_default_when_others_missing_for_endpoint() {
+        temp_env::with_vars([(ENV_ENDPOINT, None::<&str>)], || {
+            let builder = ZipkinExporterBuilder::default();
+            assert_eq!(
+                builder.collector_endpoint,
+                "http://127.0.0.1:9411/api/v2/spans"
+            );
+        });
     }
 }

opentelemetry-zipkin/src/lib.rs

@@ -24,9 +24,9 @@
 //! use opentelemetry::global;
 //! use opentelemetry::trace::Tracer;
 //! use opentelemetry_sdk::{trace::{SdkTracerProvider, TraceError}, Resource};
-//! use opentelemetry_zipkin::ZipkinExporter;
+//! use opentelemetry_zipkin::{ExporterBuildError,ZipkinExporter};
 //!
-//! fn main() -> Result<(), TraceError> {
+//! fn main() -> Result<(), ExporterBuildError> {
 //!     global::set_text_map_propagator(opentelemetry_zipkin::Propagator::new());
 //!
 //!     let exporter = ZipkinExporter::builder()
@@ -68,9 +68,9 @@
 //!     },
 //!     Resource,
 //! };
-//! use opentelemetry_zipkin::ZipkinExporter;
+//! use opentelemetry_zipkin::{ExporterBuildError,ZipkinExporter};
 //!
-//! fn main() -> Result<(), opentelemetry_sdk::trace::TraceError> {
+//! fn main() -> Result<(), ExporterBuildError> {
 //!     let exporter = ZipkinExporter::builder()
 //!         .build()?;
 //!
@@ -116,7 +116,7 @@
 //! use opentelemetry::{global, InstrumentationScope, KeyValue, trace::Tracer};
 //! use opentelemetry_sdk::{trace::{self, RandomIdGenerator, Sampler, TraceError}, Resource};
 //! use opentelemetry_http::{HttpClient, HttpError};
-//! use opentelemetry_zipkin::{Error as ZipkinError, ZipkinExporter};
+//! use opentelemetry_zipkin::{ExporterBuildError, ZipkinExporter};
 //! use async_trait::async_trait;
 //! use bytes::Bytes;
 //! use futures_util::io::AsyncReadExt as _;
@@ -157,7 +157,7 @@
 //!     }
 //! }
 //!
-//! fn init_traces() -> Result<trace::SdkTracerProvider, TraceError> {
+//! fn init_traces() -> Result<trace::SdkTracerProvider, ExporterBuildError> {
 //!     let exporter = ZipkinExporter::builder()
 //!         .with_http_client(
 //!             HyperClient(
@@ -168,7 +168,7 @@
 //!         .with_service_address(
 //!             "127.0.0.1:8080"
 //!                 .parse()
-//!                 .map_err::<ZipkinError, _>(Into::into)?
+//!                 .map_err::<ExporterBuildError, _>(Into::into)?
 //!         )
 //!         .with_collector_endpoint("http://localhost:9411/api/v2/spans")
 //!         .build()?;
@@ -257,5 +257,5 @@ extern crate typed_builder;
 mod exporter;
 mod propagator;
 
-pub use exporter::{Error, ZipkinExporter, ZipkinExporterBuilder};
+pub use exporter::{ExporterBuildError, ZipkinExporter, ZipkinExporterBuilder};
 pub use propagator::{B3Encoding, Propagator};

opentelemetry/Cargo.toml

@@ -43,6 +43,8 @@ internal-logs = ["tracing"]
 opentelemetry_sdk = { path = "../opentelemetry-sdk", features = ["spec_unstable_logs_enabled"]} # for documentation tests
 criterion = { workspace = true }
 rand = { workspace = true, features = ["os_rng", "thread_rng"] }
+tokio = { version = "1.0", features = ["full"] }
+futures = "0.3"
 
 [[bench]]
 name = "metrics"