vcap_logging 0.1.4

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

@@ -0,0 +1,25 @@
+require 'vcap/logging/sink/base_sink'
+
+module VCAP::Logging::Sink
+
+  # A sink for writing to stderr/stdout
+  # Usage:
+  #   stdout_sink = VCAP::Logging::Sink::StdioSink.new(STDOUT)
+  #
+  class StdioSink < BaseSink
+    def initialize(io, formatter=nil)
+      super(formatter)
+      @io  = io
+      open
+    end
+
+    private
+
+    def write(message)
+      @mutex.synchronize do
+        @io.write(message)
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,18 @@
+require 'vcap/logging/sink/base_sink'
+
+module VCAP::Logging::Sink
+
+  # A sink for writing data to a string. Useful if you want to capture logs
+  # in memory along with writing to a file.
+  class StringSink < BaseSink
+    def initialize(str, formatter=nil)
+      super(formatter)
+      @str = str
+      open
+    end
+
+    def write(message)
+      @mutex.synchronize { @str << message }
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+require 'syslog'
+
+require 'vcap/logging/sink/base_sink'
+
+module VCAP::Logging::Sink
+
+  # A sink for logging messages to the local syslog server.
+  # NB: The ruby syslog module is a thin wrapper around glibc syslog(). It will first
+  #     attempt to open a unix stream socket to '/dev/log', and upon failure will attempt
+  #     to open a unix datagram socket there. Make sure you configure your syslog server
+  #     to use the appropriate type (probably dgram in our case).
+  #
+  #     Beware that all messages will be silently lost if the syslog server goes away.
+  class SyslogSink < BaseSink
+
+    DEFAULT_LOG_LEVEL_MAP = {
+      :fatal  => Syslog::LOG_CRIT,
+      :error  => Syslog::LOG_ERR,
+      :warn   => Syslog::LOG_WARNING,
+      :info   => Syslog::LOG_INFO,
+      :debug  => Syslog::LOG_DEBUG,
+      :debug1 => Syslog::LOG_DEBUG,
+      :debug2 => Syslog::LOG_DEBUG,
+    }
+
+    # @param  prog_name  String  Program name to identify lines logged to syslog
+    # @param  opts       Hash    :log_level_map  Map of log level => syslog level
+    #                            :formatter      LogFormatter
+    def initialize(prog_name, opts={})
+      super(opts[:formatter])
+
+      @prog_name     = prog_name
+      @log_level_map = opts[:log_level_map] || DEFAULT_LOG_LEVEL_MAP
+      @syslog        = nil
+      open
+    end
+
+    def open
+      @mutex.synchronize do
+        unless @opened
+          @syslog = Syslog.open(@prog_name, Syslog::LOG_PID, Syslog::LOG_USER)
+          @opened = true
+        end
+      end
+    end
+
+    def close
+      @mutex.synchronize do
+        if @opened
+          @syslog.close
+          @syslog = nil
+          @opened = false
+        end
+      end
+    end
+
+    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)
+      pri = @log_level_map[log_record.log_level]
+      @mutex.synchronize { @syslog.log(pri, '%s', message) }
+    end
+
+  end
+end

data/lib/vcap/logging/sink.rb

@@ -0,0 +1,5 @@
+require 'vcap/logging/sink/base_sink'
+require 'vcap/logging/sink/file_sink'
+require 'vcap/logging/sink/stdio_sink'
+require 'vcap/logging/sink/string_sink'
+require 'vcap/logging/sink/syslog_sink'

data/lib/vcap/logging/sink_map.rb

@@ -0,0 +1,62 @@
+require 'set'
+
+module VCAP
+  module Logging
+    class SinkMap
+
+      # @param  log_levels  Hash  Map of level_name => value
+      def initialize(log_levels)
+        @log_levels = log_levels
+        @sinks      = {}
+        for level in @log_levels.keys
+          @sinks[level] = []
+        end
+      end
+
+      # Adds a sink for all the levels in the supplied range
+      #
+      # Usage:
+      #   add_sink(nil,   :debug, sink)  # Add a sink for all levels up to, and including, the :debug level
+      #   add_sink(:info, :info,  sink)  # Add a sink for only the info level
+      #   add_sink(:warn, nil,    sink)  # Add a sink for all levels :warn and greater
+      #   add_sink(nil,   nil,    sink)  # Add a sink for all levels
+      #
+      # @param  start_level  Symbol    The most noisy level you want this sink to apply to. Use nil to set no restriction.
+      # @param  end_level    Symbol    The least noisy level you want this sink to apply to. Use nil to set no restriction.
+      # @param  sink         BaseSink  The sink to add
+      def add_sink(start_level, end_level, sink)
+        raise ArgumentError, "Unknown level #{start_level}" if start_level && !@log_levels.has_key?(start_level)
+        raise ArgumentError, "Unknown level #{end_level}" if end_level && !@log_levels.has_key?(end_level)
+
+        start_value = @log_levels[start_level]
+        end_value   = @log_levels[end_level]
+
+        for level, value in @log_levels
+          next if start_value && (value > start_value)
+          next if end_value && (value < end_value)
+          @sinks[level] << sink
+        end
+      end
+
+      # @param  level  :Symbol  Log level to retrieve sinks for
+      # @return Array
+      def get_sinks(level)
+        @sinks[level]
+      end
+
+      def each_sink
+        raise "You must supply a block" unless block_given?
+
+        seen = Set.new
+        for level, sinks in @sinks
+          for sink in sinks
+            next if seen.include?(sink)
+            yield sink
+            seen.add(sink)
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/vcap/logging/version.rb

@@ -0,0 +1,5 @@
+module VCAP
+  module Logging
+    VERSION = '0.1.4'
+  end
+end

data/lib/vcap/logging.rb

@@ -0,0 +1,160 @@
+require 'vcap/logging/error'
+require 'vcap/logging/formatter'
+require 'vcap/logging/log_record'
+require 'vcap/logging/logger'
+require 'vcap/logging/sink'
+require 'vcap/logging/sink_map'
+require 'vcap/logging/version'
+
+module VCAP
+  module Logging
+
+    FORMATTER = VCAP::Logging::Formatter::DelimitedFormatter.new do
+      timestamp '[%F %T]'
+      logger_name
+      tags
+      process_id
+      thread_shortid
+      fiber_shortid
+      log_level
+      text '--'
+      data
+    end
+
+    LOG_LEVELS = {
+      :off    => 0,
+      :fatal  => 1,
+      :error  => 5,
+      :warn   => 10,
+      :info   => 15,
+      :debug  => 16,
+      :debug1 => 17,
+      :debug2 => 18,
+    }
+
+    class << self
+
+      attr_reader :default_log_level
+
+      def init
+        fail "init() can only be called once" if @initialized
+        reset
+
+        # Ideally we would call close() on each sink. Unfortunatley, we can't be sure
+        # that close runs last, and that other at_exit handlers aren't attempting to
+        # log to a sink. The best we can do is enable autoflushing.
+        at_exit do
+          @sink_map.each_sink {|s| s.autoflush = true }
+        end
+
+        @initialized = true
+      end
+
+      # Exists primarily for testing
+      def reset
+        VCAP::Logging::Logger.define_log_levels(LOG_LEVELS)
+        @default_log_level = pick_default_level(LOG_LEVELS)
+        @sink_map = VCAP::Logging::SinkMap.new(LOG_LEVELS)
+        @log_level_filters = {}
+        @sorted_log_level_filters = []
+        @loggers  = {}
+      end
+
+      def default_log_level=(log_level_name)
+        log_level_name = log_level_name.to_sym if log_level_name.kind_of?(String)
+        raise ArgumentError, "Unknown level #{log_level_name}" unless LOG_LEVELS[log_level_name]
+        @default_log_level = log_level_name
+      end
+
+      # Configures the logging infrastructure using a hash parsed from a config file.
+      # The config file is expected to contain a section with the following format:
+      # logging:
+      #    level: <default_log_level>
+      #     file: <filename>
+      #   syslog: <program name to use with the syslog sink>
+      #
+      # This interface is limiting, but it should satisfy the majority of our use cases.
+      # I'm imagining usage will be something like:
+      #   config = YAML.load(<file>)
+      #   ...
+      #   VCAP::Logging.setup_from_config(config[:logging])
+      def setup_from_config(config={})
+        level = config[:level] || config['level']
+        if level
+          level_sym = level.to_sym
+          raise ArgumentError, "Unknown level: #{level}" unless LOG_LEVELS[level_sym]
+          @default_log_level = level_sym
+        end
+
+        logfile = config[:file] || config['file']
+        # Undecided as to whether or not we should enable buffering here. For now, don't buffer to stay consistent with the current logger.
+        add_sink(nil, nil, VCAP::Logging::Sink::FileSink.new(logfile, FORMATTER)) if logfile
+
+        syslog_name = config[:syslog] || config['syslog']
+        add_sink(nil, nil, VCAP::Logging::Sink::SyslogSink.new(syslog_name, :formatter => FORMATTER)) if syslog_name
+
+        # Log to stdout if no other sinks are supplied
+        add_sink(nil, nil, VCAP::Logging::Sink::StdioSink.new(STDOUT, FORMATTER)) unless (logfile || syslog_name)
+      end
+
+      # Returns the logger associated with _name_. Creates one if it doesn't exist. The log level will be inherited
+      # from the parent logger.
+      #
+      # @param  name  String  Logger name
+      def logger(name)
+        if !@loggers.has_key?(name)
+          @loggers[name] = VCAP::Logging::Logger.new(name, @sink_map)
+          @loggers[name].log_level = @default_log_level
+          for level, regex in @sorted_log_level_filters
+            if regex.match(name)
+              @loggers[name].log_level = level
+              break
+            end
+          end
+        end
+
+        @loggers[name]
+      end
+
+      def add_sink(*args)
+        @sink_map.add_sink(*args)
+      end
+
+      # Sets the log level to _log_level_ for every logger whose name matches _path_regex_. Loggers who
+      # were previously set to this level and whose names no longer match _path_regex_ are reset to
+      # the default level.
+      #
+      # @param  path_regex      String  Regular expression to use when matching against the logger name
+      # @param  log_level_name  Symbol  Name of the log level to set on all matching loggers
+      def set_log_level(path_regex, log_level_name)
+        log_level_name = log_level_name.to_sym if log_level_name.kind_of?(String)
+
+        raise ArgumentError, "Unknown log level #{log_level_name}" unless LOG_LEVELS[log_level_name]
+        regex = Regexp.new("^#{path_regex}$")
+
+        @log_level_filters[log_level_name] = regex
+        @sorted_log_level_filters = @log_level_filters.keys.sort {|a, b| LOG_LEVELS[a] <=> LOG_LEVELS[b] }.map {|lvl| [lvl, @log_level_filters[lvl]] }
+
+        for logger_name, logger in @loggers
+          if regex.match(logger_name)
+            logger.log_level = log_level_name
+          elsif logger.log_level == log_level_name
+            # Reset any loggers at the supplied level that no longer match
+            logger.log_level = @default_log_level
+          end
+        end
+      end
+
+      private
+
+      # The middle level seems like a reasonable default
+      def pick_default_level(level_map)
+        sorted_levels = level_map.keys.sort {|a, b| level_map[a] <=> level_map[b] }
+        sorted_levels[sorted_levels.length / 2]
+      end
+
+    end # << self
+  end   # VCAP::Logging
+end
+
+VCAP::Logging.init

data/spec/Rakefile

@@ -0,0 +1,15 @@
+BASE_DIR = File.expand_path(File.join('..', '..'), __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.join(BASE_DIR, 'Gemfile')
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = '**/*_spec.rb'
+  t.rspec_opts = ['--color', '--format nested']
+end
+
+task :default => [:spec]

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rspec/core'
+
+$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+require 'vcap/logging'

data/spec/unit/base_sink_spec.rb

@@ -0,0 +1,38 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe VCAP::Logging::Sink::BaseSink do
+  before :each do
+    @sink = VCAP::Logging::Sink::BaseSink.new
+    @rec = VCAP::Logging::LogRecord.new(:info, 'foo', VCAP::Logging::Logger.new('bar', nil), [])
+  end
+
+  describe '#add_record' do
+    it 'should raise an exception if called before the sink is open' do
+      lambda { @sink.add_record(@rec) }.should raise_error(VCAP::Logging::Sink::UsageError)
+    end
+
+    it 'should raise an exception if called when a formatter has not been set for the sink' do
+      @sink.open
+      lambda { @sink.add_record(@rec) }.should raise_error(VCAP::Logging::Sink::UsageError)
+    end
+  end
+
+  describe '#autoflush' do
+    it 'should immediately call flush when set to true' do
+      @sink.formatter = mock(:formatter)
+      @sink.should_receive(:flush)
+      @sink.open
+      @sink.autoflush = true
+    end
+
+    it 'should call flush after each add_record call if true' do
+      @sink.formatter = mock(:formatter)
+      @sink.formatter.should_receive(:format_record).with(@rec).and_return('foo')
+      @sink.should_receive(:write).with('foo')
+      @sink.should_receive(:flush).twice
+      @sink.open
+      @sink.autoflush = true
+      @sink.add_record(@rec)
+    end
+  end
+end

data/spec/unit/delimited_formatter_spec.rb

@@ -0,0 +1,44 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe VCAP::Logging::Formatter::DelimitedFormatter do
+  describe '#initialize' do
+
+    it 'should define a format_record' do
+      fmt = VCAP::Logging::Formatter::DelimitedFormatter.new {}
+      fmt.respond_to?(:format_record).should be_true
+    end
+
+  end
+
+  describe '#format_record' do
+    it 'should return a correctly formatted message' do
+      rec = VCAP::Logging::LogRecord.new(:debug, 'foo', VCAP::Logging::Logger.new('foo', nil), ['bar', 'baz'])
+      fmt = VCAP::Logging::Formatter::DelimitedFormatter.new('.') do
+        timestamp '%s'
+        log_level
+        tags
+        process_id
+        thread_id
+        data
+      end
+
+      fmt.format_record(rec).should == [rec.timestamp.strftime('%s'), ' DEBUG', 'bar,baz', rec.process_id.to_s, rec.thread_id.to_s, 'foo'].join('.') + "\n"
+    end
+
+    it 'should encode newlines' do
+      rec = VCAP::Logging::LogRecord.new(:debug, "test\ning123\n\n", VCAP::Logging::Logger.new('foo', nil), [])
+      fmt = VCAP::Logging::Formatter::DelimitedFormatter.new('.') { data }
+      fmt.format_record(rec).should == "test\\ning123\\n\\n\n"
+    end
+
+    it 'should format exceptions' do
+      begin
+        raise StandardError, "Testing 123"
+      rescue => exc
+      end
+      rec = VCAP::Logging::LogRecord.new(:error, exc, VCAP::Logging::Logger.new('foo', nil), [])
+      fmt = VCAP::Logging::Formatter::DelimitedFormatter.new('.') { data }
+      fmt.format_record(rec).should == "StandardError(\"Testing 123\", [#{exc.backtrace.join(',')}])\n"
+    end
+  end
+end