loggerstash 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5fd1556e489712e61e7737f1605cafae63e09a3d611d4dc2581ab0a0769e4dc
-  data.tar.gz: 3d0c19110f5cdc49f97fc2531982f1402604b65720e76b433d7ebc32d03e7b9a
+  metadata.gz: 1ea3f2fdbe4dfa4604759d473ef117f7c1c1961b3c484be9b7deb1c2ed53dc74
+  data.tar.gz: ca16b574bdd0adfef725a7eb8a3821a541ba8f74bc7f88be0185888daf125ec3
 SHA512:
-  metadata.gz: 45038a77ffe34f2b5e86158e9eb52955918bf75e506d4a70b6ed808c12db8c853449a859c870dc28514ca59145558d07f322138c2f79b825ab8922a461a906e5
-  data.tar.gz: a0ae83e92b00dad48125c030d8937750fa950dcc99e867d968abd078d987c5d373e0fd2072cfd4483c6a3553f48a522d1014ca57be6091307a106eba8e584753
+  metadata.gz: bea707a8f38924bfac3b4c61d61fff5eff9d534c4beaa08024cc70865a79968a5f9a75399e9a4f7a06a9cc93351c539c7077ef4c7a11e0764adb6d0235107f56
+  data.tar.gz: 64d870fac502e29a4dc811ae0d4e83268a80e238642021b6294a2029b5b914b7b09a9595bb7347ce69c3d8312f3198aa590956cc0e5d009bbcef8deec7870cd8

data/lib/filtered_debug_logger.rb

@@ -0,0 +1,42 @@
+require 'logger'
+
+# Filter debug-level log entries on progname
+#
+# Whilst well-thought-out debug logs are fantastic at showing you the
+# fine-level detail of your program's execution, they can sometimes be
+# "too much of a good thing".  Excessively verbose debug logs can obscure
+# the important debug info, and turning on debug logging on a busy service
+# can quickly swamp all but the most overprovisioned of log aggregation
+# systems.
+#
+# Hence, there's this little module.  Require it in your program, and then
+# set `logger.permitted_prognames = ['some', 'array']` on whatever logger
+# is likely to want some debug logging.  Then, whenever debug logging is
+# enabled, only those calls to `logger.debug` which provide a progname exactly
+# matching an entry in the list you provided will actually get logged.
+#
+module FilteredDebugLogger
+  # Set the list of prognames to log debug messages for.
+  #
+  # @param l [Array<String>] the (exact) prognames to log debug-level messages
+  #   for.  If it's not in this list, it doesn't get emitted, even if debug
+  #   logging is enabled.
+  #
+  def permitted_prognames=(l)
+    raise ArgumentError, "Must provide an array" unless l.is_a?(Array)
+
+    @permitted_prognames = l
+  end
+
+  # Decorate Logger#add with our "reject by progname" logic.
+  #
+  def add(s, m = nil, p = nil)
+    return if s == Logger::DEBUG && @permitted_prognames && !@permitted_prognames.include?(p)
+
+    super
+  end
+
+  alias log add
+end
+
+Logger.prepend(FilteredDebugLogger)

data/lib/loggerstash.rb

@@ -14,16 +14,51 @@ class Loggerstash
   #
   class AlreadyRunningError < Error; end
 
+  # Set the formatter proc to a new proc.
+  #
+  # The passed in proc must take four arguments: `severity`, `timestamp`,
+  # `progname` and `message`.  `timestamp` is a `Time`, all over arguments
+  # are `String`s, and `progname` can possibly be `nil`.  It must return a
+  # Hash containing the parameters you wish to send to logstash.
+  #
   attr_writer :formatter
 
-  def initialize(logstash_server:, metrics_registry: nil, formatter: nil)
+  # A new Loggerstash!
+  #
+  # @param logstash_server [String] an address:port, hostname:port, or srvname
+  #   to which a `json_lines` logstash connection can be made.
+  # @param metrics_registry [Prometheus::Client::Registry] where the metrics
+  #   which are used by the underlying `LogstashWriter` should be registered,
+  #   for later presentation by the Prometheus client.
+  # @param formatter [Proc] a formatting proc which takes the same arguments
+  #   as the standard `Logger` formatter, but rather than emitting a string,
+  #   it should pass back a Hash containing all the fields you wish to send
+  #   to logstash.
+  # @param logstash_writer [LogstashWriter] in the event that you've already
+  #   got a LogstashWriter instance configured, you can pass it in here.  Note
+  #   that any values you've set for logstash_server and metrics_registry
+  #   will be ignored.
+  #
+  def initialize(logstash_server:, metrics_registry: nil, formatter: nil, logstash_writer: nil)
     @logstash_server = logstash_server
     @metrics_registry = metrics_registry
     @formatter = formatter
+    @logstash_writer = logstash_writer
 
     @op_mutex = Mutex.new
   end
 
+  # Associate this Loggerstash with a Logger (or class of Loggers).
+  #
+  # A single Loggerstash instance can be associated with one or more Logger
+  # objects, or all instances of Logger, by attaching the Loggerstash to the
+  # other object (or class).  Attaching a Loggerstash means it can no longer
+  # be configured (by the setter methods).
+  #
+  # @param obj [Object] the instance or class to attach this Loggerstash to.
+  #   We won't check that you're attaching to an object or class that will
+  #   benefit from the attachment; that's up to you to ensure.
+  #
   def attach(obj)
     @op_mutex.synchronize do
       obj.instance_variable_set(:@loggerstash, self)
@@ -50,21 +85,36 @@ class Loggerstash
     end
   end
 
+  # Send a logger message to logstash.
+  #
+  # @private
+  #
   def log_message(s, t, p, m)
     @op_mutex.synchronize do
       if @logstash_writer.nil?
+        #:nocov:
         run_writer
+        #:nocov:
       end
 
       @logstash_writer.send_event((@formatter || default_formatter).call(s, t, p, m))
     end
   end
+
   private
 
+  # Do the needful to get the writer going.
+  #
+  # This will error out unless the @op_mutex is held at the time the
+  # method is called; we can't acquire it ourselves because some calls
+  # to run_writer already need to hold the mutex.
+  #
   def run_writer
     unless @op_mutex.owned?
+      #:nocov:
       raise RuntimeError,
             "Must call run_writer while holding @op_mutex"
+      #:nocov:
     end
 
     if @logstash_writer.nil?
@@ -80,6 +130,9 @@ class Loggerstash
     end
   end
 
+  # Mangle the standard sev/time/prog/msg set into a minimal logstash
+  # event.
+  #
   def default_formatter
     @default_formatter ||= ->(s, t, p, m) do
       {
@@ -92,6 +145,8 @@ class Loggerstash
     end
   end
 
+  # The methods needed to turn any Logger into a Loggerstash Logger.
+  #
   module Mixin
     private
 
@@ -104,11 +159,20 @@ class Loggerstash
       super
     end
 
+    # Find where our associated Loggerstash object is being held captive.
+    #
+    # We're kinda reimplementing Ruby's method lookup logic here, but there's
+    # no other way to store our object *somewhere* in the object + class
+    # hierarchy and still be able to get at it from a module (class variables
+    # don't like being accessed from modules).
+    #
     def loggerstash
       ([self] + self.class.ancestors).find { |m| m.instance_variable_defined?(:@loggerstash) }.instance_variable_get(:@loggerstash).tap do |ls|
         if ls.nil?
+          #:nocov:
           raise RuntimeError,
                 "Cannot find loggerstash instance.  CAN'T HAPPEN."
+          #:nocov:
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loggerstash
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-02 00:00:00.000000000 Z
+date: 2018-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logstash_writer
@@ -210,6 +210,7 @@ files:
 - CONTRIBUTING.md
 - LICENCE
 - README.md
+- lib/filtered_debug_logger.rb
 - lib/loggerstash.rb
 - loggerstash.gemspec
 homepage: https://github.com/discourse/loggerstash