safis-logging 1.0.1

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/NOTICE.md

@@ -0,0 +1,10 @@
+Safis Logging
+=============
+
+Part of the Safis Project.
+
+
+Contributors and Copyright Holders
+----------------------------------
+
+* Copyright 2009, Ian MacLeod <ian@nevir.net>

data/README.md

@@ -0,0 +1,92 @@
+Safis Logging
+=============
+
+When building distributed applications, the ability to audit their behavior is a necessity.  Often, the easiest way to get at this information is by logging it!
+
+The goal of the Safis logging subsystem is to provide the ability to log your application's behavior with minimal developer friction.
+
+
+Getting Started
+---------------
+
+So, let's suppose you're developing an application for your evil overlord.  The aim, of course, is to take over the world; but you'd best start small.
+
+    require 'safis/logging'
+    
+    log.warn 'The world shall be ours! ...in due time.'
+
+Which outputs your nefarious intentions to STDOUT:
+
+> ``WARN: [Object 19:57:24] The world shall be ours! ...in due time. [2009-07-01T19:57:24.818687-07:00]``  
+
+The time is duplicated you say?  Why haven't I been dropped into a shark tank for _daring to denormalize_ your log output!?
+
+Well, we often forget that it will be a bleary-eyed developer who will be pouring over these logs.  As such, they should give them the information they care about first, and more granular information second.
+
+After all, you can't afford to execute all of your minions for easily avoidable failure; and you certainly don't want the overlord to do the same to you!
+
+
+The Hierarchy
+-------------
+
+Much of the power of the Safis logger comes from gleaning the structure of your application.  You use, Modules and Classes, _right?_
+
+    require 'safis/logging'
+    
+    module Villany
+      log.warn 'Loading Villany...'
+      
+      class SharkTankTrapDoor
+        def open!
+          log.info 'Dropping the hero into a tank of certain death! With laser beams.'
+          
+          begin
+            ...
+          rescue TrapDoorFailure => err
+            log.fatal 'The trap door failed to open. Execute the nearest henchman immediately!', err
+          end
+        end
+      end
+    end
+  
+Of course, the trap door will fail, embarrassing the overlord _for the last time_:
+
+> ``WARN: [Villany 20:24:32] Loading Villany... [2009-07-01T20:24:32.329174-07:00]``  
+> ``INFO: [Villany::SharkTankTrapDoor 20:24:36] Dropping the hero into a tank of certain death! With laser beams. [2009-07-01T20:24:36.197427-07:00]``  
+> ``FATAL: [Villany::SharkTankTrapDoor 20:24:38] The trap door failed to open. Execute the nearest henchman immediately! [2009-07-01T20:24:38.747175-07:00]``  
+> ``  TrapDoorFailure: The magma vents are blocked.``  
+> ``    /villany/power_source/geothermal.rb:27:in `reroute_magma_flow'``  
+> ``    /villany/power_source/geothermal.rb:53:in `check_power_levels'``  
+> ``    ...``  
+
+Of course, there's also a variety of menial tasks that your overlord just can't be bothered to peruse.  You can filter out log events that you don't need.  Building on the above example, if we had set the following filter level (in the global context):
+
+    log.filter_level = :warn
+
+The `:info` log event would be filtered out of the log output.  It would look like:
+
+> ``WARN: [Villany 20:24:32] Loading Villany... [2009-07-01T20:24:32.329174-07:00]``  
+> ``FATAL: [Villany::SharkTankTrapDoor 20:24:38] The trap door failed to open. Execute the nearest henchman immediately! [2009-07-01T20:24:38.747175-07:00]``  
+> ``  TrapDoorFailure: The magma vents are blocked.``  
+> ``    /villany/power_source/geothermal.rb:27:in `reroute_magma_flow'``  
+> ``    /villany/power_source/geothermal.rb:53:in `check_power_levels'``  
+> ``    ...``
+
+Furthermore, filter levels inherit from their parent `Log`s.  For example:
+
+    log.filter_level = :fatal
+    
+    module Villany
+      class SharkTankTrapDoor
+        log.filter_level = :info
+      end
+    end
+
+In this case, `Villany` inherits from the global scope's log (`Object`'s log), so the initial :warn log event would be filtered.  However, `Villany::SharkTankTrapDoor` overrides that with a filter level of `:info`, allowing the other two log events to be outputted unscathed:
+ 
+> ``INFO: [Villany::SharkTankTrapDoor 20:24:36] Dropping the hero into a tank of certain death! With laser beams. [2009-07-01T20:24:36.197427-07:00]``  
+> ``FATAL: [Villany::SharkTankTrapDoor 20:24:38] The trap door failed to open. Execute the nearest henchman immediately! [2009-07-01T20:24:38.747175-07:00]``  
+> ``  TrapDoorFailure: The magma vents are blocked.``  
+> ``    /villany/power_source/geothermal.rb:27:in `reroute_magma_flow'``  
+> ``    /villany/power_source/geothermal.rb:53:in `check_power_levels'``  
+> ``    ...``

data/lib/safis/logging.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'safis/logging/automagic'
+
+module Safis
+  module Logging
+    autoload :Log,             'safis/logging/log'
+    autoload :SimpleFormatter, 'safis/logging/simple_formatter'
+    autoload :FileRotator,     'safis/logging/file_rotator'
+  end
+end

data/lib/safis/logging/automagic.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'safis/logging'
+
+class Object
+  # Returns the {Log} for this object's class
+  def log
+    self.class.log
+  end
+end
+
+class Module
+  # Returns the {Log} for this +Module+ (or +Class+)
+  def log
+    if ( not instance_variable_defined? :@log ) then
+      # If we're Object, we're top 'o the chain and want to send our events to the default formatter
+      parent = nil
+      if ( self != Object ) then
+        scope_position = name.rindex('::')
+        parent_constant = (scope_position) ? eval(name[0...scope_position]) : Object
+        
+        parent = parent_constant.log
+      end
+      
+      @log = Safis::Logging::Log.new(name, parent)
+    end
+    
+    @log
+  end
+end

data/lib/safis/logging/file_rotator.rb

@@ -0,0 +1,162 @@
+# encoding: utf-8
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'safis/logging'
+
+module Safis
+  module Logging
+    # An IO-like object that writes its input out to disk, rotating files as they fill up or expire.
+    class FileRotator
+      # The base path & file name of this +LogRotator+'s resultant files.
+      attr_reader :base_path
+      
+      # How often files should be automatically rotated, regardless of their size.
+      attr_reader :granularity
+      
+      # The maximum size of a file before it is rotated
+      attr_reader :max_size
+      
+      # The maximum number of files kept around (old files are deleted)
+      attr_reader :max_files
+      
+      # Creates a new +FileRotator+.
+      # 
+      # Depending on the values you choose, the file naming scheme differs slightly.  In all the 
+      # following examples, we use +"doom_laser.log"+ as our +base_path+.
+      # 
+      # @example Hourly rotated log
+      #   doom_laser.2009-07-03-14.log
+      #   doom_laser.2009-07-03-15.log
+      #   doom_laser.2009-07-03-15.1.log
+      # 
+      # @example Daily rotated log
+      #   doom_laser.2009-07-03.log
+      #   doom_laser.2009-07-04.log
+      #   doom_laser.2009-07-04.1.log
+      # 
+      # @example No time based rotation
+      #   doom_laser.log
+      #   doom_laser.1.log
+      #   doom_laser.2.log
+      # 
+      # @param [String] base_path The base path and name of the file.
+      # @param [optional, :hourly, :daily, :none] granularity How often should the output be 
+      #                                                       automatically rotated?  Every hour?
+      #                                                       Every Day?  Never?
+      # @param [optional, Number] max_size The maximum size of a file, in bytes, before it gets 
+      #                                    rotated.  Defaults to 16MiB.
+      # @param [optional, Number] max_files The maximum number of files to keep around before
+      #                                     deleting old ones.  Defaults to 100 (so approx 1.5GiB
+      #                                     maximum).
+      def initialize(base_path, granularity = :hourly, max_size = 16777216, max_files = 100)
+        @base_path   = base_path
+        @file_root   = File.dirname(base_path)
+        @file_ext    = File.extname(base_path)
+        @file_base   = File.basename(base_path, @file_ext)
+        
+        @granularity = granularity
+        @max_size    = max_size
+        @max_files   = max_files
+        
+        @file_lock = Mutex.new
+        @file      = create_file
+      end
+      
+      # Writes output to the current file
+      def write(output)
+        @file_lock.synchronize do
+          # Do we need to rotate due to file size?
+          if ( @file.stat.size + output.length > @max_size ) then
+            @file = create_file
+            
+          # Or do we need to rotate due to a time switchover?
+          elsif ( @next_rotation and Time.now >= @next_rotation ) then
+            @file = create_file
+          end
+          
+          # aaand log it
+          @file.write(output)
+        end
+      end
+      
+    protected
+      # Creates a new file, rotating as necessary
+      # 
+      # NOT SYNCHRONIZED!
+      def create_file
+        full_base = @file_base
+        
+        now = Time.now
+        
+        # Set up our file base and the next rotation time
+        if ( @granularity == :daily ) then
+          full_base += ".#{now.strftime('%Y-%m-%d')}"
+          @next_rotation = Time.mktime(now.year, now.month, now.day) + 86400
+          
+        elsif ( @granularity == :hourly ) then
+          full_base     += ".#{now.strftime('%Y-%m-%d-%H')}"
+          @next_rotation = Time.mktime(now.year, now.month, now.day, now.hour) + 3600
+        end
+        
+        # Set up for scanning the directory
+        base_path         = File.join(@file_root, full_base)
+        escaped_base_path = base_path.gsub('.', '\\.')
+        escaped_ext       = @file_ext.gsub('.', '\\.')
+        file_regex        = Regexp.new("^#{escaped_base_path}(\\.(\\d+))#{escaped_ext}$")
+        
+        # Read in any existing files, and sort them by their incremental values.  Note that we're
+        # storing this in a Hash, since there might be gaps
+        existing_files = {}
+        Dir.glob("#{base_path}*#{@file_ext}").each do |path|
+          # is this our "zeroth" increment?
+          if ( path == "#{base_path}#{@file_ext}" ) then
+            existing_files[0] = path
+          else
+            match = file_regex.match(path)
+            
+            if ( match ) then
+              existing_files[match[2].to_i] = path
+            end
+          end
+        end
+        
+        # sort it by increment
+        sorted_files = existing_files.sort { |a,b| a[0] <=> b[0] }
+        
+        # Delete any files if we have too many
+        if ( sorted_files.length >= @max_files ) then
+          delete_until = sorted_files[sorted_files.length - @max_files][0]
+          
+          while ( sorted = sorted_files[0] and sorted[0] <= delete_until ) do
+            sorted_files.delete_at(0)
+            File.delete(sorted[1])
+          end
+        end
+        
+        # Finally, create our latest one
+        if ( sorted_files.length == 0 ) then
+          new_file_path = base_path + @file_ext
+        else
+          new_increment = sorted_files[-1][0] + 1
+          new_file_path = "#{base_path}.#{new_increment}#{@file_ext}"
+        end
+        
+        file = File.open(new_file_path, 'a') # append, just in case it was created during this
+        file.sync = true # flush every write
+        
+        return file
+      end
+    end
+  end
+end

data/lib/safis/logging/log.rb

@@ -0,0 +1,208 @@
+# encoding: utf-8
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'safis/logging'
+
+module Safis
+  module Logging
+    class Log
+      @@persisted_filter_levels = {}
+      
+      # Log severities, and their order (least to most severe)
+      SEVERITY = [
+        :debug,
+        :info,
+        :warn,
+        :error,
+        :fatal
+      ]
+      
+      # The current filter level of this +Log+.  Can be +nil+.
+      attr_reader :filter_level
+      
+      # Indicates that this +Log+ should filter all log events at a level below the one set.
+      # 
+      # For example, filtering at the +:warn+ level indicates that you want only log events of the 
+      # +:warn+ severity or higher to be logged.
+      # 
+      # If the filter level is nil, the Log inherits the filter level from its parent Log; 
+      # defaulting to no filtering if there is no ancestor to inherit from.
+      # 
+      # @param [Symbol] new_filter_level The new filter level for this +Log+.
+      def filter_level=(new_filter_level)
+        @filter_level = new_filter_level
+      end
+      
+      # The parent +Log+ or +Formatter+.
+      attr_reader :parent
+      
+      # Sets the parent +Log+ or +Formatter+.
+      # 
+      # All log events from this +Log+ or its children will be send to the parent, by calling
+      # {#log_event} on the parent.
+      def parent=(new_parent)
+        @parent = new_parent
+      end
+      
+      # The component that this log emits log events for.  This is typically the name of the +Class+
+      # or +Module+ that its log events are associated with.
+      attr_reader :component
+      
+      # Creates a new Log.
+      # 
+      # @param [String] component The name of the component that this log tracks.
+      # @param [optional, #log_event] parent An object that responds to +#log_event+.  This is usually
+      #                               another +Log+ to bubble events up to, or a formatter object
+      #                               (like {SimpleFormatter}).
+      def initialize(component, parent = nil)
+        @component = component
+        @parent    = parent || SimpleFormatter.new
+        
+        # Do we have a persisted filter level?
+        if ( @@persisted_filter_levels.has_key? component ) then
+          @filter_level = @@persisted_filter_levels[component]
+        end
+      end
+      
+      # Logs an event.
+      # 
+      # An event is an array with values in the following order:
+      # * severity
+      # * component name
+      # * timestamp
+      # * message
+      # * event details (optional - usually an exception)
+      # 
+      # @param [Array] event The event to log.
+      # @param [Boolean] filter Whether or not this Log should apply filtering logic to the event.
+      # 
+      # @return [Log] Returns self, for the chaining fanatics.
+      def log_event(event, filter = true)
+        # Just pass it up?
+        if ( not filter )
+          @parent.log_event(event, filter)
+          
+        # Otherwise filter as necessary
+        else
+          event_level = SEVERITY.index(event[0])
+          # do we filter this?
+          if ( event_level.nil? or event_level >= computed_filter_level )
+            # nope.  And let our parent know to not filter any further
+            @parent.log_event(event, false)
+          end
+        end
+        
+        # In case you want to chain?
+        self
+      end
+      
+      # Handle the method missing event, allowing us to handle whatever severities this Log
+      # implements.  If the method called is a severity, we take two arguments: message and an 
+      # optional details object (typically an exception).  We then generate a log event, and pass it
+      # up to be formatted and outputted.
+      # 
+      # An event is an array with values in the following order:
+      # * severity
+      # * component name
+      # * timestamp
+      # * message
+      # * event details (optional - usually an exception)
+      def method_missing(severity, *args)
+        # this isn't a severity we know about, so just treat it like a standard missing method
+        if ( not SEVERITY.include? severity ) then
+          super(severity, *args)
+        end
+        
+        # otherwise log out the event
+        self.log_event([
+          severity,
+          @component,
+          Time.now,
+          args[0],
+          args[1],
+        ])
+        
+        # not sure why you'd need to chain this, but let's do it!
+        return self
+      end
+      
+      # Returns a human readable version of this Log.
+      # 
+      # @example A Log with the filter level set.
+      #   <Log for 'Villany::PowerSource::Geothermal', filter level :warn>
+      def to_s
+        result  = "<Log for '#{@component}'"
+        result << ", filter level :#{@filter_level}" if @filter_level
+        return result + '>'
+      end
+      
+      # Alias for {#to_s}.
+      def inspect
+        to_s
+      end
+      
+      
+      #################
+      # Class Methods #
+      #################
+      
+      # Batch-sets filter levels for each component's +Log+ that you specify.
+      # 
+      # @param [Hash<String => Symbol>] filter_levels A Hash (or set of options) indicating filter
+      #                                               levels for component +Log+s.  The key is the
+      #                                               name, and the value is the filter level.
+      def self.set_filter_levels(filter_levels = {})
+        ObjectSpace.each_object(self) do |log|
+          if ( filter_levels.has_key? log.component ) then
+            log.filter_level = filter_levels[log.component]
+          end
+        end
+      end
+      
+      # Persists a set of filter levels for current and future component +Log+s.
+      # 
+      # This is similar to {#set_filter_levels}, but in addition to setting the filter levels of
+      # existing +Log+s, it also determines filter levels for any new +Log+ that is created.
+      #
+      # @param [Hash<String => Symbol>] filter_levels A Hash (or set of options) indicating filter
+      #                                               levels for component +Log+s.  The key is the
+      #                                               name, and the value is the filter level.
+      def self.persist_filter_levels(filter_levels = {})
+        @@persisted_filter_levels = filter_levels
+        
+        set_filter_levels(filter_levels)
+      end
+      
+    protected
+      # :nodoc:
+      # 
+      # Returns the computed filter level, _as a Number_, inheriting from this Log's ancestors as
+      # necessary.
+      def computed_filter_level
+        if ( @filter_level ) then
+          # convert the symbol to a Number value
+          return SEVERITY.index(@filter_level) || -1 # don't filter if we can't find it
+          
+        # if we have a parent, and it looks like a Log, return its filter level
+        elsif ( @parent and @parent.respond_to? :filter_level ) then
+          return @parent.computed_filter_level
+          
+        # otherwise, default to not filtering anything
+        else
+          return -1
+        end
+      end
+    end
+  end
+end

data/lib/safis/logging/simple_formatter.rb

@@ -0,0 +1,147 @@
+# encoding: utf-8
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'safis/logging'
+
+require 'time'
+
+module Safis
+  module Logging
+    # A simple log formatter.
+    # 
+    # This formatter generates logging output in the following format:
+    # 
+    #   SEVERITY: [component HH:MM:SS] Log message [ISO-8601 Datetime]
+    # 
+    # If the log event had details associated with it, the details value is inspected and printed
+    # to the following line.  Exceptions are logged with their full backtrace.
+    # 
+    # == A Few Examples
+    # 
+    # === Simple log event
+    #   WARN: [Object 19:57:24] The world shall be ours! ...in due time. [2009-07-01T19:57:24.818687-07:00]
+    # 
+    # === Log event with details
+    #   INFO: [Villany::DoomLaser 04:32:27] Doom laser locked on target. [2009-07-02T04:32:27.775913-07:00]
+    #     #<Villany::DoomLaser:0x13ee44 @power_level=11, @target=[40.689606, -74.044901]>
+    # 
+    # === Log event with an exception as details
+    #   FATAL: [Villany::SharkTankTrapDoor 20:24:38] The trap door failed to open. Execute the nearest henchman immediately! [2009-07-01T20:24:38.747175-07:00]
+    #     TrapDoorFailure: The magma vents are blocked.
+    #       /villany/power_source/geothermal.rb:27:in `reroute_magma_flow'
+    #       /villany/power_source/geothermal.rb:53:in `check_power_levels'
+    #       ...
+    class SimpleFormatter
+      # Creates a new SimpleFormatter.
+      # 
+      # @param [optional, #write] output An +IO+-like object to write our formatted logging output to.
+      def initialize(output = STDOUT)
+        @output = output
+      end
+      
+      # Formats and outputs an event.
+      # 
+      # An event is an array with values in the following order:
+      # * severity
+      # * component name
+      # * timestamp
+      # * message
+      # * event details (optional - usually an exception)
+      # 
+      # @param [Array] event The event to log.
+      # @param [Boolean] filter This is ignored by +SimpleFormatter+.  It does not filter events.
+      # 
+      # @return [SimpleFormatter] Returns self, for the chaining fanatics.
+      def log_event(event, filter = true)
+        begin
+          formatted_event = self.class.format_event(event)
+          
+        # The logging facilities shouldn't generate exceptions themselves if we can help it.
+        rescue Exception => err
+          formatted_event  = "We failed to format a log event!  Event details:\n"
+          formatted_event << event.inspect + "\n"
+          formatted_event << "Exception: #{err.message}\n"
+          err.backtrace.each do |line|
+            formatted_event << line + "\n"
+          end
+        end
+        
+        # Write the entry as a single transaction
+        begin
+          @output.write(formatted_event)
+          
+        rescue Exception => err
+          # Generate an event for this exception (SPAMMY!)
+          write_failure = self.class.format_event([
+            :error,
+            self.class.name,
+            Time.now,
+            "Unable to write a formatted log event to #{@output.inspect}!",
+            err
+          ])
+          STDERR.write(write_failure)
+          
+          # Write the original error
+          STDOUT.write(result)
+        end
+        
+        # For those who love to chain
+        self
+      end
+      
+      # Formats an event.
+      # 
+      # An event is an array with values in the following order:
+      # * severity
+      # * component name
+      # * timestamp
+      # * message
+      # * event details (optional - usually an exception)
+      # 
+      # @param [Array] event The event to log.
+      # 
+      # @return [String] The formatted event.
+      def self.format_event(event)
+        result = ''
+        
+        severity   = event[0].to_s.upcase
+        component  = event[1]
+        short_time = event[2].strftime('%H:%M:%S')
+        iso_time   = event[2].iso8601
+        message    = event[3]
+        details    = event[4]
+        
+        result << "#{severity}: [#{component} #{short_time}] #{message} [#{iso_time}]\n"
+        
+        if ( not details.nil? ) then
+          # Does it look like an exception?
+          if ( details.respond_to? :backtrace ) then
+            result << '  ' + details.message + "\n"
+            
+            # and the backtrace
+            details.backtrace.each do |line|
+              result << '    ' + line + "\n"
+            end
+            
+          # Nope, just inspect it
+          else
+            result << '  ' + details.inspect + "\n"
+          end
+        end
+        
+        return result
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: safis-logging
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Ian MacLeod
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-16 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Logging made just a little bit easier.
+email: ian@nevir.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- NOTICE.md
+- README.md
+files: 
+- LICENSE.txt
+- NOTICE.md
+- README.md
+- lib/safis/logging.rb
+- lib/safis/logging/automagic.rb
+- lib/safis/logging/file_rotator.rb
+- lib/safis/logging/log.rb
+- lib/safis/logging/simple_formatter.rb
+has_rdoc: true
+homepage: http://github.com/safis/logging
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Logging made just a little bit easier.
+test_files: []
+