philiprehberger-structured_logger 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7adb741998f54fcb27d66e78322d0abcb77c6537298e8b8d9be58b999bf571
-  data.tar.gz: bbeea6cf1479ffa7548be5ab32cdaca87dc42c8d5657a778e1e71574056ac4f1
+  metadata.gz: c8cf0e19aa5820ae2ee81a3cf73ece78e151e6a53f7fc48f8c74e94f9b7841ed
+  data.tar.gz: c7ab4e1bc11362adc93bfe54dcf06360b846a232d1d433c597a60f7d2e4a1fd0
 SHA512:
-  metadata.gz: 67ac2a22e4a7b1b3397256fc39e9e04d11fe219b21096fd1b3c8e9996bb98f8120859baa378448d33cfe55425759c406aac72f17520582fcda4ad23e4171c4a2
-  data.tar.gz: db854b806432b15b8b891592011f02ca39741975657ef1948d6fcfad6f5408e69101b7100b46007b03588216fd85cb997c7d91fbfa299d99dcff82c88fdb5ace
+  metadata.gz: d239e014b25dd71f821e97213b1ad979c2444d6cae3f4db330debec29e6f6a045b6dde4abc84e350f6cca3f384886fccc2430d413709131f58a6b81f8b09657e
+  data.tar.gz: 9a390ecf766ec22be918f9fb3a2daf5fcc8643cafe7848e82b72ce6fae7fc90c3cc176ba15da5dc2fb7f2544cf51730088851ec4fa801fe80ab70dfdd98eca7f

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-25
+
+### Added
+- `Logger#with_tags(*tags)` for tagged context blocks with automatic restoration
+- `Logger#measure_value(message)` variant of `#measure` that returns the block result while still emitting the timing entry
+
 ## [0.4.0] - 2026-04-17
 
 ### Added

data/README.md

@@ -256,6 +256,40 @@ logger.close
 
 When the buffer is full, writes fall back to synchronous mode (backpressure) to avoid dropping log entries.
 
+### Tagged Context
+
+Use `with_tags` to add tags to the logging context for the duration of a block. Tags merge with any existing tags (de-duplicated, preserving order) and the original context is restored on exit:
+
+```ruby
+require "philiprehberger/structured_logger"
+
+logger = Philiprehberger::StructuredLogger::Logger.new
+
+logger.with_tags("auth", "request") do
+  logger.info("Login attempt")
+  # => {"timestamp":"...","level":"info","message":"Login attempt","tags":["auth","request"]}
+end
+# Tags are restored after the block
+```
+
+### Measuring with Return Value
+
+Use `measure_value` when you need the block's result while still emitting a timing entry:
+
+```ruby
+require "philiprehberger/structured_logger"
+
+logger = Philiprehberger::StructuredLogger::Logger.new
+
+result = logger.measure_value("db.query") do
+  # ...query the database...
+  [{ id: 1, name: "Alice" }]
+end
+
+# result == [{ id: 1, name: "Alice" }]
+# => {"timestamp":"...","level":"info","message":"db.query","event":"db.query","duration_ms":12.345}
+```
+
 ## API
 
 ### `Philiprehberger::StructuredLogger::Logger`
@@ -275,6 +309,8 @@ When the buffer is full, writes fall back to synchronous mode (backpressure) to
 | `silence(level = :fatal, &block)` | Temporarily raise log level for a block |
 | `log_exception(exception, level: :error, **extra)` | Log exception details |
 | `measure(event_name, **context) { block }` | Time a block, emit an info event with `duration_ms`, and re-raise on failure |
+| `#with_tags(*tags) { block }` | Add tags to context for the block |
+| `#measure_value(message) { block }` | Like #measure but returns the block's value |
 | `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 |

data/lib/philiprehberger/structured_logger/logger.rb

@@ -50,6 +50,41 @@ module Philiprehberger
         end
       end
 
+      # Adds the given tags to the logger's context under the `:tags`
+      # key, merging with any existing tags (de-duplicated, preserving
+      # insertion order). When a block is given, the previous context is
+      # restored when the block exits (even on exception). Without a
+      # block, the change persists like {#with_context}.
+      #
+      # @param tags [Array<String, Symbol>] one or more tags to add.
+      # @yield (optional) executes within the tagged context; the
+      #   original context is restored on exit.
+      # @return [Object, Hash] the block's return value when a block is
+      #   given, otherwise the new merged context hash.
+      #
+      # @example Block form
+      #   logger.with_tags('auth', 'request') do
+      #     logger.info('Login attempt')
+      #     # entry includes tags: ['auth', 'request']
+      #   end
+      def with_tags(*tags)
+        existing = @context[:tags] || []
+        merged_tags = (existing + tags).uniq
+        if block_given?
+          @monitor.synchronize do
+            original = @context
+            @context = @context.merge(tags: merged_tags).freeze
+            yield
+          ensure
+            @context = original
+          end
+        else
+          @monitor.synchronize do
+            @context = @context.merge(tags: merged_tags).freeze
+          end
+        end
+      end
+
       def silence(temp_level = :fatal, &block)
         @monitor.synchronize do
           original = @level
@@ -111,6 +146,23 @@ module Philiprehberger
         end
       end
 
+      # Variant of {#measure} that emits the same timing log entry but
+      # also returns the block's return value. Captures and re-raises
+      # exceptions like {#measure}.
+      #
+      # @param event_name [String, Symbol] the event name to record as
+      #   the `event` field in the log entry.
+      # @param context [Hash] extra context merged into the log entry.
+      # @yield executes the measured block.
+      # @return [Object] the block's return value on success.
+      # @raise re-raises any exception raised by the block.
+      #
+      # @example Capturing a query result
+      #   result = logger.measure_value('db.query') { query_database }
+      def measure_value(event_name, **context, &)
+        measure(event_name, **context, &)
+      end
+
       def flush
         @monitor.synchronize { @outputs.each { |out| out[:io].flush if out[:io].respond_to?(:flush) } }
       end

data/lib/philiprehberger/structured_logger/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module StructuredLogger
-    VERSION = '0.4.0'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-structured_logger
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-04-26 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.