philiprehberger-structured_logger 0.3.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c97dff36fddffd8ef26c0e08eee6912b41509c203803ef11d467b8e64fa8a1a
-  data.tar.gz: 6bb760bfb58992ca97db27ef7b5a220617984256f488a2eae4e7f1bd7320eab9
+  metadata.gz: c8cf0e19aa5820ae2ee81a3cf73ece78e151e6a53f7fc48f8c74e94f9b7841ed
+  data.tar.gz: c7ab4e1bc11362adc93bfe54dcf06360b846a232d1d433c597a60f7d2e4a1fd0
 SHA512:
-  metadata.gz: 935b133170aacfd15bd0b9152cd30dd845a807fcf0e31d417fda1c2d6186c2ed0acedb11156554420370630a6151037697fa2a0f903cabe989fbb6a59234dae5
-  data.tar.gz: 2f30001a038326c9eb53e2427f85a905f001a1781bc91968e86e2ceff0a49b3bb4b0e606609242675630a73bebcd5eb3829546413f1113225ebdb06f99ca7cb3
+  metadata.gz: d239e014b25dd71f821e97213b1ad979c2444d6cae3f4db330debec29e6f6a045b6dde4abc84e350f6cca3f384886fccc2430d413709131f58a6b81f8b09657e
+  data.tar.gz: 9a390ecf766ec22be918f9fb3a2daf5fcc8643cafe7848e82b72ce6fae7fc90c3cc176ba15da5dc2fb7f2544cf51730088851ec4fa801fe80ab70dfdd98eca7f

data/CHANGELOG.md

@@ -7,6 +7,22 @@ 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
+- `Logger#measure(event, **context) { block }` yields to the block, captures elapsed time, and emits a single info-level structured event with `duration_ms` (plus `error`/`error_class` on failure; original exception re-raised)
+
+## [0.3.5] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.3.4] - 2026-03-31
 
 ### Changed

data/README.md

@@ -121,6 +121,23 @@ end
 logger.log_exception(e, level: :fatal, user_id: 42)
 ```
 
+### Timing a block
+
+Use `measure` to time a block and emit a single structured event with `duration_ms`:
+
+```ruby
+logger.measure("db.query", table: "users") { User.find(1) }
+# => {"timestamp":"...","level":"info","message":"db.query","event":"db.query","table":"users","duration_ms":12.345}
+```
+
+On failure, the original exception is re-raised and the log entry also includes `error` and `error_class`:
+
+```ruby
+logger.measure("db.query") { raise "boom" }
+# => {"timestamp":"...","level":"info","message":"db.query","event":"db.query","duration_ms":0.123,"error":"boom","error_class":"RuntimeError"}
+# RuntimeError: boom
+```
+
 ### Multiple Outputs
 
 Log to multiple destinations simultaneously. Each output can have its own level filter and formatter:
@@ -239,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`
@@ -257,6 +308,9 @@ When the buffer is full, writes fall back to synchronous mode (backpressure) to
 | `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 |
+| `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
@@ -76,6 +111,58 @@ module Philiprehberger
             **extra)
       end
 
+      # Yields to the given block, measures its monotonic wall-clock
+      # duration, and emits a single info-level log entry describing the
+      # outcome. On success, the block's return value is returned. On
+      # exception, the failure is logged and the original exception is
+      # re-raised.
+      #
+      # @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 Measuring a database query
+      #   logger.measure('db.query', table: 'users') { User.find(1) }
+      #   # logs event: 'db.query', table: 'users', duration_ms: 12.345
+      def measure(event_name, **context)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          result = yield
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0).round(3)
+          log(:info, event_name.to_s, event: event_name, duration_ms: duration_ms, **context)
+          result
+        rescue StandardError => e
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0).round(3)
+          log(:info, event_name.to_s,
+              event: event_name,
+              duration_ms: duration_ms,
+              error: e.message,
+              error_class: e.class.name,
+              **context)
+          raise
+        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.3.4'
+    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.3.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 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.
@@ -26,11 +26,11 @@ files:
 - lib/philiprehberger/structured_logger/formatter.rb
 - lib/philiprehberger/structured_logger/logger.rb
 - lib/philiprehberger/structured_logger/version.rb
-homepage: https://github.com/philiprehberger/rb-structured-logger
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-structured_logger
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-structured-logger
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-structured_logger
   source_code_uri: https://github.com/philiprehberger/rb-structured-logger
   changelog_uri: https://github.com/philiprehberger/rb-structured-logger/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'