Add support for logging to file via configuration

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.
+Contexts provide a clean and safe mechanism for managing diverse configuration needs within a single application.
+

lib/ruby_llm.rb

@@ -68,9 +68,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

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