philiprehberger-structured_logger 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7adb741998f54fcb27d66e78322d0abcb77c6537298e8b8d9be58b999bf571
-  data.tar.gz: bbeea6cf1479ffa7548be5ab32cdaca87dc42c8d5657a778e1e71574056ac4f1
+  metadata.gz: fc219c6050b216013a637d5318a9709a870c024ab1edb390868062659343ba7f
+  data.tar.gz: 38c8d7a6d7938d2f7494c805d7f77460d5f644957110221bf5621c5e39db0516
 SHA512:
-  metadata.gz: 67ac2a22e4a7b1b3397256fc39e9e04d11fe219b21096fd1b3c8e9996bb98f8120859baa378448d33cfe55425759c406aac72f17520582fcda4ad23e4171c4a2
-  data.tar.gz: db854b806432b15b8b891592011f02ca39741975657ef1948d6fcfad6f5408e69101b7100b46007b03588216fd85cb997c7d91fbfa299d99dcff82c88fdb5ace
+  metadata.gz: f29e6f9e660c14de6266aa7897ea2abbd6805eea66c5c027b32e6076175cdf86cfc592849b85c0ed09397b14b57bf90bba52c3f441edcff93f23d27f436dfed6
+  data.tar.gz: f09c837882298ea589e3b18730c523ec6343254945c9e4c2cf8c1a0928af51d5fa0753a15abde31674df1d792801d3ffc0dd84bc8c89f31ec4fe5eca98744fc3

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-30
+
+### Added
+- `Logger#log_exception(structured_backtrace: true)` option to emit the backtrace as an array of `{file:, line:, method:}` hashes for friendlier log-aggregation indexing
+
+### Fixed
+- README now includes the standard package card image after the badges
+- Bug report issue template now includes a required `gem-version` field
+
+## [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

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-structured_logger.svg)](https://rubygems.org/gems/philiprehberger-structured_logger)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-structured-logger)](https://github.com/philiprehberger/rb-structured-logger/commits/main)
 
+![philiprehberger-structured_logger](https://raw.githubusercontent.com/philiprehberger/rb-structured-logger/main/package-card.webp)
+
 Structured JSON logger with context and child loggers
 
 ## Requirements
@@ -121,6 +123,36 @@ end
 logger.log_exception(e, level: :fatal, user_id: 42)
 ```
 
+### Structured backtraces
+
+By default `log_exception` emits the backtrace as an array of raw
+strings (matching `exception.backtrace`). Pass `structured_backtrace: true`
+to parse each line into a hash with `:file`, `:line`, and `:method`
+keys — easier to index in log-aggregation systems like Elasticsearch,
+Datadog, or Loki:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  logger.log_exception(e, structured_backtrace: true)
+  # => {
+  #      "timestamp":"...",
+  #      "level":"error",
+  #      "message":"something broke",
+  #      "error_class":"RuntimeError",
+  #      "backtrace":[
+  #        {"file":"app/foo.rb","line":42,"method":"bar"},
+  #        {"file":"lib/baz.rb","line":7,"method":"qux"}
+  #      ]
+  #    }
+end
+```
+
+Lines without a method segment omit the `:method` key. Lines that
+don't match the standard Ruby backtrace format fall back to
+`{ raw: "<original line>" }`.
+
 ### Timing a block
 
 Use `measure` to time a block and emit a single structured event with `duration_ms`:
@@ -256,6 +288,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`
@@ -273,8 +339,10 @@ When the buffer is full, writes fall back to synchronous mode (backpressure) to
 | `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 |
+| `log_exception(exception, level: :error, structured_backtrace: false, **extra)` | Log exception details. Pass `structured_backtrace: true` to emit the backtrace as `{file:, line:, method:}` hashes |
 | `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

@@ -10,6 +10,12 @@ module Philiprehberger
 
       CORRELATION_ID_KEY = :philiprehberger_structured_logger_correlation_id
 
+      # Regex matching a single Ruby backtrace line. Captures the file
+      # path, the line number, and (optionally) the method name. Handles
+      # both Ruby 3.4+ single-quote (`'method'`) and Ruby 3.3-and-earlier
+      # backtick-apostrophe (`` `method' ``) quoting.
+      BACKTRACE_LINE = /\A(?<file>.+?):(?<line>\d+)(?::in ['`](?<method>[^']+)')?\z/
+
       attr_reader :context, :level
 
       def initialize(**opts)
@@ -50,6 +56,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
@@ -69,10 +110,41 @@ module Philiprehberger
         Thread.current[CORRELATION_ID_KEY] = previous
       end
 
-      def log_exception(exception, level: :error, **extra)
+      # Logs an exception's message, class, and backtrace as a single
+      # structured entry.
+      #
+      # @param exception [Exception] the exception to log.
+      # @param level [Symbol] the log level for the entry (default
+      #   `:error`).
+      # @param structured_backtrace [Boolean] when `false` (default),
+      #   the backtrace is emitted as an array of raw strings (the same
+      #   shape as `exception.backtrace`). When `true`, each backtrace
+      #   line is parsed into a hash with `:file`, `:line` (Integer),
+      #   and (when present) `:method` keys. Lines that don't match the
+      #   standard Ruby backtrace format are passed through as
+      #   `{ raw: "<original line>" }`. The parsed form is generally
+      #   easier to index in log-aggregation systems like Elasticsearch,
+      #   Datadog, or Loki.
+      # @param extra [Hash] additional context merged into the log
+      #   entry.
+      # @return [void]
+      #
+      # @example Default (raw string backtrace)
+      #   logger.log_exception(e)
+      #   # backtrace: ["app/foo.rb:42:in 'bar'", ...]
+      #
+      # @example Structured backtrace
+      #   logger.log_exception(e, structured_backtrace: true)
+      #   # backtrace: [
+      #   #   { file: "app/foo.rb", line: 42, method: "bar" },
+      #   #   ...
+      #   # ]
+      def log_exception(exception, level: :error, structured_backtrace: false, **extra)
+        bt = exception.backtrace || []
+        bt = parse_backtrace(bt) if structured_backtrace
         log(level, exception.message,
             error_class: exception.class.name,
-            backtrace: exception.backtrace || [],
+            backtrace: bt,
             **extra)
       end
 
@@ -111,6 +183,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
@@ -161,6 +250,16 @@ module Philiprehberger
       def validate_level!(level)
         raise ArgumentError, "Invalid level: #{level}" unless LEVELS.key?(level)
       end
+
+      def parse_backtrace(backtrace)
+        backtrace.map do |line|
+          if (m = line.match(BACKTRACE_LINE))
+            { file: m[:file], line: m[:line].to_i, method: m[:method] }.compact
+          else
+            { raw: line }
+          end
+        end
+      end
     end
 
     # Builds output configuration from constructor options.

data/lib/philiprehberger/structured_logger/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module StructuredLogger
-    VERSION = '0.4.0'
+    VERSION = '0.6.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.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-05-31 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.