philiprehberger-structured_logger 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ef7c59f106a991921ebecf414e00246f465120af2cc8d1abf17ebc9dafeb227
-  data.tar.gz: 6b803b7b323343ba481445416dabffeed056d6a79788ada1c797b752c88dcb87
+  metadata.gz: aa759b5a2e0251937f0ab9951c533f233ef8129a4b13c724995bf98699618374
+  data.tar.gz: 5908a03340aaf26b1b0a428d7756874f6fc6caabe14a137fad5fec8e7e3110a9
 SHA512:
-  metadata.gz: 7c14cb179e55002dc57fdaf65fb59dc8d570da2da2fb62205aed82bd49e916704409ab46f0350f690e57d02478591cb256ce49f7fb057655e9894ae8c842e257
-  data.tar.gz: caef71a9ca0b7d278d77eb2f0a31b7c0349af95905f143535d008a7f3e95f37315c393ca183f383844a05819c7be7c487d98b4c8cf44357b6e237e6ad00820cd
+  metadata.gz: dadadcbd9611ee77a72099b12a2441c83405fc1d2a11a74d841fa09b7ab29ee0201a7c9743130378809d7e1e7ad92c7c55244e35a36fabe1cbfba6c5e1c49e82
+  data.tar.gz: 14f5d6583b9713eac95fc8d1a564de17e78ee665789766fcc3662dd7154ec852d12616fae740ad3bea6ce50079e78757d7ebd43af5cdccbb3a2ba38144715fd4

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.0
+
+- Add multiple outputs (appenders) with per-output level filtering and formatters
+- Add `add_output` for adding output destinations at runtime
+- Add custom formatters: `:json` (default), `:text`, and any callable (proc/lambda)
+- Add `TextFormatter` for human-readable `[TIMESTAMP] LEVEL: message key=value` output
+- Add log sampling with configurable rates per level
+- Add `with_correlation_id` for injecting correlation/request IDs via Thread-local storage
+- Add buffered async output via background thread with backpressure support
+- Add `flush` and `close` methods for async writer lifecycle management
+
+## 0.2.1
+
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+- Add Development section to README
+- Add Requirements section to README
+
+## [0.2.0] - 2026-03-13
+- Add `level` getter to read the current log level
+- Add `with_context` for temporarily merging context during a block
+- Add `silence` for temporarily raising the log level during a block
+- Add `log_exception` for logging exception class, message, and backtrace
+
 ## [0.1.0] - 2026-03-10
 - Initial release
 - Structured JSON log output

data/README.md

@@ -1,6 +1,10 @@
 # Philiprehberger::StructuredLogger
 
-A zero-dependency Ruby gem for structured JSON logging with context merging, child loggers, level filtering, and pluggable outputs.
+A zero-dependency Ruby gem for structured JSON logging with context merging, child loggers, level filtering, multiple outputs, custom formatters, log sampling, correlation IDs, and async output.
+
+## Requirements
+
+- Ruby >= 3.1
 
 ## Installation
 
@@ -61,35 +65,198 @@ logger.warn("visible")   # written
 logger.error("visible")  # written
 ```
 
+Read the current level:
+
+```ruby
+logger.level  # => :debug
+```
+
 Change the level at runtime:
 
 ```ruby
 logger.level = :error
 ```
 
-### Custom Output
+### Temporary Context
+
+Use `with_context` to add context for the duration of a block:
+
+```ruby
+logger.with_context(request_id: "abc-123") do
+  logger.info("Processing request")
+  # => {"timestamp":"...","level":"info","message":"Processing request","request_id":"abc-123"}
+end
+# Context is restored after the block
+```
+
+### Silence
 
-Pass any IO-like object that responds to `puts`:
+Temporarily suppress log output by raising the minimum level:
 
 ```ruby
-file = File.open("app.log", "a")
-logger = Philiprehberger::StructuredLogger::Logger.new(output: file)
+logger.silence(:fatal) do
+  logger.info("suppressed")   # not written
+  logger.error("suppressed")  # not written
+end
+# Level is restored after the block
 ```
 
+### Exception Logging
+
+Log exceptions with class, message, and backtrace:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  logger.log_exception(e)
+  # => {"timestamp":"...","level":"error","message":"something broke","error_class":"RuntimeError","backtrace":[...]}
+end
+
+# Custom level and extra context:
+logger.log_exception(e, level: :fatal, user_id: 42)
+```
+
+### Multiple Outputs
+
+Log to multiple destinations simultaneously. Each output can have its own level filter and formatter:
+
+```ruby
+logger = Philiprehberger::StructuredLogger::Logger.new(
+  outputs: [$stdout, File.open("app.log", "a")]
+)
+
+# With per-output configuration:
+logger = Philiprehberger::StructuredLogger::Logger.new(outputs: [
+  { io: $stdout, formatter: :text },
+  { io: File.open("app.log", "a"), formatter: :json },
+  { io: $stderr, level: :error }
+])
+```
+
+Add outputs at runtime:
+
+```ruby
+logger.add_output($stderr, level: :error)
+logger.add_output(File.open("debug.log", "a"), formatter: :text)
+```
+
+The singular `output:` parameter still works for backwards compatibility:
+
+```ruby
+logger = Philiprehberger::StructuredLogger::Logger.new(output: $stdout)
+```
+
+### Custom Formatters
+
+Choose from built-in formatters or provide your own:
+
+```ruby
+# JSON formatter (default)
+logger = Philiprehberger::StructuredLogger::Logger.new(formatter: :json)
+
+# Text formatter — human-readable output
+logger = Philiprehberger::StructuredLogger::Logger.new(formatter: :text)
+logger.info("hello", user: "alice")
+# => [2026-03-10T12:00:00.000Z] INFO: hello user=alice
+
+# Custom proc formatter
+logger = Philiprehberger::StructuredLogger::Logger.new(
+  formatter: ->(level, message, context) { "#{level.upcase} #{message}" }
+)
+
+# Any callable object
+class MyFormatter
+  def call(level, message, context)
+    "#{level}|#{message}|#{context.to_json}"
+  end
+end
+
+logger = Philiprehberger::StructuredLogger::Logger.new(formatter: MyFormatter.new)
+```
+
+### Log Sampling
+
+Sample a percentage of logs per level to reduce volume:
+
+```ruby
+logger = Philiprehberger::StructuredLogger::Logger.new(
+  sampling: { debug: 0.1, info: 0.5 }
+)
+```
+
+- `1.0` means log everything (default for unspecified levels)
+- `0.5` means log approximately 50%
+- `0.0` means log nothing
+
+### Correlation ID
+
+Inject a correlation/request ID into all log entries within a block:
+
+```ruby
+logger.with_correlation_id("req-abc-123") do
+  logger.info("processing")
+  # => {"timestamp":"...","level":"info","message":"processing","correlation_id":"req-abc-123"}
+end
+
+# Auto-generate a UUID:
+logger.with_correlation_id do
+  logger.info("processing")
+  # => {"timestamp":"...","level":"info","message":"processing","correlation_id":"550e8400-e29b-41d4-a716-446655440000"}
+end
+```
+
+Correlation IDs nest correctly and are stored in Thread-local storage:
+
+```ruby
+logger.with_correlation_id("outer") do
+  logger.with_correlation_id("inner") do
+    logger.info("nested")  # correlation_id: "inner"
+  end
+  logger.info("back")      # correlation_id: "outer"
+end
+```
+
+### Async Output
+
+Enable non-blocking log writes via a background thread:
+
+```ruby
+logger = Philiprehberger::StructuredLogger::Logger.new(async: true, buffer_size: 100)
+
+logger.info("non-blocking")
+
+# Force immediate write of buffered entries:
+logger.flush
+
+# Flush and stop the background thread:
+logger.close
+```
+
+When the buffer is full, writes fall back to synchronous mode (backpressure) to avoid dropping log entries.
+
 ## API
 
 ### `Philiprehberger::StructuredLogger::Logger`
 
 | Method | Description |
 |---|---|
-| `new(output: $stdout, level: :debug, context: {})` | Create a logger |
+| `new(output: $stdout, outputs: nil, level: :debug, context: {}, formatter: nil, sampling: {}, async: false, buffer_size: 1000)` | Create a logger |
 | `debug(message, **extra)` | Log at debug level |
 | `info(message, **extra)` | Log at info level |
 | `warn(message, **extra)` | Log at warn level |
 | `error(message, **extra)` | Log at error level |
 | `fatal(message, **extra)` | Log at fatal level |
 | `child(**context)` | Create a child logger with merged context |
+| `level` | Get the current log level |
 | `level=(new_level)` | Set the minimum log level |
+| `with_context(**extra, &block)` | Temporarily merge context for a block |
+| `silence(level = :fatal, &block)` | Temporarily raise log level for a block |
+| `log_exception(exception, level: :error, **extra)` | Log exception details |
+| `add_output(io, level: nil, formatter: nil)` | Add an output destination at runtime |
+| `with_correlation_id(id = nil, &block)` | Set a correlation ID for the block |
+| `flush` | Force write of all buffered log entries |
+| `close` | Flush and stop async background threads |
 
 ### `Philiprehberger::StructuredLogger::Formatter`
 
@@ -97,6 +264,29 @@ logger = Philiprehberger::StructuredLogger::Logger.new(output: file)
 |---|---|
 | `call(level, message, context)` | Build a JSON log string |
 
+### `Philiprehberger::StructuredLogger::TextFormatter`
+
+| Method | Description |
+|---|---|
+| `call(level, message, context)` | Build a human-readable text log string |
+
+### `Philiprehberger::StructuredLogger::AsyncWriter`
+
+| Method | Description |
+|---|---|
+| `new(output, buffer_size: 1000)` | Create an async writer wrapping an IO |
+| `puts(line)` | Enqueue a line for async writing |
+| `flush` | Force write of buffered entries |
+| `close` | Flush and stop the background thread |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
 ## License
 
 MIT

data/lib/philiprehberger/structured_logger/async_writer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module StructuredLogger
+    # Non-blocking log writer that enqueues log lines to a background thread.
+    # Falls back to synchronous writes when the buffer is full (backpressure).
+    class AsyncWriter
+      # @param output [IO] writable output destination
+      # @param buffer_size [Integer] maximum number of queued log lines
+      def initialize(output, buffer_size: 1000)
+        @output = output
+        @buffer_size = buffer_size
+        @queue = SizedQueue.new(buffer_size)
+        @stopped = false
+        @closed = false
+        @mutex = Mutex.new
+        @thread = Thread.new { drain }
+      end
+
+      # Enqueue a log line for asynchronous writing.
+      # Falls back to synchronous write if the buffer is full.
+      #
+      # @param line [String] the formatted log line
+      def write(line)
+        @mutex.synchronize do
+          return sync_write(line) if @stopped
+        end
+
+        begin
+          @queue.push(line, true)
+        rescue ThreadError
+          sync_write(line)
+        end
+      end
+
+      # Write a log line using puts.
+      #
+      # @param line [String] the formatted log line
+      def puts(line)
+        write(line)
+      end
+
+      # Force all buffered log lines to be written immediately.
+      def flush
+        Thread.pass until @queue.empty?
+        @output.flush if @output.respond_to?(:flush)
+      end
+
+      # Flush remaining log lines and stop the background thread.
+      # Safe to call multiple times.
+      def close
+        @mutex.synchronize do
+          return if @closed
+
+          @stopped = true
+          @closed = true
+        end
+        @queue.push(:stop)
+        @thread.join
+        @output.flush if @output.respond_to?(:flush)
+      end
+
+      private
+
+      def drain
+        loop do
+          line = @queue.pop
+          break if line == :stop
+
+          @output.puts(line)
+        end
+
+        # Drain remaining items after stop signal
+        drain_remaining
+      end
+
+      def drain_remaining
+        loop do
+          line = @queue.pop(true)
+          @output.puts(line) unless line == :stop
+        rescue ThreadError
+          break
+        end
+      end
+
+      def sync_write(line)
+        @output.puts(line)
+      end
+    end
+  end
+end

data/lib/philiprehberger/structured_logger/formatter.rb

@@ -29,5 +29,35 @@ module Philiprehberger
         }
       end
     end
+
+    # Builds plain-text structured log entries.
+    class TextFormatter
+      # Format a log entry as a human-readable text string.
+      #
+      # @param level [Symbol] the log level
+      # @param message [String] the log message
+      # @param context [Hash] merged context data
+      # @return [String] formatted text log line
+      def call(level, message, context)
+        timestamp = Time.now.utc.iso8601(3)
+        parts = ["[#{timestamp}] #{level.to_s.upcase}: #{message}"]
+        context.each do |key, value|
+          parts << "#{key}=#{value}"
+        end
+        parts.join(" ")
+      end
+    end
+
+    def self.resolve_formatter(formatter)
+      case formatter
+      when nil, :json then Formatter.new
+      when :text then TextFormatter.new
+      when Proc then formatter
+      else
+        raise ArgumentError, "Invalid formatter" unless formatter.respond_to?(:call)
+
+        formatter
+      end
+    end
   end
 end

data/lib/philiprehberger/structured_logger/logger.rb

@@ -1,40 +1,87 @@
 # frozen_string_literal: true
 
 require "monitor"
+require "securerandom"
 
 module Philiprehberger
   module StructuredLogger
-    # Thread-safe structured JSON logger with context and child loggers.
     class Logger
       LEVELS = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }.freeze
 
-      attr_reader :context
+      CORRELATION_ID_KEY = :philiprehberger_structured_logger_correlation_id
 
-      # @param output [IO] writable output (default: $stdout)
-      # @param level [Symbol] minimum log level
-      # @param context [Hash] base context merged into every entry
-      def initialize(output: $stdout, level: :debug, context: {})
-        @output = output
-        @level = level
-        @context = context.freeze
-        @formatter = Formatter.new
+      attr_reader :context, :level
+
+      def initialize(**opts)
+        @level = opts.fetch(:level, :debug)
+        @context = opts.fetch(:context, {}).freeze
+        @sampling = opts.fetch(:sampling, {})
+        @async = opts.fetch(:async, false)
+        @buffer_size = opts.fetch(:buffer_size, 1000)
         @monitor = Monitor.new
+
+        @outputs = OutputBuilder.call(opts, @async, @buffer_size)
       end
 
-      # Set the minimum log level.
-      #
-      # @param new_level [Symbol]
       def level=(new_level)
         validate_level!(new_level)
         @level = new_level
       end
 
-      # Create a child logger with additional context.
-      #
-      # @param extra [Hash] context to merge
-      # @return [Logger]
+      def add_output(io, level: nil, formatter: nil)
+        resolved = StructuredLogger.resolve_formatter(formatter)
+        wrapped = @async ? AsyncWriter.new(io, buffer_size: @buffer_size) : io
+        @monitor.synchronize { @outputs << { io: wrapped, level: level, formatter: resolved } }
+      end
+
       def child(**extra)
-        self.class.new(output: @output, level: @level, context: @context.merge(extra))
+        clone = self.class.allocate
+        clone.send(:initialize_child, @outputs, @level, @context.merge(extra), @sampling, @monitor)
+        clone
+      end
+
+      def with_context(**extra, &block)
+        @monitor.synchronize do
+          original = @context
+          @context = @context.merge(extra).freeze
+          block.call
+        ensure
+          @context = original
+        end
+      end
+
+      def silence(temp_level = :fatal, &block)
+        @monitor.synchronize do
+          original = @level
+          @level = temp_level
+          block.call
+        ensure
+          @level = original
+        end
+      end
+
+      def with_correlation_id(id = nil, &block)
+        id ||= SecureRandom.uuid
+        previous = Thread.current[CORRELATION_ID_KEY]
+        Thread.current[CORRELATION_ID_KEY] = id
+        block.call
+      ensure
+        Thread.current[CORRELATION_ID_KEY] = previous
+      end
+
+      def log_exception(exception, level: :error, **extra)
+        log(level, exception.message,
+            error_class: exception.class.name,
+            backtrace: exception.backtrace || [],
+            **extra)
+      end
+
+      def flush
+        @monitor.synchronize { @outputs.each { |out| out[:io].flush if out[:io].respond_to?(:flush) } }
+      end
+
+      def close
+        @monitor.synchronize { @outputs.each { |out| out[:io].close if out[:io].is_a?(AsyncWriter) } }
       end
 
       LEVELS.each_key do |lvl|
@@ -45,22 +92,76 @@ module Philiprehberger
 
       private
 
+      def initialize_child(outputs, level, context, sampling, monitor)
+        @outputs = outputs
+        @level = level
+        @context = context.freeze
+        @sampling = sampling
+        @monitor = monitor
+      end
+
       def log(level, message, **extra)
-        return unless should_log?(level)
+        return unless LEVELS.fetch(level) >= LEVELS.fetch(@level)
+        return unless sample?(level)
 
         merged = @context.merge(extra)
-        line = @formatter.call(level, message, merged)
-        @monitor.synchronize { @output.puts(line) }
+        cid = Thread.current[CORRELATION_ID_KEY]
+        merged = merged.merge(correlation_id: cid) if cid
+        @monitor.synchronize { write_to_outputs(level, message, merged) }
+      end
+
+      def write_to_outputs(level, message, merged)
+        @outputs.each do |out|
+          next if out[:level] && LEVELS.fetch(level) < LEVELS.fetch(out[:level])
+
+          out[:io].puts(out[:formatter].call(level, message, merged))
+        end
       end
 
-      def should_log?(level)
-        LEVELS.fetch(level) >= LEVELS.fetch(@level)
+      def sample?(level)
+        rate = @sampling.fetch(level, 1.0)
+        rate >= 1.0 || (rate > 0.0 && rand < rate)
       end
 
       def validate_level!(level)
-        return if LEVELS.key?(level)
+        raise ArgumentError, "Invalid level: #{level}" unless LEVELS.key?(level)
+      end
+    end
+
+    # Builds output configuration from constructor options.
+    module OutputBuilder
+      module_function
+
+      def call(opts, async, buffer_size)
+        outputs = opts[:outputs]
+        if outputs
+          build_multi(outputs, opts[:formatter], async, buffer_size)
+        else
+          build_single(opts[:output], opts[:formatter], async, buffer_size)
+        end
+      end
+
+      def build_multi(outputs, default_formatter, async, buffer_size)
+        outputs.map do |out|
+          if out.is_a?(Hash)
+            build_hash_output(out, async, buffer_size)
+          else
+            io = async ? AsyncWriter.new(out, buffer_size: buffer_size) : out
+            { io: io, level: nil, formatter: StructuredLogger.resolve_formatter(default_formatter) }
+          end
+        end
+      end
+
+      def build_hash_output(out, async, buffer_size)
+        io = async ? AsyncWriter.new(out[:io], buffer_size: buffer_size) : out[:io]
+        fmt = StructuredLogger.resolve_formatter(out[:formatter])
+        { io: io, level: out[:level], formatter: fmt }
+      end
 
-        raise ArgumentError, "Invalid level: #{level}. Valid: #{LEVELS.keys.join(', ')}"
+      def build_single(output, formatter, async, buffer_size)
+        io = output || $stdout
+        io = AsyncWriter.new(io, buffer_size: buffer_size) if async
+        [{ io: io, level: nil, formatter: StructuredLogger.resolve_formatter(formatter) }]
       end
     end
   end

data/lib/philiprehberger/structured_logger/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module StructuredLogger
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/philiprehberger/structured_logger.rb

@@ -2,6 +2,7 @@
 
 require_relative "structured_logger/version"
 require_relative "structured_logger/formatter"
+require_relative "structured_logger/async_writer"
 require_relative "structured_logger/logger"
 
 module Philiprehberger

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-structured_logger
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-11 00:00:00.000000000 Z
+date: 2026-03-17 00:00:00.000000000 Z
 dependencies: []
 description: A zero-dependency Ruby gem for structured JSON logging with context merging,
   child loggers, level filtering, and pluggable outputs.
@@ -22,6 +22,7 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/structured_logger.rb
+- lib/philiprehberger/structured_logger/async_writer.rb
 - lib/philiprehberger/structured_logger/formatter.rb
 - lib/philiprehberger/structured_logger/logger.rb
 - lib/philiprehberger/structured_logger/version.rb