Use a builder pattern for loggers and tracers

opentelemetry-appender-log/src/lib.rs

@@ -49,12 +49,10 @@ where
 {
     pub fn new(provider: &P) -> Self {
         OpenTelemetryLogBridge {
-            logger: provider.versioned_logger(
-                "opentelemetry-log-appender",
-                Some(Cow::Borrowed(env!("CARGO_PKG_VERSION"))),
-                None,
-                None,
-            ),
+            logger: provider
+                .logger_builder("opentelemetry-log-appender")
+                .with_version(Cow::Borrowed(env!("CARGO_PKG_VERSION")))
+                .build(),
             _phantom: Default::default(),
         }
     }

opentelemetry-appender-tracing/src/layer.rs

@@ -138,12 +138,10 @@ where
 {
     pub fn new(provider: &P) -> Self {
         OpenTelemetryTracingBridge {
-            logger: provider.versioned_logger(
-                INSTRUMENTATION_LIBRARY_NAME,
-                Some(Cow::Borrowed(env!("CARGO_PKG_VERSION"))),
-                None,
-                None,
-            ),
+            logger: provider
+                .logger_builder(INSTRUMENTATION_LIBRARY_NAME)
+                .with_version(Cow::Borrowed(env!("CARGO_PKG_VERSION")))
+                .build(),
             _phantom: Default::default(),
         }
     }

opentelemetry-jaeger/src/exporter/config/mod.rs

@@ -85,13 +85,13 @@ fn build_config_and_process(
 pub(crate) fn install_tracer_provider_and_get_tracer(
     tracer_provider: TracerProvider,
 ) -> Result<Tracer, TraceError> {
-    let tracer = opentelemetry::trace::TracerProvider::versioned_tracer(
+    let tracer = opentelemetry::trace::TracerProvider::tracer_builder(
         &tracer_provider,
         "opentelemetry-jaeger",
-        Some(env!("CARGO_PKG_VERSION")),
-        Some(semcov::SCHEMA_URL),
-        None,
-    );
+    )
+    .with_version(env!("CARGO_PKG_VERSION"))
+    .with_schema_url(semcov::SCHEMA_URL)
+    .build();
     let _ = global::set_tracer_provider(tracer_provider);
     Ok(tracer)
 }

opentelemetry-otlp/src/logs.rs

@@ -183,12 +183,10 @@ fn build_simple_with_exporter(
         provider_builder = provider_builder.with_config(config);
     }
     let provider = provider_builder.build();
-    let logger = provider.versioned_logger(
-        Cow::Borrowed("opentelemetry-otlp"),
-        Some(Cow::Borrowed(env!("CARGO_PKG_VERSION"))),
-        None,
-        None,
-    );
+    let logger = provider
+        .logger_builder(Cow::Borrowed("opentelemetry-otlp"))
+        .with_version(Cow::Borrowed(env!("CARGO_PKG_VERSION")))
+        .build();
     let _ = global::set_logger_provider(provider);
     logger
 }
@@ -209,12 +207,10 @@ fn build_batch_with_exporter<R: RuntimeChannel>(
         provider_builder = provider_builder.with_config(config);
     }
     let provider = provider_builder.build();
-    let logger = provider.versioned_logger(
-        Cow::Borrowed("opentelemetry-otlp"),
-        Some(Cow::Borrowed(env!("CARGO_PKG_VERSION"))),
-        None,
-        None,
-    );
+    let logger = provider
+        .logger_builder(Cow::Borrowed("opentelemetry-otlp"))
+        .with_version(Cow::Borrowed(env!("CARGO_PKG_VERSION")))
+        .build();
     let _ = global::set_logger_provider(provider);
     logger
 }

opentelemetry-otlp/src/span.rs

@@ -140,12 +140,11 @@ fn build_simple_with_exporter(
         provider_builder = provider_builder.with_config(config);
     }
     let provider = provider_builder.build();
-    let tracer = provider.versioned_tracer(
-        "opentelemetry-otlp",
-        Some(env!("CARGO_PKG_VERSION")),
-        Some(SCHEMA_URL),
-        None,
-    );
+    let tracer = provider
+        .tracer_builder("opentelemetry-otlp")
+        .with_version(env!("CARGO_PKG_VERSION"))
+        .with_schema_url(SCHEMA_URL)
+        .build();
     let _ = global::set_tracer_provider(provider);
     tracer
 }
@@ -166,12 +165,11 @@ fn build_batch_with_exporter<R: RuntimeChannel>(
         provider_builder = provider_builder.with_config(config);
     }
     let provider = provider_builder.build();
-    let tracer = provider.versioned_tracer(
-        "opentelemetry-otlp",
-        Some(env!("CARGO_PKG_VERSION")),
-        Some(SCHEMA_URL),
-        None,
-    );
+    let tracer = provider
+        .tracer_builder("opentelemetry-otlp")
+        .with_version(env!("CARGO_PKG_VERSION"))
+        .with_schema_url(SCHEMA_URL)
+        .build();
     let _ = global::set_tracer_provider(provider);
     tracer
 }

opentelemetry-sdk/src/logs/log_emitter.rs

@@ -43,12 +43,19 @@ impl opentelemetry::logs::LoggerProvider for LoggerProvider {
             name
         };
 
-        self.library_logger(Arc::new(InstrumentationLibrary::new(
-            component_name,
-            version,
-            schema_url,
-            attributes,
-        )))
+        let mut builder = self.logger_builder(component_name);
+
+        if let Some(v) = version {
+            builder = builder.with_version(v);
+        }
+        if let Some(s) = schema_url {
+            builder = builder.with_schema_url(s);
+        }
+        if let Some(a) = attributes {
+            builder = builder.with_attributes(a);
+        }
+
+        builder.build()
     }
 
     fn library_logger(&self, library: Arc<InstrumentationLibrary>) -> Self::Logger {

opentelemetry-sdk/src/metrics/meter_provider.rs

@@ -125,7 +125,19 @@ impl MeterProvider for SdkMeterProvider {
             return Meter::new(Arc::new(NoopMeterCore::new()));
         }
 
-        let scope = Scope::new(name, version, schema_url, attributes);
+        let mut builder = Scope::builder(name);
+
+        if let Some(v) = version {
+            builder = builder.with_version(v);
+        }
+        if let Some(s) = schema_url {
+            builder = builder.with_schema_url(s);
+        }
+        if let Some(a) = attributes {
+            builder = builder.with_attributes(a);
+        }
+
+        let scope = builder.build();
 
         if let Ok(mut meters) = self.meters.lock() {
             let meter = meters

opentelemetry-sdk/src/trace/provider.rs

@@ -136,12 +136,19 @@ impl opentelemetry::trace::TracerProvider for TracerProvider {
             name
         };
 
-        self.library_tracer(Arc::new(InstrumentationLibrary::new(
-            component_name,
-            version,
-            schema_url,
-            attributes,
-        )))
+        let mut builder = self.tracer_builder(component_name);
+
+        if let Some(v) = version {
+            builder = builder.with_version(v);
+        }
+        if let Some(s) = schema_url {
+            builder = builder.with_schema_url(s);
+        }
+        if let Some(a) = attributes {
+            builder = builder.with_attributes(a);
+        }
+
+        builder.build()
     }
 
     fn library_tracer(&self, library: Arc<InstrumentationLibrary>) -> Self::Tracer {

opentelemetry-zipkin/src/exporter/mod.rs

@@ -151,13 +151,11 @@ impl ZipkinPipelineBuilder {
         let mut provider_builder = TracerProvider::builder().with_simple_exporter(exporter);
         provider_builder = provider_builder.with_config(config);
         let provider = provider_builder.build();
-        let tracer = opentelemetry::trace::TracerProvider::versioned_tracer(
-            &provider,
-            "opentelemetry-zipkin",
-            Some(env!("CARGO_PKG_VERSION")),
-            Some(semcov::SCHEMA_URL),
-            None,
-        );
+        let tracer =
+            opentelemetry::trace::TracerProvider::tracer_builder(&provider, "opentelemetry-zipkin")
+                .with_version(env!("CARGO_PKG_VERSION"))
+                .with_schema_url(semcov::SCHEMA_URL)
+                .build();
         let _ = global::set_tracer_provider(provider);
         Ok(tracer)
     }
@@ -170,13 +168,11 @@ impl ZipkinPipelineBuilder {
         let mut provider_builder = TracerProvider::builder().with_batch_exporter(exporter, runtime);
         provider_builder = provider_builder.with_config(config);
         let provider = provider_builder.build();
-        let tracer = opentelemetry::trace::TracerProvider::versioned_tracer(
-            &provider,
-            "opentelemetry-zipkin",
-            Some(env!("CARGO_PKG_VERSION")),
-            Some(semcov::SCHEMA_URL),
-            None,
-        );
+        let tracer =
+            opentelemetry::trace::TracerProvider::tracer_builder(&provider, "opentelemetry-zipkin")
+                .with_version(env!("CARGO_PKG_VERSION"))
+                .with_schema_url(semcov::SCHEMA_URL)
+                .build();
         let _ = global::set_tracer_provider(provider);
         Ok(tracer)
     }

opentelemetry/src/common.rs

@@ -449,12 +449,10 @@ pub struct InstrumentationLibrary {
     /// # Examples
     ///
     /// ```
-    /// let library = opentelemetry::InstrumentationLibrary::new(
-    ///     "my-crate",
-    ///     Some(env!("CARGO_PKG_VERSION")),
-    ///     Some("https://opentelemetry.io/schemas/1.17.0"),
-    ///     None,
-    /// );
+    /// let library = opentelemetry::InstrumentationLibrary::builder("my-crate").
+    ///     with_version(env!("CARGO_PKG_VERSION")).
+    ///     with_schema_url("https://opentelemetry.io/schemas/1.17.0").
+    ///     build();
     /// ```
     pub version: Option<Cow<'static, str>>,
 
@@ -487,7 +485,10 @@ impl hash::Hash for InstrumentationLibrary {
 }
 
 impl InstrumentationLibrary {
+    /// Deprecated, use [`InstrumentationLibrary::builder()`]
+    ///
     /// Create an new instrumentation library.
+    #[deprecated(since = "0.23.0", note = "Please use builder() instead")]
     pub fn new(
         name: impl Into<Cow<'static, str>>,
         version: Option<impl Into<Cow<'static, str>>>,
@@ -501,4 +502,92 @@ impl InstrumentationLibrary {
             attributes: attributes.unwrap_or_default(),
         }
     }
+
+    /// Create a new builder to create an [InstrumentationLibrary]
+    pub fn builder(name: impl Into<Cow<'static, str>>) -> InstrumentationLibraryBuilder {
+        InstrumentationLibraryBuilder {
+            name: name.into(),
+            version: None,
+            schema_url: None,
+            attributes: None,
+        }
+    }
+}
+
+/// Configuration options for [InstrumentationLibrary].
+///
+/// An instrumentation library is a library or crate providing instrumentation.
+/// It should be named to follow any naming conventions of the instrumented
+/// library (e.g. 'middleware' for a web framework).
+///
+/// Apart from the name, all other fields are optional.
+///
+/// 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)]
+pub struct InstrumentationLibraryBuilder {
+    name: Cow<'static, str>,
+
+    version: Option<Cow<'static, str>>,
+
+    schema_url: Option<Cow<'static, str>>,
+
+    attributes: Option<Vec<KeyValue>>,
+}
+
+impl InstrumentationLibraryBuilder {
+    /// Configure the version for the instrumentation library
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let library = opentelemetry::InstrumentationLibrary::builder("my-crate")
+    ///     .with_version("v0.1.0")
+    ///     .build();
+    /// ```
+    pub fn with_version(mut self, version: impl Into<Cow<'static, str>>) -> Self {
+        self.version = Some(version.into());
+        self
+    }
+
+    /// Configure the Schema URL for the instrumentation library
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let library = opentelemetry::InstrumentationLibrary::builder("my-crate")
+    ///     .with_schema_url("https://opentelemetry.io/schemas/1.17.0")
+    ///     .build();
+    /// ```
+    pub fn with_schema_url(mut self, schema_url: impl Into<Cow<'static, str>>) -> Self {
+        self.schema_url = Some(schema_url.into());
+        self
+    }
+
+    /// Configure the attributes for the instrumentation library
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use opentelemetry::KeyValue;
+    ///
+    /// let library = opentelemetry::InstrumentationLibrary::builder("my-crate")
+    ///     .with_attributes(vec![KeyValue::new("k", "v")])
+    ///     .build();
+    /// ```
+    pub fn with_attributes(mut self, attributes: impl Into<Vec<KeyValue>>) -> Self {
+        self.attributes = Some(attributes.into());
+        self
+    }
+
+    /// Create a new [InstrumentationLibrary] from this configuration
+    pub fn build(self) -> InstrumentationLibrary {
+        InstrumentationLibrary {
+            name: self.name,
+            version: self.version,
+            schema_url: self.schema_url,
+            attributes: self.attributes.unwrap_or_default(),
+        }
+    }
 }

opentelemetry/src/global/mod.rs

@@ -56,12 +56,10 @@
 //! pub fn my_traced_library_function() {
 //!     // End users of your library will configure their global tracer provider
 //!     // so you can use the global tracer without any setup
-//!     let tracer = global::tracer_provider().versioned_tracer(
-//!         "my-library-name",
-//!         Some(env!("CARGO_PKG_VERSION")),
-//!         Some("https://opentelemetry.io/schemas/1.17.0"),
-//!         None,
-//!     );
+//!     let tracer = global::tracer_provider().tracer_builder("my-library-name").
+//!         with_version(env!("CARGO_PKG_VERSION")).
+//!         with_schema_url("https://opentelemetry.io/schemas/1.17.0").
+//!         build();
 //!
 //!     tracer.in_span("doing_library_work", |cx| {
 //!         // Traced library logic here...

opentelemetry/src/lib.rs

@@ -222,7 +222,10 @@ mod common;
 #[doc(hidden)]
 pub mod testing;
 
-pub use common::{Array, ExportError, InstrumentationLibrary, Key, KeyValue, StringValue, Value};
+pub use common::{
+    Array, ExportError, InstrumentationLibrary, InstrumentationLibraryBuilder, Key, KeyValue,
+    StringValue, Value,
+};
 
 #[cfg(feature = "metrics")]
 #[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]