refactor send_to_logfire setting to match Python, start adding docs (#9)

* refactor `send_to_logfire` setting to match Python, start adding docs

* lint fixes

Author: davidhewitt

README.md

@@ -13,7 +13,7 @@
 >
 > This is an initial release of the Logfire Rust SDK. We've been using it internally to build Logfire for some time, and it is serving us well. As we're using it ourselves in production, we figured it's ready for everyone else also using Logfire.
 >
-> We are continually iterating to make this SDK better. We'd love your feedback on all aspects of the SDK and are keen to make the design as idiomatic and performant as possible.
+> We are continually iterating to make this SDK better. We'd love your feedback on all aspects of the SDK and are keen to make the design as idiomatic and performant as possible. There are also many features currently supported by the Python SDK which are not yet supported by this SDK; please open issues to help us prioritize these to close this gap.
 >
 > In particular, the current coupling to `tracing` is an open design point. By building on top of tracing we get widest compatibility and a relatively simple SDK, however to make Logfire-specific adjustments we might prefer in future to move `tracing` to be an optional integration.
 

examples/basic.rs

@@ -1,3 +1,5 @@
+//! A basic example of using Logfire to instrument Rust code.
+
 use std::sync::LazyLock;
 
 use opentelemetry::{KeyValue, metrics::Counter};
@@ -12,7 +14,6 @@ static BASIC_COUNTER: LazyLock<Counter<u64>> = LazyLock::new(|| {
 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()?;
 

src/bridges/log.rs

@@ -95,7 +95,9 @@ mod tests {
                     .line(Some(42))
                     .build();
 
-                let _ = crate::configure().send_to_logfire(false).finish();
+                let _ = crate::configure()
+                    .send_to_logfire(crate::SendToLogfire::No)
+                    .finish();
                 crate::span!("root span",).in_scope(|| logger.log(&record));
             },
         );

src/config.rs

@@ -0,0 +1,93 @@
+use std::{fmt::Display, str::FromStr};
+
+use tracing::Level;
+
+use crate::ConfigureError;
+
+/// Whether to send logs to Logfire.
+#[derive(Default, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SendToLogfire {
+    #[default]
+    Yes,
+    No,
+    IfTokenPresent,
+}
+
+impl Display for SendToLogfire {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            SendToLogfire::Yes => write!(f, "yes"),
+            SendToLogfire::No => write!(f, "no"),
+            SendToLogfire::IfTokenPresent => write!(f, "if-token-present"),
+        }
+    }
+}
+
+impl FromStr for SendToLogfire {
+    type Err = ConfigureError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "yes" => Ok(SendToLogfire::Yes),
+            "no" => Ok(SendToLogfire::No),
+            "if-token-present" => Ok(SendToLogfire::IfTokenPresent),
+            _ => Err(ConfigureError::InvalidConfigurationValue {
+                parameter: "LOGFIRE_SEND_TO_LOGFIRE",
+                value: s.to_owned(),
+            }),
+        }
+    }
+}
+
+/// Options for controlling console output.
+#[expect(clippy::struct_excessive_bools)] // Config options, bools make sense here.
+pub struct ConsoleOptions {
+    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,
+}
+
+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,
+        }
+    }
+}
+
+/// Whether to show colors in the console.
+#[derive(Default)]
+pub enum ConsoleColors {
+    #[default]
+    Auto,
+    Always,
+    Never,
+}
+
+/// Style for rendering spans in the console.
+#[derive(Default)]
+pub enum SpanStyle {
+    Simple,
+    Indented,
+    #[default]
+    ShowParents,
+    HideChildren,
+}

src/internal/exporters/remove_pending.rs

@@ -52,6 +52,7 @@ impl<Inner: SpanExporter> SpanExporter for RemovePendingSpansExporter<Inner> {
 mod tests {
     use std::time::Duration;
 
+    use crate::config::SendToLogfire;
     use crate::set_local_logfire;
     use crate::tests::DeterministicExporter;
     use crate::tests::DeterministicIdGenerator;
@@ -87,7 +88,7 @@ mod tests {
 
         let mut config = crate::configure();
         config
-            .send_to_logfire(false)
+            .send_to_logfire(SendToLogfire::No)
             .install_panic_handler()
             .with_tracer_provider(provider)
             .with_defalt_level_filter(LevelFilter::TRACE);