vcap_logging 0.1.4

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
+task :spec do
+  desc 'Run tests'
+  sh('bundle install')
+  sh('cd spec && rake spec')
+end

data/lib/vcap/logging/error.rb

@@ -0,0 +1,5 @@
+module VCAP
+  module Logging
+    class LoggingError < StandardError; end
+  end
+end

data/lib/vcap/logging/formatter/base_formatter.rb

@@ -0,0 +1,30 @@
+require 'vcap/logging/log_record'
+
+module VCAP
+  module Logging
+    module Formatter
+
+      # Formatters are responsible for taking a log record and
+      # producing a string representation suitable for writing to a sink.
+      #
+      class BaseFormatter
+        # Produces a string suitable for writing to a sink
+        #
+        # @param  log_record  VCAP::Logging::LogRecord  Log record to be formatted
+        # @return String
+        def format_record(log_record)
+          raise NotImplementedError
+        end
+
+        # The inverse of format_record()
+        #
+        # @param  message  String  A string formatted using format_record()
+        # @return VCAP::Logging::LogRecord
+        def parse_message(message)
+          raise NotImplementedError
+        end
+      end
+
+    end
+  end
+end

data/lib/vcap/logging/formatter/delimited_formatter.rb

@@ -0,0 +1,96 @@
+require 'vcap/logging/formatter/base_formatter'
+require 'vcap/logging/log_record'
+
+module VCAP::Logging::Formatter
+
+  # A formatter for creating messages delimited by a given value (e.g. space separated logs)
+  class DelimitedFormatter < BaseFormatter
+
+    DEFAULT_DELIMITER        = ' '
+    DEFAULT_TIMESTAMP_FORMAT = '%F %T %z' # YYYY-MM-DD HH:MM:SS TZ
+
+    # This provides a tiny DSL for constructing the formatting function. We opt
+    # to define the method inline in order to avoid incurring multiple method calls
+    # per call to format_record().
+    #
+    # Usage:
+    #
+    # formatter = VCAP::Logging::Formatter::DelimitedFormatter.new do
+    #   timestamp '%s'
+    #   log_level
+    #   data
+    # end
+    #
+    # @param  delim  String   Delimiter that will separate fields in the message
+    # @param         Block    Block that defines the log message format
+    def initialize(delim=DEFAULT_DELIMITER, &blk)
+      @exprs = []
+
+      # Collect the expressions we want to use when constructing messages in the
+      # order that they should appear.
+      instance_eval(&blk)
+
+      # Build the format string to that will generate the message along with
+      # the arguments
+      fmt_chars = @exprs.map {|e| e[0] }
+      fmt       = fmt_chars.join(delim) + "\n"
+      fmt_args  = @exprs.map {|e| e[1] }.join(', ')
+
+      instance_eval("def format_record(log_record); '#{fmt}' % [#{fmt_args}]; end")
+    end
+
+    private
+
+    def log_level
+      @exprs << ['%6s', "log_record.log_level.to_s.upcase"]
+    end
+
+    def data
+      # Not sure of a better way to do this...
+      # If we are given an exception, include the class name, string representation, and stacktrace
+      snippet = "(log_record.data.kind_of?(Exception) ? " \
+                + "log_record.data.class.to_s + '(\"' + log_record.data.to_s + '\", [' + (log_record.data.backtrace ? log_record.data.backtrace.join(',') : '') + '])'" \
+                + ": log_record.data.to_s" \
+                + ").gsub(/\n/, '\\n')"
+      @exprs << ['%s', snippet]
+    end
+
+    def tags
+      @exprs << ['%s', "log_record.tags.empty? ? '-': log_record.tags.join(',')"]
+    end
+
+    def fiber_id
+      @exprs << ['%s', "log_record.fiber_id"]
+    end
+
+    def fiber_shortid
+      @exprs << ['%s', "log_record.fiber_shortid"]
+    end
+
+    def process_id
+      @exprs << ['%s', "log_record.process_id"]
+    end
+
+    def thread_id
+      @exprs << ['%s', "log_record.thread_id"]
+    end
+
+    def thread_shortid
+      @exprs << ['%s', "log_record.thread_shortid"]
+    end
+
+    def timestamp(fmt=DEFAULT_TIMESTAMP_FORMAT)
+      @exprs << ['%s', "log_record.timestamp.strftime('#{fmt}')"]
+    end
+
+    def logger_name
+      @exprs << ['%s', "log_record.logger_name"]
+    end
+
+    def text(str)
+      @exprs << ['%s', "'#{str}'"]
+    end
+
+  end
+
+end

data/lib/vcap/logging/formatter.rb

@@ -0,0 +1,2 @@
+require 'vcap/logging/formatter/base_formatter'
+require 'vcap/logging/formatter/delimited_formatter'

data/lib/vcap/logging/log_record.rb

@@ -0,0 +1,71 @@
+require 'digest/md5'
+require 'thread'
+
+module VCAP
+  module Logging
+
+    class LogRecord
+
+      @@have_fibers = nil
+
+      class << self
+
+        def have_fibers?
+          if @@have_fibers == nil
+            begin
+              require 'fiber'
+              @@have_fibers = true
+            rescue LoadError
+              @@have_fibers = false
+            end
+          else
+            @@have_fibers
+          end
+        end
+
+        def current_fiber_id
+          if have_fibers?
+            Fiber.current.object_id
+          else
+            nil
+          end
+        end
+
+      end
+
+      attr_reader :timestamp
+      attr_reader :data
+      attr_reader :log_level
+      attr_reader :logger_name
+      attr_reader :tags
+      attr_reader :thread_id
+      attr_reader :thread_shortid
+      attr_reader :fiber_id
+      attr_reader :fiber_shortid
+      attr_reader :process_id
+
+      def initialize(log_level, data, logger, tags=[])
+        @timestamp   = Time.now
+        @data        = data
+        @logger_name = logger.name
+        @log_level   = log_level
+        @tags        = tags
+
+        @thread_id      = Thread.current.object_id
+        @thread_shortid = shortid(@thread_id)
+        @fiber_id       = LogRecord.current_fiber_id
+        @fiber_shortid  = @fiber_id ? shortid(@fiber_id) : nil
+        @process_id     = Process.pid
+      end
+
+      private
+
+      def shortid(data, len=4)
+        digest = Digest::MD5.hexdigest(data.to_s)
+        len = len > digest.length ? digest.length : len
+        digest[0, len]
+      end
+
+    end # VCAP::Logging::LogRecord
+  end
+end

data/lib/vcap/logging/logger.rb

@@ -0,0 +1,116 @@
+require 'vcap/logging/log_record'
+
+module VCAP
+  module Logging
+    class Logger
+
+      # Loggers are responsible for dispatching log messages to an appropriate
+      # sink.
+
+      LogLevel = Struct.new(:name, :value)
+
+      class << self
+        attr_reader :log_levels
+
+        # Defines convenience methods for each log level. For example, if 'debug' is the name of a level
+        # corresponding 'debug' and 'debugf' instance methods will be defined for all loggers.
+        #
+        # @param  levels  Array[VCAP::Logging::LogLevel]  Log levels to use
+        def define_log_levels(levels)
+
+          @prev_log_methods ||= []
+          # Clean up previously defined methods
+          for meth_name in @prev_log_methods
+            undef_method(meth_name)
+          end
+
+          @prev_log_methods = []
+          @log_levels       = {}
+
+          # Partially evaluate log/logf for the level specified by each name
+          for name, level in levels
+            @log_levels[name] = LogLevel.new(name, level)
+
+            define_log_helper(name)
+            @prev_log_methods << name
+
+            name_f = "#{name}f".to_sym
+            define_logf_helper(name_f, name)
+            @prev_log_methods << name_f
+          end
+        end
+
+        private
+
+        # Helper methods for defining helper methods (look out, you might be getting incepted...)
+        # Needed in order to create a new scope when binding level to the blocks
+
+        def define_log_helper(level)
+          define_method(level) {|*args| log(level, *args) }
+        end
+
+        def define_logf_helper(name, level)
+          define_method(name) {|*args| logf(level, *args) }
+        end
+
+      end
+
+      attr_reader   :name
+      attr_accessor :sink_map
+
+      def initialize(name, sink_map)
+        @name = name
+        @sink_map = sink_map
+      end
+
+      def log_level
+        @log_level.name
+      end
+
+      def log_level=(lvl_name)
+        level = self.class.log_levels[lvl_name]
+        raise ArgumentError, "Unknown level #{lvl_name}" unless level
+        @log_level = level
+
+        self
+      end
+
+      # Logs a message to the configured sinks. You may optionally supply a block to be called; its return value
+      # will be used as data for the log record.
+      #
+      # @param  lvl_name  Symbol  Log level for the associated message
+      # @param  data      Object      Optional data to log. How this is converted to a string is determined by the formatters.
+      # @param  opts      Hash      :tags => Array[String]  Tags to associated with this log message
+      def log(lvl_name, data=nil, opts={})
+        level = self.class.log_levels[lvl_name]
+        raise ArgumentError, "Unknown level #{lvl_name}" unless level
+
+        return unless level.value <= @log_level.value
+        data = yield if block_given?
+        tags = opts[:tags] || []
+        tags << :exception if data.kind_of?(Exception)
+
+        rec = VCAP::Logging::LogRecord.new(lvl_name, data, self, tags)
+        @sink_map.get_sinks(lvl_name).each {|s| s.add_record(rec) }
+      end
+
+      # Logs a message to the configured sinks. This is analogous to the printf() family
+      #
+      # @param  lvl_name  Symbol  Log level for the associated message
+      # @param  fmt       String  Format string to use when formatting the message
+      # @param  fmt_args  Array   Arguments to format string
+      # @param  opts      Hash    See log()
+      def logf(lvl_name, fmt, fmt_args, opts={})
+        level = self.class.log_levels[lvl_name]
+        raise ArgumentError, "Unknown level #{lvl_name}" unless level
+
+        return unless level.value <= @log_level.value
+        data = fmt % fmt_args
+
+        rec = VCAP::Logging::LogRecord.new(lvl_name, data, self, opts[:tags] || [])
+        @sink_map.get_sinks(lvl_name).each {|s| s.add_record(rec) }
+      end
+
+    end # VCAP::Logging::Logger
+  end
+end

data/lib/vcap/logging/sink/base_sink.rb

@@ -0,0 +1,83 @@
+require 'thread'
+
+require 'vcap/logging/error'
+require 'vcap/logging/log_record'
+
+module VCAP
+  module Logging
+    module Sink
+
+      class SinkError  < VCAP::Logging::LoggingError; end
+      class UsageError < SinkError;                   end
+
+      # Sinks serve as the final destination for log records.
+      # Usually they are lightweight wrappers around other objects that perform IO (files and sockets come to mind).
+
+      class BaseSink
+        attr_reader   :opened
+        attr_accessor :formatter
+        attr_accessor :autoflush
+
+        def initialize(formatter=nil)
+          @formatter = formatter
+          @opened    = false
+          @mutex     = Mutex.new
+          @autoflush = false
+        end
+
+        # Opens any underlying file descriptors, etc. and ensures that the sink
+        # is capable of receiving records.
+        #
+        # This MUST be called before any calls to add_record().
+        def open
+          @mutex.synchronize { @opened = true }
+        end
+
+        # Closes any underlying file descriptors and ensures that any log records
+        # buffered in memory are flushed.
+        def close
+          @mutex.synchronize { @opened = false }
+        end
+
+        def autoflush=(should_autoflush)
+          @autoflush = should_autoflush
+          flush if @autoflush
+        end
+
+        # Formats the log record using the configured formatter and
+        # NB: Depending on the implementation of write(), this may buffer the record in memory.
+        #
+        # @param  log_record  VCAP::Logging::LogRecord  Record to add
+        def add_record(log_record)
+          raise UsageError, "You cannot add a record until the sink has been opened" unless @opened
+          raise UsageError, "You must supply a formatter" unless @formatter
+
+          message = @formatter.format_record(log_record)
+          write(message)
+          flush if @autoflush
+        end
+
+        # Flushes any log records that may have been buffered in memory
+        def flush
+          nil
+        end
+
+        private
+
+        # Writes the formatted log message to the underlying device
+        #
+        # NB: Implementations MUST:
+        #   - Be thread-safe.
+        #   - Handle all exceptions that may occur when writing a message.
+        #     An appropriate strategy could be as simple as logging the exception to standard error.
+        #
+        # @param  log_message  String  Message to write
+        def write(log_message)
+          raise NotImplementedError
+        end
+
+      end # VCAP::Logging::Sink::BaseSink
+
+    end
+  end
+end

data/lib/vcap/logging/sink/file_sink.rb

@@ -0,0 +1,120 @@
+module VCAP::Logging::Sink
+
+  # A sink for writing to a file. Buffering is supported, but disabled by default.
+  class FileSink < BaseSink
+
+    attr_reader :filename
+
+    class MessageBuffer
+      attr_reader :size
+      attr_accessor :max_buffer_size
+
+      def initialize(buffer_size)
+        @max_buffer_size = buffer_size
+        @buffer = []
+        @size   = 0
+      end
+
+      def append(msg)
+        @buffer << msg
+        @size += msg.length
+      end
+
+      def compact
+        return nil unless @size > 0
+        ret = @buffer.join
+        @buffer = []
+        @size = 0
+        ret
+      end
+
+      def full?
+        @size >= @max_buffer_size
+      end
+
+      def empty?
+        @size == 0
+      end
+    end
+
+    # @param  filename  String         Pretty obvious...
+    # @param  formatter BaseFormatter  Formatter to use when generating log messages
+    # @param  opts      Hash           :buffer_size  =>  Size (in bytes) to buffer in memory before flushing to disk
+    #
+    def initialize(filename, formatter=nil, opts={})
+      super(formatter)
+
+      @filename = filename
+      @file     = nil
+      if opts[:buffer_size] && (Integer(opts[:buffer_size]) > 0)
+        @buffer = MessageBuffer.new(opts[:buffer_size])
+      else
+        @buffer = nil
+      end
+      open()
+    end
+
+    # Missing Python's decorators pretty badly here. Even guards would be better than the existing solution.
+    # Alas, ruby has no real destructors.
+
+    def open
+      @mutex.synchronize do
+        if !@opened
+          @file = File.new(@filename, 'a+')
+          @file.sync = true
+          @opened = true
+        end
+      end
+    end
+
+    def close
+      @mutex.synchronize do
+        if @opened
+          perform_write(@buffer.compact) if @buffer && !@buffer.empty?
+          @file.close
+          @file = nil
+          @opened = false
+        end
+      end
+    end
+
+    def flush
+      @mutex.synchronize do
+        perform_write(@buffer.compact) if @buffer && !@buffer.empty?
+      end
+    end
+
+    private
+
+    def write(message)
+      @mutex.synchronize do
+        if @buffer
+          @buffer.append(message)
+          perform_write(@buffer.compact) if @buffer.full?
+        else
+          perform_write(message)
+        end
+      end
+    end
+
+    def perform_write(message)
+      bytes_left = message.length
+      begin
+        while bytes_left > 0
+          written = @file.syswrite(message)
+          bytes_left -= written
+          message = message[written, message.length - written] if bytes_left
+        end
+      rescue Errno::EINTR
+          # This can only happen if the write is interrupted before any data is written.
+          # If a partial write occurs due to an interrupt write(2) will return the number of bytes written
+          # instead of -1.
+          #
+          # The rest of the exceptions that syswrite() can throw cannot be recovered from,
+          # and should be propagated up the stack. (See `man 2 write`.)
+          retry
+      end
+    end
+  end
+
+end