add with_console_options config, deprecate console_mode (#33)

Author: davidhewitt

README.md

@@ -40,8 +40,6 @@ Here's a simple manual tracing (aka logging) example:
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let shutdown_handler = logfire::configure()
         .install_panic_handler()
-        .send_to_logfire(true)
-        .console_mode(logfire::ConsoleMode::Fallback)
         .finish()?;
 
     logfire::info!("Hello, {name}!", name = "world");

examples/basic.rs

@@ -12,10 +12,7 @@ static BASIC_COUNTER: LazyLock<Counter<u64>> = LazyLock::new(|| {
 });
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let shutdown_handler = logfire::configure()
-        .install_panic_handler()
-        .console_mode(logfire::ConsoleMode::Fallback)
-        .finish()?;
+    let shutdown_handler = logfire::configure().install_panic_handler().finish()?;
 
     logfire::info!("Hello, world!");
 

src/bridges/tracing.rs

@@ -1383,7 +1383,7 @@ mod tests {
         let handler = crate::configure()
             .local()
             .send_to_logfire(false)
-            .console_options(console_options.clone())
+            .with_console(Some(console_options.clone()))
             .install_panic_handler()
             .with_default_level_filter(LevelFilter::TRACE)
             .finish()

src/config.rs

@@ -12,7 +12,6 @@ use opentelemetry_sdk::{
     metrics::reader::MetricReader,
     trace::{IdGenerator, SpanProcessor},
 };
-use tracing::Level;
 
 use crate::ConfigureError;
 
@@ -65,44 +64,55 @@ impl From<bool> for SendToLogfire {
 }
 
 /// Options for controlling console output.
-#[expect(clippy::struct_excessive_bools)] // Config options, bools make sense here.
 #[derive(Debug, Clone)]
 pub struct ConsoleOptions {
-    /// Whether to show colors in the console.
-    pub colors: ConsoleColors,
-    /// How spans are shown in the console.
-    pub span_style: SpanStyle,
-    /// Whether to include timestamps in the console output.
-    pub include_timestamps: bool,
-    /// Whether to include tags in the console output.
-    pub include_tags: bool,
-    /// Whether to show verbose output.
-    ///
-    /// It includes the filename, log level, and line number.
-    pub verbose: bool,
-    /// The minimum log level to show in the console.
-    pub min_log_level: Level,
-    /// Whether to print the URL of the Logfire project after initialization.
-    pub show_project_link: bool,
     /// Where to send output
-    pub target: Target,
+    pub(crate) target: Target,
+    // TODO: support the below configuration options (inherited from Python SDK)
+
+    // /// Whether to show colors in the console.
+    // colors: ConsoleColors,
+    // /// How spans are shown in the console.
+    // span_style: SpanStyle,
+    // /// Whether to include timestamps in the console output.
+    // include_timestamps: bool,
+    // /// Whether to include tags in the console output.
+    // include_tags: bool,
+    // /// Whether to show verbose output.
+    // ///
+    // /// It includes the filename, log level, and line number.
+    // verbose: bool,
+    // /// The minimum log level to show in the console.
+    // min_log_level: Level,
+    // /// Whether to print the URL of the Logfire project after initialization.
+    // show_project_link: bool,
 }
 
+#[expect(clippy::derivable_impls)] // When the other options are implemented, we will need this.
 impl Default for ConsoleOptions {
     fn default() -> Self {
         ConsoleOptions {
-            colors: ConsoleColors::default(),
-            span_style: SpanStyle::default(),
-            include_timestamps: true,
-            include_tags: true,
-            verbose: false,
-            min_log_level: Level::INFO,
-            show_project_link: true,
+            // colors: ConsoleColors::default(),
+            // span_style: SpanStyle::default(),
+            // include_timestamps: true,
+            // include_tags: true,
+            // verbose: false,
+            // min_log_level: Level::INFO,
+            // show_project_link: true,
             target: Target::default(),
         }
     }
 }
 
+impl ConsoleOptions {
+    /// Set the target for console output.
+    #[must_use]
+    pub fn with_target(mut self, target: Target) -> Self {
+        self.target = target;
+        self
+    }
+}
+
 /// Whether to show colors in the console.
 #[derive(Default, Debug, Clone, Copy)]
 pub enum ConsoleColors {

src/internal/exporters/console.rs

@@ -347,15 +347,12 @@ mod tests {
     fn test_print_to_console() {
         let output = Arc::new(Mutex::new(Vec::new()));
 
-        let console_options = ConsoleOptions {
-            target: Target::Pipe(output.clone()),
-            ..ConsoleOptions::default()
-        };
+        let console_options = ConsoleOptions::default().with_target(Target::Pipe(output.clone()));
 
         let handler = crate::configure()
             .local()
             .send_to_logfire(false)
-            .console_options(console_options)
+            .with_console(Some(console_options))
             .install_panic_handler()
             .with_default_level_filter(LevelFilter::TRACE)
             .finish()
@@ -387,7 +384,7 @@ mod tests {
         1970-01-01T00:00:00.000002Z DEBUG logfire::internal::exporters::console::tests debug span
         1970-01-01T00:00:00.000003Z DEBUG logfire::internal::exporters::console::tests debug span with explicit parent
         1970-01-01T00:00:00.000004Z  INFO logfire::internal::exporters::console::tests hello world log
-        [2m1970-01-01T00:00:00.000005Z[0m[31m ERROR[0m [2;3mlogfire[0m [1mpanic: oh no![0m [3mlocation[0m=src/internal/exporters/console.rs:373:17, [3mbacktrace[0m=disabled backtrace
+        [2m1970-01-01T00:00:00.000005Z[0m[31m ERROR[0m [2;3mlogfire[0m [1mpanic: oh no![0m [3mlocation[0m=src/internal/exporters/console.rs:370:17, [3mbacktrace[0m=disabled backtrace
         "#);
     }
 }

src/lib.rs

@@ -100,7 +100,7 @@ use std::cell::RefCell;
 use std::collections::HashMap;
 use std::panic::PanicHookInfo;
 use std::sync::{Arc, Once};
-use std::{backtrace::Backtrace, env::VarError, str::FromStr, sync::OnceLock, time::Duration};
+use std::{backtrace::Backtrace, env::VarError, sync::OnceLock, time::Duration};
 
 use bridges::tracing::LogfireTracingPendingSpanNotSentLayer;
 use opentelemetry::trace::TracerProvider;
@@ -190,30 +190,39 @@ pub enum ConfigureError {
     Other(#[from] Box<dyn std::error::Error + Send + Sync>),
 }
 
-/// Whether to print to the console.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-#[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
-pub enum ConsoleMode {
-    /// Write to console if no logfire token
-    #[default]
-    Fallback,
-    /// Force write to console
-    Force,
-}
+#[expect(deprecated)]
+mod deprecated {
+    use std::str::FromStr;
+
+    /// Whether to print to the console.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+    #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+    #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
+    #[deprecated(since = "0.4.0", note = "use `ConsoleOptions` instead")]
+    pub enum ConsoleMode {
+        /// Write to console if no logfire token
+        #[default]
+        Fallback,
+        /// Force write to console
+        Force,
+    }
 
-impl FromStr for ConsoleMode {
-    type Err = String;
+    impl FromStr for ConsoleMode {
+        type Err = String;
 
-    fn from_str(s: &str) -> Result<Self, Self::Err> {
-        match s {
-            "fallback" => Ok(ConsoleMode::Fallback),
-            "force" => Ok(ConsoleMode::Force),
-            _ => Err(format!("invalid console mode: {s}")),
+        fn from_str(s: &str) -> Result<Self, Self::Err> {
+            match s {
+                "fallback" => Ok(ConsoleMode::Fallback),
+                "force" => Ok(ConsoleMode::Force),
+                _ => Err(format!("invalid console mode: {s}")),
+            }
         }
     }
 }
 
+#[expect(deprecated)]
+use deprecated::ConsoleMode;
+
 /// Main entry point to configure logfire.
 ///
 /// This should be called once at the start of the program.
@@ -241,7 +250,9 @@ pub fn configure() -> LogfireConfigBuilder {
         local: false,
         send_to_logfire: None,
         token: None,
-        console_options: None,
+        console_options: Some(ConsoleOptions::default()),
+        #[expect(deprecated)]
+        console_mode: ConsoleMode::Force,
         additional_span_processors: Vec::new(),
         advanced: None,
         metrics: None,
@@ -260,6 +271,10 @@ pub struct LogfireConfigBuilder {
     // service_version: Option<String>,
     // environment: Option<String>,
     console_options: Option<ConsoleOptions>,
+    /// Deprecated setting, `Force` implies use `console_options`, `Fallback` will filter
+    /// them out if `send_to_logfire` is false.
+    #[expect(deprecated)]
+    console_mode: ConsoleMode,
 
     // config_dir: Option<PathBuf>,
     // data_dir: Option<Path>,
@@ -323,6 +338,8 @@ impl LogfireConfigBuilder {
 
     /// Whether to log to the console.
     #[must_use]
+    #[deprecated(note = "use `console_options()` instead")]
+    #[expect(deprecated)]
     pub fn console_mode(mut self, console_mode: ConsoleMode) -> Self {
         // FIXME: remove this API and make it match Python, see `console_options()` below
         match console_mode {
@@ -334,10 +351,12 @@ impl LogfireConfigBuilder {
         self
     }
 
-    /// Set the options for logging to console.
-    #[cfg(test)] // FIXME: not all options exposed actually work yet, so not public
-    pub fn console_options(mut self, console_options: ConsoleOptions) -> Self {
-        self.console_options = Some(console_options);
+    /// Sets console options. Set to `None` to disable console logging.
+    ///
+    /// If not set, will use `ConsoleOptions::default()`.
+    #[must_use]
+    pub fn with_console(mut self, console_options: Option<ConsoleOptions>) -> Self {
+        self.console_options = console_options;
         self
     }
 
@@ -495,15 +514,15 @@ impl LogfireConfigBuilder {
             );
         }
 
-        // TODO make this behaviour closer to Python
-        let mut console_options = self.console_options;
-        if console_options.is_none() && !send_to_logfire {
-            // FIXME: in Python the console and logfire settings are independent, we should not have
-            // "fallback" like this.
-            console_options = Some(ConsoleOptions::default());
-        }
-
-        let console_writer = console_options.map(ConsoleWriter::new).map(Arc::new);
+        let console_writer = self
+            .console_options
+            // NB deprecated behaviour: if set to fallback and sending to logfire, disable console
+            .filter(
+                #[expect(deprecated)]
+                |_| !(self.console_mode == ConsoleMode::Fallback && send_to_logfire),
+            )
+            .map(ConsoleWriter::new)
+            .map(Arc::new);
 
         if let Some(console_writer) = console_writer.clone() {
             tracer_provider_builder = tracer_provider_builder.with_span_processor(

tests/test_basic_exports.rs

@@ -1032,7 +1032,7 @@ fn test_basic_span() {
                         "code.lineno",
                     ),
                     value: I64(
-                        647,
+                        666,
                     ),
                 },
                 KeyValue {