philiprehberger-log_filter 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20449cdb409bc84ab640e2baa8e3762c3695eed5dc5e4c740c70a15acb249675
-  data.tar.gz: bda4b072fd035940d86ad1cee170aa9683fe642546d166fe64164c99dd72d32a
+  metadata.gz: 683ed9a496a285367a229889b099e3fe5dcaacce4c4f659d98f51c1f151f77f6
+  data.tar.gz: 97ad3d5ecb23b237128cbe1f416c444bf531e428d6f5611aeb1ca3f606fa7d16
 SHA512:
-  metadata.gz: 03d7c21e00e2baeee8c6ccae4adea63c4fa58a78a7a2d6e6d5a802190014d630f094a5d602e0023979a5af2afcd1fcf395678185f4232cd478d67817a6990c79
-  data.tar.gz: 822fd979279c229e1950ff35d8c195a2953eb4eba1b5aeaf73254914c63fd5c840086ff6361a15dc844cedf604140ed5534a38d62f9a5a7b28a5c009bb5bc499
+  metadata.gz: a8fc6d49639fc0b38e7915953f19d41d8aec7f0e6eeae4eff394cbc55ebed7331ef88a3f0da856d8eddeac762a20d1e24c0de84ac29003bdb621a49ad893de38
+  data.tar.gz: df60ffb387bbb13b15fe9cb903d46494bcc33800822a5e42dc73e5b01275943ca0840a0b2d5bf93355e66d411995b129a9f17ff3ff79874e4e346fa0920bb248

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-29
+
+### Added
+
+- Sampling support via `Filter#sample(pattern, rate:)` — pass through only a fraction of matching messages
+- Filter statistics via `Filter#stats` and `Filter#reset_stats!` — thread-safe atomic counters for dropped, passed, replaced, and sampled messages
+- Structured log support via `Filter#drop_field(key)` and `Filter#mask_field(key, with:)` — parse JSON messages, remove or mask fields, re-serialize
+
 ## [0.1.7] - 2026-03-26
 
 ### Changed

data/README.md

@@ -2,7 +2,11 @@
 
 [![Tests](https://github.com/philiprehberger/rb-log-filter/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-log-filter/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-log_filter.svg)](https://rubygems.org/gems/philiprehberger-log_filter)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-log-filter)](https://github.com/philiprehberger/rb-log-filter/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-log-filter)](https://github.com/philiprehberger/rb-log-filter/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-log-filter)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-log-filter/bug)](https://github.com/philiprehberger/rb-log-filter/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-log-filter/enhancement)](https://github.com/philiprehberger/rb-log-filter/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
 [![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 Pattern-based log filtering with drop, replace, and preset rules
@@ -63,6 +67,8 @@ filtered_logger.info("GET /api/users 200")       # logs normally
 ### Using Presets
 
 ```ruby
+require "philiprehberger/log_filter"
+
 # Drop health-check noise
 filter = Philiprehberger::LogFilter.health_check_filter
 filtered_logger = Philiprehberger::LogFilter.wrap(logger, filter)
@@ -77,11 +83,60 @@ filter = Philiprehberger::LogFilter.bot_filter
 ### Block-Based Drop Rules
 
 ```ruby
+require "philiprehberger/log_filter"
+
 filter = Philiprehberger::LogFilter::Filter.new
   .drop_if { |msg| msg.length > 1000 }   # drop excessively long messages
   .drop_if { |msg| msg.count("\n") > 10 } # drop multi-line spam
 ```
 
+### Sampling
+
+```ruby
+require "philiprehberger/log_filter"
+
+# Only pass through 10% of debug messages
+filter = Philiprehberger::LogFilter::Filter.new
+  .sample(/DEBUG/, rate: 0.1)
+
+filter.apply("DEBUG verbose output")  # => nil (90% of the time)
+filter.apply("INFO normal message")   # => "INFO normal message" (always passes)
+```
+
+### Structured Log Support
+
+```ruby
+require "philiprehberger/log_filter"
+
+filter = Philiprehberger::LogFilter::Filter.new
+  .drop_field("password")
+  .mask_field("ssn", with: "***")
+
+filter.apply('{"user":"alice","password":"secret","ssn":"123-45-6789"}')
+# => '{"user":"alice","ssn":"***"}'
+
+# Non-JSON messages pass through unmodified
+filter.apply("plain text log line")  # => "plain text log line"
+```
+
+### Filter Statistics
+
+```ruby
+require "philiprehberger/log_filter"
+
+filter = Philiprehberger::LogFilter::Filter.new
+  .drop(/DEBUG/)
+  .replace(/secret/, "[REDACTED]")
+
+filter.apply("DEBUG noise")
+filter.apply("has secret data")
+filter.apply("normal message")
+
+filter.stats  # => { dropped: 1, passed: 2, replaced: 1, sampled: 0 }
+filter.reset_stats!
+filter.stats  # => { dropped: 0, passed: 0, replaced: 0, sampled: 0 }
+```
+
 ## API
 
 | Class / Method | Description |
@@ -90,7 +145,12 @@ filter = Philiprehberger::LogFilter::Filter.new
 | `Filter#drop(pattern)` | Add a regex drop rule; returns self |
 | `Filter#drop_if(&block)` | Add a block-based drop rule; returns self |
 | `Filter#replace(pattern, replacement)` | Add a replacement rule; returns self |
+| `Filter#sample(pattern, rate:)` | Add a sampling rule; only pass rate fraction of matches |
+| `Filter#drop_field(key)` | Remove a field from JSON log messages; returns self |
+| `Filter#mask_field(key, with:)` | Mask a field value in JSON log messages; returns self |
 | `Filter#apply(message)` | Run all rules; returns transformed string or nil |
+| `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 |
 | `Presets.health_check` | Filter dropping health-check paths |
 | `Presets.assets` | Filter dropping static-asset requests |
@@ -108,6 +168,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
 [MIT](LICENSE)

data/lib/philiprehberger/log_filter/filter.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'securerandom'
+
 module Philiprehberger
   module LogFilter
     # Chain of rules that can drop or transform log messages.
@@ -13,6 +16,8 @@ module Philiprehberger
 
       def initialize
         @rules = []
+        @mutex = Mutex.new
+        @stats = { dropped: 0, passed: 0, replaced: 0, sampled: 0 }
       end
 
       # Add a pattern-based drop rule. Messages matching +pattern+ are suppressed.
@@ -47,6 +52,56 @@ module Philiprehberger
         self
       end
 
+      # Add a sampling rule. Only pass through +rate+ fraction of messages
+      # matching +pattern+. Non-matching messages pass through unaffected.
+      #
+      # @param pattern [Regexp] the pattern to match
+      # @param rate [Float] sampling rate between 0.0 and 1.0
+      # @return [self] for chaining
+      def sample(pattern, rate:)
+        raise ArgumentError, 'rate must be between 0.0 and 1.0' unless rate.is_a?(Numeric) && rate >= 0.0 && rate <= 1.0
+
+        @rules << { type: :sample, pattern: pattern, rate: rate.to_f }
+        self
+      end
+
+      # Add a rule to remove a field from JSON log messages.
+      # Non-JSON messages pass through unmodified.
+      #
+      # @param key [String] the JSON field key to remove
+      # @return [self] for chaining
+      def drop_field(key)
+        @rules << { type: :drop_field, key: key.to_s }
+        self
+      end
+
+      # Add a rule to mask a field value in JSON log messages.
+      # Non-JSON messages pass through unmodified.
+      #
+      # @param key [String] the JSON field key to mask
+      # @param with [String] the mask replacement value
+      # @return [self] for chaining
+      def mask_field(key, with: '***')
+        @rules << { type: :mask_field, key: key.to_s, mask: with }
+        self
+      end
+
+      # Return current filter statistics.
+      #
+      # @return [Hash] counters for :dropped, :passed, :replaced, :sampled
+      def stats
+        @mutex.synchronize { @stats.dup }
+      end
+
+      # Reset all statistics counters to zero.
+      #
+      # @return [void]
+      def reset_stats!
+        @mutex.synchronize do
+          @stats = { dropped: 0, passed: 0, replaced: 0, sampled: 0 }
+        end
+      end
+
       # Run all rules against +message+ in order.
       #
       # @param message [String] the log message to filter
@@ -56,23 +111,98 @@ module Philiprehberger
 
         @rules.each do |rule|
           result = apply_rule(rule, result)
-          return nil if result.nil?
+          if result.nil?
+            increment_stat(:dropped)
+            return nil
+          end
         end
 
+        increment_stat(:passed)
         result
       end
 
       private
 
+      # @param stat [Symbol] the stat key to increment
+      # @return [void]
+      def increment_stat(stat)
+        @mutex.synchronize { @stats[stat] += 1 }
+      end
+
       # @param rule [Hash] a single rule hash
       # @param message [String] the current message
       # @return [String, nil]
       def apply_rule(rule, message)
         case rule[:type]
-        when :drop_pattern then message.match?(rule[:pattern]) ? nil : message
-        when :drop_block   then rule[:block].call(message) ? nil : message
-        when :replace      then message.gsub(rule[:pattern], rule[:replacement])
+        when :drop_pattern
+          message.match?(rule[:pattern]) ? nil : message
+        when :drop_block
+          rule[:block].call(message) ? nil : message
+        when :replace
+          replaced = message.gsub(rule[:pattern], rule[:replacement])
+          if replaced != message
+            increment_stat(:replaced)
+          end
+          replaced
+        when :sample
+          apply_sample_rule(rule, message)
+        when :drop_field
+          apply_drop_field_rule(rule, message)
+        when :mask_field
+          apply_mask_field_rule(rule, message)
+        end
+      end
+
+      # @param rule [Hash] a sample rule
+      # @param message [String] the current message
+      # @return [String, nil]
+      def apply_sample_rule(rule, message)
+        return message unless message.match?(rule[:pattern])
+
+        return unless SecureRandom.rand < rule[:rate]
+
+        increment_stat(:sampled)
+        message
+      end
+
+      # @param rule [Hash] a drop_field rule
+      # @param message [String] the current message
+      # @return [String]
+      def apply_drop_field_rule(rule, message)
+        parsed = parse_json(message)
+        return message unless parsed
+
+        parsed.delete(rule[:key])
+        JSON.generate(parsed)
+      rescue StandardError
+        message
+      end
+
+      # @param rule [Hash] a mask_field rule
+      # @param message [String] the current message
+      # @return [String]
+      def apply_mask_field_rule(rule, message)
+        parsed = parse_json(message)
+        return message unless parsed
+
+        if parsed.key?(rule[:key])
+          parsed[rule[:key]] = rule[:mask]
+          increment_stat(:replaced)
         end
+        JSON.generate(parsed)
+      rescue StandardError
+        message
+      end
+
+      # Attempt to parse a string as JSON.
+      #
+      # @param str [String] the string to parse
+      # @return [Hash, nil] parsed hash or nil if not valid JSON object
+      def parse_json(str)
+        result = JSON.parse(str)
+        result.is_a?(Hash) ? result : nil
+      rescue JSON::ParserError
+        nil
       end
     end
   end

data/lib/philiprehberger/log_filter/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module LogFilter
-    VERSION = "0.1.7"
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/log_filter.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "log_filter/version"
-require_relative "log_filter/filter"
-require_relative "log_filter/wrapper"
-require_relative "log_filter/presets"
+require_relative 'log_filter/version'
+require_relative 'log_filter/filter'
+require_relative 'log_filter/wrapper'
+require_relative 'log_filter/presets'
 
 module Philiprehberger
   module LogFilter

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-log_filter
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-30 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.