From 7340cf0c3aecb1efe6abbacb150e0e146a3f49d5 Mon Sep 17 00:00:00 2001
From: Rhys Murray <contact@rhysmurray.me>
Date: Sat, 3 May 2025 13:43:10 +1000
Subject: [PATCH] feat: add logging to file via configuration

---
 docs/configuration.md         | 33 ++++++++++++++++++++++++++++++++-
 lib/ruby_llm.rb               |  4 ++--
 lib/ruby_llm/configuration.rb |  9 ++++++++-
 3 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 63b050f9c..f1b0dcc8c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -27,6 +27,7 @@ After reading this guide, you will know:
 *   How to customize connection timeouts and retries.
 *   How to connect to custom endpoints (like Azure OpenAI).
 *   How to use temporary, scoped configurations with `RubyLLM.context`.
+*   How to configure the logging location.
 
 ## Global Configuration (`RubyLLM.configure`)
 
@@ -75,6 +76,10 @@ RubyLLM.configure do |config|
   config.retry_interval = 0.1 # Initial delay in seconds (default: 0.1)
   config.retry_backoff_factor = 2 # Multiplier for subsequent retries (default: 2)
   config.retry_interval_randomness = 0.5 # Jitter factor (default: 0.5)
+
+  # --- Logging Settings ---
+  config.log_file = '/logs/ruby_llm.log'
+  config.level = :debug # debug level can also be set to debug by setting RUBYLLM_DEBUG envar to true
 end
 ```
 
@@ -134,6 +139,31 @@ Fine-tune how RubyLLM handles HTTP connections and retries.
 
 Adjust these based on network conditions and provider reliability.
 
+## Logging Settings
+
+RubyLLM provides flexible logging configuration to help you monitor and debug API interactions. You can configure both the log file location and the logging level.
+
+```ruby
+RubyLLM.configure do |config|
+  # --- Logging Settings ---
+  config.log_file = '/logs/ruby_llm.log'  # Path to log file (default: nil, logs to STDOUT)
+  config.level = :debug  # Log level (:debug, :info, :warn)
+end
+```
+
+### Log File Configuration
+
+* `config.log_file`: Specifies the path where logs should be written. If not set, logs will be written to STDOUT.
+* The log file will be created if it doesn't exist, and logs will be appended to it.
+
+### Log Levels
+
+* `:debug`: Most verbose level, includes detailed request/response information as provided by the faraday client
+* `:info`: General operational information
+* `:warn`: Warning messages for non-critical issues that may need attention
+
+You can also set the debug level by setting the `RUBYLLM_DEBUG` environment variable to `true`.
+
 ## Scoped Configuration with Contexts
 {: .d-inline-block }
 
@@ -178,4 +208,5 @@ default_response = default_chat.ask("Query using global production settings...")
 *   **Isolation:** Modifying configuration within a context block does **not** affect the global `RubyLLM.config`.
 *   **Thread Safety:** Each context is independent, making them safe for use across different threads.
 
-Contexts provide a clean and safe mechanism for managing diverse configuration needs within a single application.
\ No newline at end of file
+Contexts provide a clean and safe mechanism for managing diverse configuration needs within a single application.
+
diff --git a/lib/ruby_llm.rb b/lib/ruby_llm.rb
index 6bfdf552a..b83fe3d76 100644
--- a/lib/ruby_llm.rb
+++ b/lib/ruby_llm.rb
@@ -67,9 +67,9 @@ def config
 
     def logger
       @logger ||= Logger.new(
-        $stdout,
+        config.log_file,
         progname: 'RubyLLM',
-        level: ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
+        level: config.log_level
       )
     end
   end
diff --git a/lib/ruby_llm/configuration.rb b/lib/ruby_llm/configuration.rb
index 7327bc831..30c59861a 100644
--- a/lib/ruby_llm/configuration.rb
+++ b/lib/ruby_llm/configuration.rb
@@ -31,7 +31,10 @@ class Configuration
                   :max_retries,
                   :retry_interval,
                   :retry_backoff_factor,
-                  :retry_interval_randomness
+                  :retry_interval_randomness,
+                  # Logging configuration
+                  :log_file,
+                  :log_level
 
     def initialize
       # Connection configuration
@@ -45,6 +48,10 @@ def initialize
       @default_model = 'gpt-4.1-nano'
       @default_embedding_model = 'text-embedding-3-small'
       @default_image_model = 'dall-e-3'
+
+      # Logging configuration
+      @log_file = $stdout
+      @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
     end
 
     def inspect # rubocop:disable Metrics/MethodLength