philiprehberger-log_filter 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a05316f59bd1b7ea9c31dad53105a3febd50bac5c0b274257838ebf2e8e66f0
-  data.tar.gz: acd65cf197ebb2037dffc890d7be274e0dbd986cfc10de7270efb1cc922232a3
+  metadata.gz: a18a7f3be999eaccf0508fb12df28e38684d0a807e3eea4837e40ed55cc903e5
+  data.tar.gz: 4a0fd034904e1fafa47fbecf687d5ea01b9569f6d9720c96bc1f711b7e6298fd
 SHA512:
-  metadata.gz: cfc4d1c293fbdcef1fc8249f00d9cd3739d903f32b93586aaa64183f3c8f35d1bc7973d2762319529834ed936d9aebcdb934c9e91eaecbc753928054ae33f073
-  data.tar.gz: c1f741854430ca2d1c0925bc6fd04e5c06cc3ccb8542802ee2ca379d8bf2c4726ac4851d5a39d6dbb17c4ac747429a7de4c8b23d9c41d141c977353f9f64f14f
+  metadata.gz: b4e97b6b1332f6d7bda4bdb985e27562c7f05b882643eaf63e0cb9d2f78347e853a8cfedd37f9f6f064aab3ab461019d627152fd5d415f9e6ea1c02d754dad75
+  data.tar.gz: f4e6a55d9145024a782f0807bce58acb9d4448aa6194fee6c0fad93aa47efddbc94fc653ac260f5ddc00db4c142758401b12a92833d43329718caf6b2fb4071d

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-30
+
+### Added
+- `Filter#describe_rules` returns an array of `{type:, description:}` hashes describing each configured rule for debugging and logging
+- `Filter#explain(message)` runs a message through the chain without mutating stats or invoking tap blocks, returning the transformed result plus a per-rule decision trace
+
 ## [0.6.0] - 2026-05-29
 
 ### Added

data/README.md

@@ -183,6 +183,44 @@ filter.apply("GET /api/users 200")  # => "GET /api/users 200"
 filter.apply("worker booted")       # => nil
 ```
 
+### Debugging filters with `explain`
+
+When a filter chain isn't behaving as expected, use `#describe_rules` to dump the configuration and `#explain(message)` to trace how a specific message flows through. `#explain` is side-effect-free — it does NOT mutate `#stats` and does NOT invoke `tap_each` blocks. Sample rules are treated deterministically (a match counts as `:sampled_in`) so traces are reproducible.
+
+```ruby
+require "philiprehberger/log_filter"
+
+filter = Philiprehberger::LogFilter::Filter.new
+  .drop(/DEBUG/)
+  .replace(/password=\S+/, "password=[REDACTED]")
+  .mask_field("ssn")
+
+filter.describe_rules
+# => [
+#   { type: :drop_pattern, description: "drop matching /DEBUG/" },
+#   { type: :replace,      description: "replace /password=\\S+/ with \"password=[REDACTED]\"" },
+#   { type: :mask_field,   description: "mask field \"ssn\" with \"***\"" }
+# ]
+
+filter.explain("user login password=abc123")
+# => {
+#   result: "user login password=[REDACTED]",
+#   decisions: [
+#     { rule: 0, type: :drop_pattern, matched: false, action: :passed },
+#     { rule: 1, type: :replace,      matched: true,  action: :replaced },
+#     { rule: 2, type: :mask_field,   matched: false, action: :unchanged }
+#   ]
+# }
+
+filter.explain("DEBUG noisy line")
+# => {
+#   result: nil,
+#   decisions: [
+#     { rule: 0, type: :drop_pattern, matched: true, action: :dropped }
+#   ]
+# }
+```
+
 ### Filter Statistics
 
 ```ruby
@@ -216,6 +254,8 @@ filter.stats  # => { dropped: 0, passed: 0, replaced: 0, sampled: 0 }
 | `Filter#tap_each(&block)` | Invoke the block with every message passing through; message is forwarded unchanged; returns self |
 | `Filter#apply(message)` | Run all rules; returns transformed string or nil |
 | `Filter#chain(other)` | Compose with another filter; returns a new filter piping events through both |
+| `Filter#describe_rules` | Return an array of `{type:, description:}` hashes describing every rule in order |
+| `Filter#explain(message)` | Trace how a message flows through the chain without mutating stats or invoking tap blocks; returns `{result:, decisions:}` |
 | `Filter#stats` | Return counters: dropped, passed, replaced, sampled |
 | `Filter#reset_stats!` | Zero all statistics counters |
 | `Wrapper.new(logger, filter)` | Wrap a Logger with a filter |

data/lib/philiprehberger/log_filter/filter.rb

@@ -154,6 +154,55 @@ module Philiprehberger
         result
       end
 
+      # Return a human-readable description of every rule in the chain,
+      # in declaration order. Useful for debugging, logging, or rendering
+      # the filter configuration in an admin UI.
+      #
+      # Does not mutate any state and does not invoke any rule blocks.
+      #
+      # @return [Array<Hash{Symbol=>Object}>] one hash per rule with
+      #   +:type+ (the rule's symbol type) and +:description+ (a
+      #   human-readable string)
+      def describe_rules
+        @rules.map { |r| { type: r[:type], description: describe_rule(r) } }
+      end
+
+      # Run +message+ through the chain WITHOUT mutating stats and WITHOUT
+      # invoking any +tap_each+ blocks. Returns a trace describing what
+      # each rule did to the message, plus the final transformed value
+      # (or +nil+ if the chain would have dropped it).
+      #
+      # Intended for debugging filter configurations. Because +:sample+
+      # rules are stochastic, this method treats a sample rule as a
+      # deterministic +sampled_in+ when its pattern matches (it shows the
+      # path the message would take if the sample passed). This makes
+      # +explain+ deterministic and side-effect-free.
+      #
+      # @param message [String] the log message to trace
+      # @return [Hash] with +:result+ (the transformed message or +nil+)
+      #   and +:decisions+ (an array of per-rule decision hashes). Each
+      #   decision hash has +:rule+ (0-indexed integer), +:type+ (the
+      #   rule's symbol), +:matched+ (whether the rule applied), and
+      #   +:action+ (one of +:passed+, +:dropped+, +:replaced+, +:masked+,
+      #   +:sampled_in+, +:sampled_out+, +:truncated+, +:tapped+,
+      #   +:unchanged+).
+      def explain(message)
+        decisions = []
+        result = message.dup
+
+        @rules.each_with_index do |rule, idx|
+          decision, new_result = explain_rule(rule, result, idx)
+          decisions << decision
+          if decision[:action] == :dropped
+            return { result: nil, decisions: decisions }
+          end
+
+          result = new_result
+        end
+
+        { result: result, decisions: decisions }
+      end
+
       # Compose this filter with +other+ into a new filter.
       #
       # The returned filter's +apply+ runs +self.apply+ first and passes the
@@ -277,6 +326,102 @@ module Philiprehberger
       rescue JSON::ParserError
         nil
       end
+
+      # Render a single rule as a human-readable string.
+      #
+      # @param rule [Hash] a single rule hash
+      # @return [String]
+      def describe_rule(rule)
+        case rule[:type]
+        when :drop_pattern
+          "drop matching #{rule[:pattern].inspect}"
+        when :drop_block
+          'drop if block returns truthy'
+        when :replace
+          "replace #{rule[:pattern].inspect} with #{rule[:replacement].inspect}"
+        when :sample
+          "sample #{rule[:pattern].inspect} at rate #{rule[:rate]}"
+        when :drop_field
+          "drop field #{rule[:key].inspect}"
+        when :mask_field
+          "mask field #{rule[:key].inspect} with #{rule[:mask].inspect}"
+        when :truncate
+          "truncate to #{rule[:max_length]} chars with suffix #{rule[:suffix].inspect}"
+        when :tap
+          'tap each message (side effect)'
+        end
+      end
+
+      # Trace a single rule for {#explain}. Returns a [decision, new_message]
+      # pair. Never mutates stats and never calls user-supplied tap blocks.
+      #
+      # @param rule [Hash] a single rule hash
+      # @param message [String] the current message
+      # @param idx [Integer] the 0-based index of the rule in the chain
+      # @return [Array(Hash, String)]
+      def explain_rule(rule, message, idx)
+        case rule[:type]
+        when :drop_pattern
+          if message.match?(rule[:pattern])
+            [{ rule: idx, type: rule[:type], matched: true, action: :dropped }, message]
+          else
+            [{ rule: idx, type: rule[:type], matched: false, action: :passed }, message]
+          end
+        when :drop_block
+          if rule[:block].call(message)
+            [{ rule: idx, type: rule[:type], matched: true, action: :dropped }, message]
+          else
+            [{ rule: idx, type: rule[:type], matched: false, action: :passed }, message]
+          end
+        when :replace
+          replaced = message.gsub(rule[:pattern], rule[:replacement])
+          if replaced == message
+            [{ rule: idx, type: rule[:type], matched: false, action: :unchanged }, message]
+          else
+            [{ rule: idx, type: rule[:type], matched: true, action: :replaced }, replaced]
+          end
+        when :sample
+          if message.match?(rule[:pattern])
+            [{ rule: idx, type: rule[:type], matched: true, action: :sampled_in }, message]
+          else
+            [{ rule: idx, type: rule[:type], matched: false, action: :unchanged }, message]
+          end
+        when :drop_field
+          parsed = parse_json(message)
+          if parsed&.key?(rule[:key])
+            parsed.delete(rule[:key])
+            [{ rule: idx, type: rule[:type], matched: true, action: :replaced },
+             JSON.generate(parsed)]
+          else
+            [{ rule: idx, type: rule[:type], matched: false, action: :unchanged }, message]
+          end
+        when :mask_field
+          parsed = parse_json(message)
+          if parsed&.key?(rule[:key])
+            parsed[rule[:key]] = rule[:mask]
+            [{ rule: idx, type: rule[:type], matched: true, action: :masked },
+             JSON.generate(parsed)]
+          else
+            [{ rule: idx, type: rule[:type], matched: false, action: :unchanged }, message]
+          end
+        when :truncate
+          if message.length > rule[:max_length]
+            suffix = rule[:suffix]
+            max_length = rule[:max_length]
+            new_msg = if suffix.length >= max_length
+                        suffix[0, max_length]
+                      else
+                        message[0, max_length - suffix.length] + suffix
+                      end
+            [{ rule: idx, type: rule[:type], matched: true, action: :truncated }, new_msg]
+          else
+            [{ rule: idx, type: rule[:type], matched: false, action: :unchanged }, message]
+          end
+        when :tap
+          # Intentionally do not invoke the tap block — explain is side-effect-free.
+          [{ rule: idx, type: rule[:type], matched: true, action: :tapped }, message]
+        end
+      end
     end
 
     # A filter produced by {Filter#chain} that pipes events through two

data/lib/philiprehberger/log_filter/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module LogFilter
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-log_filter
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-30 00:00:00.000000000 Z
+date: 2026-05-31 00:00:00.000000000 Z
 dependencies: []
 description: Pattern-based log filtering — drop or transform log lines matching rules.
   Includes preset filters for health checks, static assets, and bot traffic.