Initial implementation of the logging SDK spec

opentelemetry-api/Cargo.toml

@@ -29,3 +29,4 @@ default = ["trace"]
 trace = ["pin-project-lite"]
 metrics = ["fnv"]
 testing = ["trace"]
+logs = []

opentelemetry-api/src/common.rs

@@ -99,6 +99,16 @@ impl From<Arc<str>> for Key {
     }
 }
 
+impl From<Cow<'static, str>> for Key {
+    /// Convert a `Cow<'static, str>` to a `Key`
+    fn from(string: Cow<'static, str>) -> Self {
+        match string {
+            Cow::Borrowed(s) => Key(OtelString::Static(s)),
+            Cow::Owned(s) => Key(OtelString::Owned(s)),
+        }
+    }
+}
+
 impl fmt::Debug for Key {
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
         self.0.fmt(fmt)

opentelemetry-api/src/global/error_handler.rs

@@ -1,6 +1,8 @@
 use std::sync::PoisonError;
 use std::sync::RwLock;
 
+#[cfg(feature = "logs")]
+use crate::logs::LogError;
 #[cfg(feature = "metrics")]
 use crate::metrics::MetricsError;
 #[cfg(feature = "trace")]
@@ -23,6 +25,13 @@ pub enum Error {
     #[error(transparent)]
     /// An issue raised by the metrics module.
     Metric(#[from] MetricsError),
+
+    #[cfg(feature = "logs")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
+    #[error(transparent)]
+    /// Failed to export logs.
+    Log(#[from] LogError),
+
     #[error("{0}")]
     /// Other types of failures not covered by the variants above.
     Other(String),
@@ -49,6 +58,9 @@ pub fn handle_error<T: Into<Error>>(err: T) {
             #[cfg(feature = "trace")]
             #[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
             Error::Trace(err) => eprintln!("OpenTelemetry trace error occurred. {}", err),
+            #[cfg(feature = "logs")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
+            Error::Log(err) => eprintln!("OpenTelemetry log error occurred. {}", err),
             Error::Other(err_msg) => eprintln!("OpenTelemetry error occurred. {}", err_msg),
         },
     }

opentelemetry-api/src/global/logs.rs

@@ -0,0 +1,158 @@
+use std::{
+    borrow::Cow,
+    fmt, mem,
+    sync::{Arc, RwLock},
+};
+
+use once_cell::sync::Lazy;
+
+use crate::{
+    logs::{Logger, LoggerProvider, NoopLoggerProvider},
+    KeyValue,
+};
+
+/// Allows a specific [`LoggerProvider`] to be used generically, by mirroring
+/// the interface, and boxing the returned types.
+///
+/// [`LoggerProvider`]: crate::logs::LoggerProvider.
+pub trait ObjectSafeLoggerProvider {
+    /// Creates a versioned named [`Logger`] instance that is a trait object
+    /// through the underlying [`LoggerProvider`].
+    ///
+    /// [`Logger`]: crate::logs::Logger
+    /// [`LoggerProvider`]: crate::logs::LoggerProvider
+    fn versioned_logger_boxed(
+        &self,
+        name: Cow<'static, str>,
+        version: Option<Cow<'static, str>>,
+        schema_url: Option<Cow<'static, str>>,
+        attributes: Option<Vec<KeyValue>>,
+        include_trace_context: bool,
+    ) -> Box<dyn Logger + Send + Sync + 'static>;
+}
+
+impl<L, P> ObjectSafeLoggerProvider for P
+where
+    L: Logger + Send + Sync + 'static,
+    P: LoggerProvider<Logger = L>,
+{
+    fn versioned_logger_boxed(
+        &self,
+        name: Cow<'static, str>,
+        version: Option<Cow<'static, str>>,
+        schema_url: Option<Cow<'static, str>>,
+        attributes: Option<Vec<KeyValue>>,
+        include_trace_context: bool,
+    ) -> Box<dyn Logger + Send + Sync + 'static> {
+        Box::new(self.versioned_logger(
+            name,
+            version,
+            schema_url,
+            attributes,
+            include_trace_context,
+        ))
+    }
+}
+
+pub struct BoxedLogger(Box<dyn Logger + Send + Sync + 'static>);
+
+impl fmt::Debug for BoxedLogger {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("BoxedLogger")
+    }
+}
+
+impl Logger for BoxedLogger {
+    fn emit(&self, record: crate::logs::LogRecord) {
+        self.0.emit(record)
+    }
+}
+
+#[derive(Clone)]
+/// Represents the globally configured [`LoggerProvider`] instance.
+pub struct GlobalLoggerProvider {
+    provider: Arc<dyn ObjectSafeLoggerProvider + Send + Sync>,
+}
+
+impl fmt::Debug for GlobalLoggerProvider {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("GlobalLoggerProvider")
+    }
+}
+
+impl GlobalLoggerProvider {
+    fn new<
+        L: Logger + Send + Sync + 'static,
+        P: LoggerProvider<Logger = L> + Send + Sync + 'static,
+    >(
+        provider: P,
+    ) -> Self {
+        GlobalLoggerProvider {
+            provider: Arc::new(provider),
+        }
+    }
+}
+
+impl LoggerProvider for GlobalLoggerProvider {
+    type Logger = BoxedLogger;
+
+    fn versioned_logger(
+        &self,
+        name: impl Into<Cow<'static, str>>,
+        version: Option<Cow<'static, str>>,
+        schema_url: Option<Cow<'static, str>>,
+        attributes: Option<Vec<KeyValue>>,
+        include_trace_context: bool,
+    ) -> Self::Logger {
+        BoxedLogger(self.provider.versioned_logger_boxed(
+            name.into(),
+            version,
+            schema_url,
+            attributes,
+            include_trace_context,
+        ))
+    }
+}
+
+static GLOBAL_LOGGER_PROVIDER: Lazy<RwLock<GlobalLoggerProvider>> =
+    Lazy::new(|| RwLock::new(GlobalLoggerProvider::new(NoopLoggerProvider::new())));
+
+/// Returns an instance of the currently configured global [`LoggerProvider`]
+/// through [`GlobalLoggerProvider`].
+///
+/// [`LoggerProvider`]: crate::logs::LoggerProvider
+pub fn logger_provider() -> GlobalLoggerProvider {
+    GLOBAL_LOGGER_PROVIDER
+        .read()
+        .expect("GLOBAL_LOGGER_PROVIDER RwLock poisoned")
+        .clone()
+}
+
+/// Creates a named instance of [`Logger`] via the configured
+/// [`GlobalLoggerProvider`].
+///
+/// If `name` is an empty string, the provider will use a default name.
+///
+/// [`Logger`]: crate::logs::Logger
+pub fn logger(name: Cow<'static, str>) -> BoxedLogger {
+    logger_provider().logger(name)
+}
+
+/// Sets the given [`LoggerProvider`] instance as the current global provider,
+/// returning the [`LoggerProvider`] instance that was previously set as global
+/// provider.
+pub fn set_logger_provider<L, P>(new_provider: P) -> GlobalLoggerProvider
+where
+    L: Logger + Send + Sync + 'static,
+    P: LoggerProvider<Logger = L> + Send + Sync + 'static,
+{
+    let mut provider = GLOBAL_LOGGER_PROVIDER
+        .write()
+        .expect("GLOBAL_LOGGER_PROVIDER RwLock poisoned");
+    mem::replace(&mut *provider, GlobalLoggerProvider::new(new_provider))
+}
+
+/// Shut down the current global [`LoggerProvider`].
+pub fn shutdown_logger_provider() {
+    let _ = set_logger_provider(NoopLoggerProvider::new());
+}

opentelemetry-api/src/global/mod.rs

@@ -142,6 +142,8 @@
 //! [`set_meter_provider`]: crate::global::set_meter_provider
 
 mod error_handler;
+#[cfg(feature = "logs")]
+mod logs;
 #[cfg(feature = "metrics")]
 mod metrics;
 #[cfg(feature = "trace")]
@@ -150,6 +152,12 @@ mod propagation;
 mod trace;
 
 pub use error_handler::{handle_error, set_error_handler, Error};
+#[cfg(feature = "logs")]
+#[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
+pub use logs::{
+    logger, logger_provider, set_logger_provider, shutdown_logger_provider, GlobalLoggerProvider,
+    ObjectSafeLoggerProvider,
+};
 #[cfg(feature = "metrics")]
 #[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]
 pub use metrics::{

opentelemetry-api/src/lib.rs

@@ -67,6 +67,10 @@ pub mod propagation;
 #[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
 pub mod trace;
 
+#[cfg(feature = "logs")]
+#[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
+pub mod logs;
+
 #[doc(hidden)]
 #[cfg(any(feature = "metrics", feature = "trace"))]
 pub mod time {

opentelemetry-api/src/logs/logger.rs

@@ -0,0 +1,52 @@
+use std::borrow::Cow;
+
+use crate::{logs::LogRecord, KeyValue};
+
+/// The interface for emitting [`LogRecord`]s.
+pub trait Logger {
+    /// Emit a [`LogRecord`]. If this `Logger` was created with
+    /// `include_trace_context` set to `true`, the logger will set the record's
+    /// [`TraceContext`] to the active trace context, using the current thread's
+    /// [`Context`].
+    ///
+    /// [`Context`]: crate::Context
+    /// [`TraceContext`]: crate::logs::TraceContext
+    fn emit(&self, record: LogRecord);
+}
+
+/// Interfaces that can create [`Logger`] instances.
+pub trait LoggerProvider {
+    /// The [`Logger`] type that this provider will return.
+    type Logger: Logger;
+
+    /// Returns a new versioned logger with a given name.
+    ///
+    /// The `name` should be the application name or the name of the library
+    /// providing instrumentation. If the name is empty, then an
+    /// implementation-defined default name may be used instead.
+    ///
+    /// If `include_trace_context` is `true`, the newly created [`Logger`]
+    /// should set the [`TraceContext`] associated with a record to the
+    /// current thread's active trace context, using [`Context`].
+    ///
+    /// [`Context`]: crate::Context
+    /// [`TraceContext`]: crate::logs::TraceContext
+
+    fn versioned_logger(
+        &self,
+        name: impl Into<Cow<'static, str>>,
+        version: Option<Cow<'static, str>>,
+        schema_url: Option<Cow<'static, str>>,
+        attributes: Option<Vec<KeyValue>>,
+        include_trace_context: bool,
+    ) -> Self::Logger;
+
+    /// Returns a new logger with the given name.
+    ///
+    /// The `name` should be the application name or the name of the library
+    /// providing instrumentation. If the name is empty, then an
+    /// implementation-defined default name may be used instead.
+    fn logger(&self, name: impl Into<Cow<'static, str>>) -> Self::Logger {
+        self.versioned_logger(name, None, None, None, true)
+    }
+}

opentelemetry-api/src/logs/mod.rs

@@ -0,0 +1,72 @@
+//! # OpenTelemetry Logs API
+
+use crate::ExportError;
+use futures_channel::{mpsc::TrySendError, oneshot::Canceled};
+use std::time::Duration;
+use thiserror::Error;
+
+mod logger;
+mod noop;
+mod record;
+
+pub use logger::{Logger, LoggerProvider};
+pub use noop::NoopLoggerProvider;
+pub use record::{AnyValue, LogRecord, LogRecordBuilder, Severity, TraceContext};
+
+/// Describe the result of operations in log SDK.
+pub type LogResult<T> = Result<T, LogError>;
+
+#[derive(Error, Debug)]
+#[non_exhaustive]
+/// Errors returned by the log SDK.
+pub enum LogError {
+    /// Export failed with the error returned by the exporter.
+    #[error("Exporter {} encountered the following errors: {0}", .0.exporter_name())]
+    ExportFailed(Box<dyn ExportError>),
+
+    /// Export failed to finish after certain period and processor stopped the export.
+    #[error("Exporter timed out after {} seconds", .0.as_secs())]
+    ExportTimedOut(Duration),
+
+    /// Other errors propagated from log SDK that weren't covered above.
+    #[error(transparent)]
+    Other(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),
+}
+
+impl<T> From<T> for LogError
+where
+    T: ExportError,
+{
+    fn from(err: T) -> Self {
+        LogError::ExportFailed(Box::new(err))
+    }
+}
+
+impl<T> From<TrySendError<T>> for LogError {
+    fn from(err: TrySendError<T>) -> Self {
+        LogError::Other(Box::new(err.into_send_error()))
+    }
+}
+
+impl From<Canceled> for LogError {
+    fn from(err: Canceled) -> Self {
+        LogError::Other(Box::new(err))
+    }
+}
+
+impl From<String> for LogError {
+    fn from(err_msg: String) -> Self {
+        LogError::Other(Box::new(Custom(err_msg)))
+    }
+}
+
+impl From<&'static str> for LogError {
+    fn from(err_msg: &'static str) -> Self {
+        LogError::Other(Box::new(Custom(err_msg.into())))
+    }
+}
+
+/// Wrap type for string
+#[derive(Error, Debug)]
+#[error("{0}")]
+struct Custom(String);