trace-util-adv 0.1.1 → 0.2.0

data/CHANGELOG

@@ -0,0 +1,7 @@
+27-10-2009
+==========
+* Created filter_factory.rb
+-  will include convenience methods to create and operate on filters
+- should be used when registering filters in all cases
+
+Framework has become overly complex - simplify, and refactor!

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/README

@@ -0,0 +1,87 @@
+Advanced TraceUtils
+===================
+last update: 26/10/2009
+By kristian mandrup, kmandrup@gmail.com
+---
+
+This project enables advanced TRACING capabilities on any Ruby application, class or module.
+
+The project was inspired by TraceUtils, a little meta-programming example (~50 lines of code) by Dave Thomas 
+(See Pragmatic Bookstore - http://pragprog.com/)
+
+The original TraceUtils has been completely refactored and expanded to include: 
+- Indentation according to nesting level of methods calls 
+- Define sets of context filters for when to apply tracing on a method, when to apply appenders etc 
+  - module, class, method, instance variable and composite filters
+- Action handlers to handle each trace/log statement
+- Appenders, similar to log4j appenders, to allow channeling of trace messages to multiple trace consumers
+- Action handlers and Appenders can also have context filters registered
+- Custom Filters  
+
+Design
+------
+- Log message
+  each log message consists of the message itself and its current context. The context includes:
+  - Modules/Classes hierarchy of the method where the log statement is called
+  - Method name
+  - Instance variables
+
+TODO:
+  log messages can be inserted in your application code and will be handled by the tracing framework.
+  Currently the framework only supports tracing of method entry and exits.
+
+- Tracing::TraceExt 
+  is configured with a set of action handlers (see below)
+  can be configured with a set of filters    
+
+- Tracing::TraceCalls
+  each Module/Class which should have tracing applied must include the TraceCalls module
+  when TraceCalls is included, the 'included' callback method iterates all instance methods of the module it has been included
+  for each such instance method, it will apply a 'before' and 'after' aspect to the instance method only if all filters registered
+  directly on TraceExt are passed.   
+  
+  When (the application runs and) the instance method is called, each action handler registered with TraceExt is called to handle the "runtime" tracing  
+  
+- Filter
+  decides whether the trace message and current context should "pass through". Multiple filters act as a filter chain, where all filters 
+  in the chain must be passed the filtered item is rejected
+  - ModuleFilter, ClassFilter, MethodFilter, CompositeModuleFilter, CompositeClassFilter, InstanceVarFilter, CompositeInstanceVarFilter
+
+  You can also specify custom filters (see class RangeFilter in filters/message_filters.rb)
+  Filters can also include custom include/exclude filters using Procs or Classes (see test_special_filters.rb)
+
+TODO
+  soon filters will be a lot easier to set up for the simple use cases!
+
+- ActionHandler
+  handles a runtime logging action
+  can be configured with a set of filters and appenders
+  if all filters are passed for the given log message and context, each appender is called in turn with the same message and context
+  The appenders can also be set using registered appenders with symbols. Default symbol mappings are:
+  :logger, :xml, :html, :template
+
+  For more on Appenders, see section below
+  
+  Usage:
+  @ah1 = Tracing::ActionHandler.new(:filters => [Module_filter_A, Method_filter_A], :appenders => [tla1])
+  
+  Alternative appender configuration using symbols:
+  @ah1 = Tracing::ActionHandler.new(:filters => [Module_filter_A, Method_filter_A], :appenders => [:template, :xml])
+  
+
+- Appender 
+  is configured with some appender options specific to the type of Appender 
+  must be configured with a Tracer that renders the output string which the appender the appends to some consumer, such as a stream  
+  - LoggerAppender, HtmlAppender, XmlAppender, FileAppender
+  - TemplatateLogAppender
+  
+  Usage:
+  tla1 = Tracing::TemplateLogAppender.new(:options => {:overwrite => false, :time_limit => 2.minutes}, :tracer => :string)    
+
+  For any Appender, the tracer configuration can be set using a symbol :string, :xml, :html. 
+  Otherwise the default tracer for the given appender is used, fx HtmlTracer for the HtmlAppender.
+
+Examples of use
+--------------
+- test_filters.rb
+- test_special_filters.rb

data/lib/TODO.txt

@@ -0,0 +1,12 @@
+Test String appender
+- log string to file
+
+
+
+Test library in general
+- functions as expected?
+- easy to use?
+- create RSpec tests?
+
+
+http://www.extjswithrails.com/2008/03/fitting-ext-js-into-rails-architecture.html

data/lib/action_handler.rb

@@ -0,0 +1,99 @@
+require 'filters/tracing_filter'
+require 'trace_appenders'
+
+module Tracing
+  class ActionHandler
+    include Tracing::Filter::Registration    
+    include Tracing::Filter::Exec    
+    include Tracing::Appender::Registration  
+
+    attr_accessor :filters
+
+    # enable registration of action handlers
+    module Registration
+      attr_accessor :action_handlers
+
+      def action_handler_from_type(type, options)      
+        if type.kind_of?(Symbol)
+          type_sym = type.to_sym
+          # use default mappings if no match found
+          appender_class = appender_mappings[type_sym] || action_handler_mappings[:default]
+          if appender_class
+            appender_class.new(options)
+          else
+            # nil
+            raise Exception, "No appender registered for this type: #{type}"
+          end
+        elsif appender.kind_of? Tracing::OutputTemplate::Trace
+          appender
+        else
+          nil
+        end          
+      end
+
+      def create_action_handlers(reg_action_handlers)
+        if reg_action_handlers.kind_of? Array
+          reg_action_handlers.flatten!
+          new_action_handlers = reg_action_handlers.collect do |f|
+            create_action_handler(f)
+          end  
+          new_action_handlers                  
+        elsif reg_action_handlers.kind_of?(Symbol) || reg_action_handlers.kind_of?(Hash)
+          create_action_handler(reg_action_handlers)
+        else
+          reg_action_handlers
+        end        
+      end      
+      
+      def create_action_handler(options)
+        if options.kind_of? Tracing::ActionHandler
+          options
+        elsif options.kind_of? Hash
+          Tracing::ActionHandler.new(options)
+        elsif options.kind_of?(Symbol) || options.kind_of?(String)
+          type = options.to_sym
+          Tracing::Appender.appender_from_type(type, options)
+        else
+          nil
+        end          
+      end      
+
+      # TODO: add convenience way to register action handlers using symbols!
+      def register_action_handlers(reg_action_handlers)
+        @action_handlers ||= []
+        new_action_handlers = create_action_handlers(reg_action_handlers)
+        raise Exception, "No action handlers" if !new_action_handlers
+        @action_handlers << new_action_handlers
+      end
+    end
+  
+    # register filters and appenders
+    def initialize(init_options)
+      register_filters(init_options[:filters])
+      register_appenders(init_options[:appenders] || init_options)
+    end 
+
+    # action for tracelogs that pass the filters
+    # by default send to all appenders for further processing!
+    def handle_allow(txt, context)
+      appenders.each do |appender|
+        appender.handle(txt, context)
+      end
+    end
+
+    # action for tracelogs that DO NOT pass the filters
+    def handle_not_allow(txt, context)
+    end
+
+    # handle tracelogs by applying filters and action handler methods
+    def handle(txt, context)
+      if filters_allow?(txt, context)
+        # puts "handle_allow: " + context[:method_name]
+        handle_allow(txt, context)
+      else
+        # puts "handle_not_allow: " + context[:method_name]        
+        handle_not_allow(txt, context)
+      end
+    end
+  end # class
+end # module

data/lib/appenders/appender.rb

@@ -0,0 +1,97 @@
+module Tracing
+  module Appender
+    
+    class << self
+
+      # array of Appender instances
+      attr_accessor :appender_mappings
+
+      # used to help construct/register Appender instances using convenience symbols
+      def default_appender_mappings
+        {
+          :logger => Tracing::LoggerAppender,
+          :stream => Tracing::StreamAppender,           
+          :xml => Tracing::XmlAppender,
+          :html => Tracing::HtmlAppender,          
+          :template => Tracing::TemplateLogAppender,          
+          :default => Tracing::StreamAppender
+        }
+      end
+
+      def register_default_mappings
+        @appender_mappings ||= {}
+        @appender_mappings.merge!(default_appender_mappings)
+      end
+
+      def register_appender_mappings(_appender_mappings)
+        appenders_mappings ||= {}
+        appenders_mappings.merge!(_appender_mappings)
+      end
+      
+      def unregister_appender_mappings(hash)
+        default_appender_mappings.reject!{|key, value| hash.include? key}
+      end      
+      
+
+      def create_appenders(appenders)
+        register_default_mappings if !appender_mappings
+        if appenders.kind_of? Array
+          appenders.flatten!
+          new_appenders = appenders.collect do |f|
+              Tracing::Appender.create_appender(f)
+          end  
+          new_appenders                  
+        elsif appenders.kind_of?(Symbol) || appenders.kind_of?(Hash)
+          Tracing::Appender.create_appender(appenders)
+        else
+          appenders
+        end        
+      end
+
+      def appender_options_type(options)
+        options[:type]
+      end
+
+      def appender_type(options)
+        if options.kind_of? Hash
+          appender_options_type(options)
+        elsif options.kind_of?(Symbol) || options.kind_of?(String)
+          options.to_sym
+        end
+      end
+      
+      def appender_from_type(type, options)  
+        register_default_mappings if !appender_mappings
+        if type.kind_of?(Symbol)
+          type_sym = type.to_sym
+          # use default mappings if no match found
+          appender_class = appender_mappings[type_sym] || appender_mappings[:default]
+          if appender_class
+            appender_class.new(options)
+          else
+            # nil
+            raise Exception, "No appender registered for this type: #{type}"
+          end
+        elsif appender.kind_of? Tracing::OutputTemplate::Trace
+          appender
+        else
+          nil
+        end          
+      end
+      
+      # 
+      def create_appender(options)
+        appender_mappings ||= {}
+        type = appender_type(options)
+        if type
+          appender_from_type(type, options)
+        elsif options.kind_of? Tracing::BaseAppender
+          options
+        else
+          nil
+        end          
+      end        
+    end # class
+    
+  end   
+end

data/lib/appenders/appender_registration.rb

@@ -0,0 +1,16 @@
+module Tracing
+  module Appender  
+  
+    # enable registration of appenders
+    module Registration
+      attr_accessor :appenders
+
+      def register_appenders(appenders)
+        @appenders ||= []      
+        new_appenders = Tracing::Appender.create_appenders(appenders)
+        @appenders.add(new_appenders) if new_appenders        
+      end
+      
+    end # registration
+  end
+end

data/lib/appenders/base_appender.rb

@@ -0,0 +1,82 @@
+module Tracing
+  # base appender (abstract)
+  class BaseAppender
+    include Tracing::Filter::Registration  
+    include Tracing::Filter::Exec    
+
+    attr_accessor :options
+    attr_reader :tracer
+    
+    class << self
+      attr_accessor :tracers
+
+      def default_tracers
+        {
+          :string => Tracing::OutputTemplate::StringTrace, 
+          :xml => Tracing::OutputTemplate::XmlTrace,
+          :html => Tracing::OutputTemplate::HtmlTrace,          
+          :default => Tracing::OutputTemplate::StringTrace
+        }
+      end
+
+      def register_tracers(tracers = nil)
+        @tracers ||= default_tracers
+        @tracers = @tracers.merge!(tracers || {})
+      end
+      
+      def create_tracer(tracer)
+        tracers ||= register_tracers
+        if tracer.kind_of?(Symbol) || tracer.kind_of?(String)
+          tracer_class = tracers[tracer.to_sym] || tracers[:default]
+          tracer_class.new
+        elsif tracer.kind_of? Tracing::OutputTemplate::Trace
+          tracer
+        else
+          nil
+        end
+      end      
+    end
+
+    def initialize(init_options = nil)          
+      return if !init_options
+      if init_options.kind_of? Hash
+        @options = init_options[:options] || init_options
+        register_filters(init_options[:filters])
+        tracer = @options[:tracer] if @options
+        return if !tracer
+
+        tracer = self.class.create_tracer(tracer)      
+        @tracer = tracer         
+      elsif init_options.kind_of? Symbol
+        self.class.register_tracers
+        tracer = self.class.tracers[init_options]
+        return if !tracer
+
+        tracer = self.class.create_tracer(tracer)      
+        @tracer = tracer                 
+      else
+        raise Exception, "Appender must be initialized with Hash"
+      end
+    end 
+  
+    # default action handler depending on filters result 
+    def handle(txt, context)
+      if filters_allow?(txt, context)
+        allow_append(txt, context)
+      else
+        not_allow_append(txt, context)
+      end
+    end
+  
+    def allow_append(txt, context)  
+          
+    end
+
+    def not_allow_append(txt, context)
+    end
+
+    def time_limit
+      options[:time_limit] || 1.minute    
+    end
+  end
+end  

data/lib/appenders/file_appender.rb

@@ -0,0 +1,72 @@
+module Tracing
+  # File Appender
+  class FileAppender < BaseAppender
+
+    class << self
+      def default_path
+        return if !@default_path
+        if !File.exists?(@default_path)
+          FileUtils.mkdir_p @default_path
+        end
+        @default_path
+      end
+            
+      def default_path=(path)
+        @default_path = path
+      end
+    end    
+
+    # file
+    def write_file(file, txt)
+      file = file_path(file)      
+      
+      write_mode = mode(file) 
+      File.open(file, write_mode) do |f|
+        f.puts txt
+      end   
+    end
+
+    def create_initial_file(file)
+    end
+
+    def insert_into_file(file, txt, marker_txt)
+      line = marker_txt
+
+      file = file_path(file)
+
+      if !File.exist?(file)
+        create_initial_file(file)
+      end  
+      
+      gsub_file file, /(#{Regexp.escape(line)})/mi do |match|
+        "#{txt}\n#{match}"
+      end
+    end
+
+    # helper for deciding file "write mode"
+    def is_old_file?(file)
+      File.new(file).mtime < (Time.now - time_limit)
+    end
+
+    def file_path(file)
+      file = File.join(self.class.default_path, file) if self.class.default_path      
+    end
+
+protected
+    def gsub_file(path, regexp, *args, &block)
+      content = File.read(path).gsub(regexp, *args, &block)
+      File.open(path, 'wb') { |file| file.write(content) }
+    end
+
+    # default file "write mode"
+    def mode(file)
+      if !options[:overwrite] && File.exist?(file) && !is_old_file?(file)
+        "a+"
+      else
+        "w+"
+      end
+    end
+    
+  end # class
+    
+end # tracing