feat(tracing): output logs to file (#377)

Author: kariy

Cargo.lock

@@ -212,6 +212,7 @@ syn = { version = "2.0", default-features = false }
 # tracing/logging
 log = "0.4.21"
 tracing = { version = "0.1.38", features = [ "log" ], default-features = false }
+tracing-appender = "0.2"
 tracing-log = "0.1.3"
 tracing-opentelemetry = "0.31.0"
 tracing-subscriber = "0.3.16"

Cargo.toml

@@ -133,9 +133,17 @@ pub struct SequencerNodeArgs {
 
 impl SequencerNodeArgs {
     pub async fn execute(&self) -> Result<()> {
-        // Initialize logging with tracer
-        let tracer_config = self.tracer_config();
-        katana_tracing::init(self.logging.log_format, tracer_config).await?;
+        let logging = katana_tracing::LoggingConfig {
+            stdout_format: self.logging.stdout.stdout_format,
+            stdout_color: self.logging.stdout.color,
+            file_enabled: self.logging.file.enabled,
+            file_format: self.logging.file.file_format,
+            file_directory: self.logging.file.directory.clone(),
+            file_max_files: self.logging.file.max_files,
+        };
+
+        katana_tracing::init(logging, self.tracer_config()).await?;
+
         self.start_node().await
     }
 

crates/cli/src/args.rs

@@ -61,9 +61,17 @@ pub struct FullNodeArgs {
 
 impl FullNodeArgs {
     pub async fn execute(&self) -> Result<()> {
-        // Initialize logging with tracer
-        let tracer_config = self.tracer_config();
-        katana_tracing::init(self.logging.log_format, tracer_config).await?;
+        let logging = katana_tracing::LoggingConfig {
+            stdout_format: self.logging.stdout.stdout_format,
+            stdout_color: self.logging.stdout.color,
+            file_enabled: self.logging.file.enabled,
+            file_format: self.logging.file.file_format,
+            file_directory: self.logging.file.directory.clone(),
+            file_max_files: self.logging.file.max_files,
+        };
+
+        katana_tracing::init(logging, self.tracer_config()).await?;
+
         self.start_node().await
     }
 

crates/cli/src/full.rs

@@ -10,6 +10,7 @@
 #[cfg(feature = "server")]
 use std::net::IpAddr;
 use std::num::NonZeroU128;
+use std::path::PathBuf;
 
 use clap::Args;
 use katana_genesis::Genesis;
@@ -30,7 +31,7 @@ use katana_primitives::block::{BlockHashOrNumber, GasPrice};
 use katana_primitives::chain::ChainId;
 #[cfg(feature = "server")]
 use katana_rpc_server::cors::HeaderValue;
-use katana_tracing::{gcloud, otlp, LogFormat, TracerConfig};
+use katana_tracing::{default_log_file_directory, gcloud, otlp, LogColor, LogFormat, TracerConfig};
 use serde::{Deserialize, Serialize};
 use serde_utils::serialize_opt_as_hex;
 use url::Url;
@@ -41,6 +42,7 @@ use crate::utils::{parse_block_hash_or_number, parse_genesis};
 
 const DEFAULT_DEV_SEED: &str = "0";
 const DEFAULT_DEV_ACCOUNTS: u16 = 10;
+const DEFAULT_LOG_FILE_MAX_FILES: usize = 7;
 
 #[cfg(feature = "server")]
 #[derive(Debug, Args, Clone, Serialize, Deserialize, PartialEq)]
@@ -433,11 +435,59 @@ pub struct ForkingOptions {
 #[derive(Debug, Args, Clone, Serialize, Deserialize, Default, PartialEq)]
 #[command(next_help_heading = "Logging options")]
 pub struct LoggingOptions {
-    /// Log format to use
-    #[arg(long = "log.format", value_name = "FORMAT")]
+    #[command(flatten)]
+    pub stdout: StdoutLoggingOptions,
+
+    #[command(flatten)]
+    pub file: FileLoggingOptions,
+}
+
+#[derive(Debug, Args, Clone, Serialize, Deserialize, Default, PartialEq)]
+pub struct StdoutLoggingOptions {
+    #[arg(long = "log.stdout.format", value_name = "FORMAT")]
+    #[arg(default_value_t = LogFormat::Full)]
+    pub stdout_format: LogFormat,
+
+    /// Sets whether or not the formatter emits ANSI terminal escape codes for colors and other
+    /// text formatting
+    ///
+    /// Possible values:
+    /// - always: Colors on
+    /// - auto:   Auto-detect
+    /// - never:  Colors off
+    #[arg(long = "color", value_name = "COLOR")]
+    #[arg(default_value_t = LogColor::Always)]
+    pub color: LogColor,
+}
+
+#[derive(Debug, Args, Clone, Serialize, Deserialize, Default, PartialEq)]
+pub struct FileLoggingOptions {
+    /// Enable writing logs to files.
+    #[arg(long = "log.file")]
+    #[serde(default)]
+    pub enabled: bool,
+
+    #[arg(requires = "enabled")]
+    #[arg(long = "log.file.format", value_name = "FORMAT")]
     #[arg(default_value_t = LogFormat::Full)]
-    pub log_format: LogFormat,
+    pub file_format: LogFormat,
+
+    /// The path to put log files in
+    #[arg(requires = "enabled")]
+    #[arg(long = "log.file.directory", value_name = "PATH")]
+    #[arg(default_value_os_t = default_log_file_directory())]
+    #[serde(default = "default_log_file_directory")]
+    pub directory: PathBuf,
+
+    /// Maximum number of daily log files to keep.
+    ///
+    /// If `0` is supplied, no files are deleted (unlimited retention).
+    #[arg(requires = "enabled")]
+    #[arg(long = "log.file.max-files", value_name = "COUNT")]
+    #[arg(default_value_t = DEFAULT_LOG_FILE_MAX_FILES)]
+    pub max_files: usize,
 }
+
 #[derive(Debug, Args, Default, Clone, Serialize, Deserialize, PartialEq)]
 #[command(next_help_heading = "Gas Price Oracle Options")]
 pub struct GasPriceOracleOptions {

crates/cli/src/options.rs

@@ -56,7 +56,7 @@ pub fn print_intro(args: &SequencerNodeArgs, chain: &ChainSpec) {
     let account_class_hash = accounts.peek().map(|e| e.1.class_hash());
     let seed = &args.development.seed;
 
-    if args.logging.log_format == LogFormat::Json {
+    if args.logging.stdout.stdout_format == LogFormat::Json {
         info!(
             target: LOG_TARGET,
             "{}",

crates/cli/src/utils.rs

@@ -510,7 +510,7 @@ impl Katana {
         }
 
         if self.json_log {
-            cmd.args(["--log.format", "json"]);
+            cmd.args(["--log.stdout.format", "json"]);
         }
 
         if let Some(fork_block_number) = self.fork_block_number {

crates/node-bindings/src/lib.rs

@@ -9,7 +9,9 @@ version.workspace = true
 clap.workspace = true
 serde.workspace = true
 thiserror.workspace = true
+dirs = "6.0.0"
 tracing.workspace = true
+tracing-appender.workspace = true
 tracing-log.workspace = true
 tracing-subscriber = { workspace = true, features = [ "chrono", "env-filter", "json", "time", "tracing-log" ] }
 

crates/tracing/Cargo.toml

@@ -4,6 +4,42 @@ use serde::{Deserialize, Serialize};
 use tracing_subscriber::fmt::format::Writer;
 use tracing_subscriber::fmt::time::{self};
 
+/// Controls when ANSI escape codes are emitted in log output.
+#[derive(Debug, Copy, Clone, PartialEq, Deserialize, Serialize, Default, Eq)]
+pub enum LogColor {
+    /// Colors on.
+    #[default]
+    Always,
+    /// Auto-detect.
+    Auto,
+    /// Colors off.
+    Never,
+}
+
+impl Display for LogColor {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Always => write!(f, "always"),
+            Self::Auto => write!(f, "auto"),
+            Self::Never => write!(f, "never"),
+        }
+    }
+}
+
+impl clap::ValueEnum for LogColor {
+    fn value_variants<'a>() -> &'a [Self] {
+        &[Self::Always, Self::Auto, Self::Never]
+    }
+
+    fn to_possible_value(&self) -> Option<clap::builder::PossibleValue> {
+        match self {
+            Self::Always => Some(clap::builder::PossibleValue::new("always")),
+            Self::Auto => Some(clap::builder::PossibleValue::new("auto")),
+            Self::Never => Some(clap::builder::PossibleValue::new("never")),
+        }
+    }
+}
+
 /// Format for logging output.
 #[derive(Debug, Copy, Clone, PartialEq, Deserialize, Serialize, Default, Eq)]
 pub enum LogFormat {