loggability 0.14.0 → 0.18.0

data/lib/loggability.rb

@@ -1,6 +1,6 @@
 # -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'logger'
 require 'date'
@@ -9,10 +9,7 @@ require 'date'
 module Loggability
 
 	# Package version constant
-	VERSION = '0.14.0'
-
-	# VCS revision
-	REVISION = %q$Revision: 500260d36bfb $
+	VERSION = '0.18.0'
 
 	# The key for the global logger (Loggability's own logger)
 	GLOBAL_KEY = :__global__
@@ -29,22 +26,28 @@ module Loggability
 	LOGSPEC_PATTERN = %r{
 		^
 			\s*
-			((?i:debug|info|warn|error|fatal))   # severity
+			(?<severity>(?i:debug|info|warn|error|fatal))
 		    (?:
 				\s+
-				((?:[\w\-/:\.]|\\[ ])+)
+				(?<target>(?:[\w\-/:\.\[\]]|\\[ ])+)
 			)?
 			(?: \s+\(
-				(\w+)
+				(?<format>\w+)
 			\) )?
 			\s*
 		$
 	}x
 
-	require 'loggability/constants'
-	include Loggability::Constants
 
-	require 'loggability/logger'
+	# Automatically load subordinate classes/modules
+	autoload :Constants, 'loggability/constants'
+	autoload :LogDevice, 'loggability/log_device'
+	autoload :Logger, 'loggability/logger'
+	autoload :LogHost, 'loggability/loghost'
+	autoload :LogClient, 'loggability/logclient'
+	autoload :Override, 'loggability/override'
+
+	include Loggability::Constants
 
 
 	##
@@ -58,18 +61,6 @@ module Loggability
 	@config = CONFIG_DEFAULTS.dup.freeze
 
 
-	# Automatically log the log host and log client mixins when they're referenced
-	autoload :LogHost, 'loggability/loghost'
-	autoload :LogClient, 'loggability/logclient'
-	autoload :Override, 'loggability/override'
-
-
-	### Return the library's version string
-	def self::version_string( include_buildnum=false )
-		vstring = "%s %s" % [ self.name, VERSION ]
-		vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
-		return vstring
-	end
 
 
 	### Cast the given +device+ to a Loggability::Logger, if possible, and return it. If
@@ -155,12 +146,12 @@ module Loggability
 
 	### Call the method with the given +methodname+ across the loggers of all loghosts with
 	### the given +arg+ and/or +block+.
-	def self::aggregate( methodname, arg, &block )
+	def self::aggregate( methodname, *args, &block )
 		# self.log.debug "Aggregating a call to %p with %p to %d log hosts" %
 		#	[ methodname, arg, Loggability.log_hosts.length ]
 		Loggability.log_hosts.values.each do |loghost|
 			# self.log.debug "  %p.logger.%s( %p )" % [ loghost, methodname, arg ]
-			loghost.logger.send( methodname, arg, &block )
+			loghost.logger.send( methodname, *args, &block )
 		end
 	end
 
@@ -200,8 +191,8 @@ module Loggability
 	#
 	# Aggregate method: set all loggers to log to +destination+. See Loggability::Logger#output_to
 	# for more info.
-	def self::output_to( newdevice )
-		self.aggregate( :output_to, newdevice )
+	def self::output_to( newdevice, *args )
+		self.aggregate( :output_to, newdevice, *args )
 	end
 	class << self
 		alias_method :write_to, :output_to
@@ -332,6 +323,7 @@ module Loggability
 		target = case target
 			when 'STDOUT' then $stdout
 			when 'STDERR' then $stderr
+			when /:/ then Loggability::LogDevice.parse_device_spec( target )
 			else
 				target
 			end

data/lib/loggability/constants.rb

@@ -1,6 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'logger'
 require 'loggability' unless defined?( Loggability )

data/lib/loggability/formatter.rb

@@ -1,6 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'loggability' unless defined?( Loggability )
 
@@ -8,21 +8,23 @@ require 'loggability' unless defined?( Loggability )
 ### An abstract base class for Loggability log formatters.
 class Loggability::Formatter
 
-	# The default sprintf pattern
-	DEFAULT_DATETIME_FORMAT = '%Y-%m-%d %H:%M:%S'
-
-
 	##
 	# Derivative classes, keyed by name
-	class << self; attr_reader :derivatives; end
+	singleton_class.attr_reader( :derivatives )
 	@derivatives = {}
 
 
 	### Inherited hook -- add subclasses to the ::derivatives Array.
 	def self::inherited( subclass )
 		super
-		classname = subclass.name.sub( /.*::/, '' ).downcase.to_sym
-		Loggability::Formatter.derivatives[ classname ] = subclass
+
+		if ( name = subclass.name )
+			classname = name.sub( /.*::/, '' ).downcase
+		else
+			classname = "anonymous_%d" % [ subclass.object_id ]
+		end
+
+		Loggability::Formatter.derivatives[ classname.to_sym ] = subclass
 	end
 
 
@@ -42,69 +44,13 @@ class Loggability::Formatter
 	end
 
 
-
-	### Initialize a new Loggability::Formatter. The specified +logformat+ should
-	### be a sprintf pattern with positional placeholders:
-	###
-	### [<tt>%1$s</tt>] Time (pre-formatted using strftime with the +datetime_format+)
-	### [<tt>%2$d</tt>] Time microseconds
-	### [<tt>%3$d</tt>] PID
-	### [<tt>%4$s</tt>] Thread ID
-	### [<tt>%5$s</tt>] Severity
-	### [<tt>%6$s</tt>] Object/Program Name
-	### [<tt>%7$s</tt>] Message
-	###
-	def initialize( logformat, datetime_format=DEFAULT_DATETIME_FORMAT )
-		@format          = logformat.dup
-		@datetime_format = datetime_format.dup
-	end
-
-
-	######
-	public
-	######
-
-	# Main log sprintf format
-	attr_accessor :format
-
-	# Strftime format for log messages
-	attr_accessor :datetime_format
-
-
 	### Create a log message from the given +severity+, +time+, +progname+, and +message+
 	### and return it.
 	def call( severity, time, progname, message )
-		timeformat = self.datetime_format
-		args = [
-			time.strftime( timeformat ),                                       # %1$s
-			time.usec,                                                         # %2$d
-			Process.pid,                                                       # %3$d
-			Thread.current == Thread.main ? 'main' : Thread.current.object_id, # %4$s
-			severity.downcase,                                                 # %5$s
-			progname,                                                          # %6$s
-			self.msg2str(message, severity)                                    # %7$s
-		]
-
-		return self.format % args
+		raise NotImplementedError, "%p doesn't implement required method %s" %
+			[ self.class, __method__ ]
 	end
 
 
-	#########
-	protected
-	#########
-
-	### Format the specified +msg+ for output to the log.
-	def msg2str( msg, severity )
-		case msg
-		when String
-			return msg
-		when Exception
-			bt = severity == 'DEBUG' ? msg.backtrace.join("\n") : msg.backtrace.first
-			return "%p: %s from %s" % [ msg.class, msg.message, bt ]
-		else
-			return msg.inspect
-		end
-	end
-
 end # class Loggability::Formatter
 

data/lib/loggability/formatter/color.rb

@@ -1,6 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'loggability' unless defined?( Loggability )
 require 'loggability/formatter' unless defined?( Loggability::Formatter )

data/lib/loggability/formatter/default.rb

@@ -1,20 +1,83 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'loggability' unless defined?( Loggability )
 require 'loggability/formatter' unless defined?( Loggability::Formatter )
 
 
-# The default log formatter class.
+# The default sprintf-based log formatter class.
 class Loggability::Formatter::Default < Loggability::Formatter
 
+	# The default sprintf pattern
+	DEFAULT_DATETIME_FORMAT = '%Y-%m-%d %H:%M:%S'
+
 	# The format to output unless debugging is turned on
 	FORMAT = "[%1$s.%2$06d %3$d/%4$s] %5$5s {%6$s} -- %7$s\n"
 
-	### Specify the format for the default formatter.
-	def initialize( format=FORMAT )
-		super
+	### Initialize a new Loggability::Formatter. The specified +logformat+ should
+	### be a sprintf pattern with positional placeholders:
+	###
+	### [<tt>%1$s</tt>] Time (pre-formatted using strftime with the +datetime_format+)
+	### [<tt>%2$d</tt>] Time microseconds
+	### [<tt>%3$d</tt>] PID
+	### [<tt>%4$s</tt>] Thread ID
+	### [<tt>%5$s</tt>] Severity
+	### [<tt>%6$s</tt>] Object/Program Name
+	### [<tt>%7$s</tt>] Message
+	###
+	def initialize( logformat=FORMAT, datetime_format=DEFAULT_DATETIME_FORMAT )
+		super()
+
+		@format          = logformat.dup
+		@datetime_format = datetime_format.dup
+	end
+
+
+	######
+	public
+	######
+
+	# Main log sprintf format
+	attr_accessor :format
+
+	# Strftime format for log messages
+	attr_accessor :datetime_format
+
+
+	### Create a log message from the given +severity+, +time+, +progname+, and +message+
+	### and return it.
+	def call( severity, time, progname, message )
+		timeformat = self.datetime_format
+		args = [
+			time.strftime( timeformat ),                                       # %1$s
+			time.usec,                                                         # %2$d
+			Process.pid,                                                       # %3$d
+			Thread.current == Thread.main ? 'main' : Thread.current.object_id, # %4$s
+			severity.downcase,                                                 # %5$s
+			progname,                                                          # %6$s
+			self.msg2str(message, severity)                                    # %7$s
+		]
+
+		return self.format % args
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Format the specified +msg+ for output to the log.
+	def msg2str( msg, severity )
+		case msg
+		when String
+			return msg
+		when Exception
+			bt = severity == 'DEBUG' ? msg.backtrace.join("\n") : msg.backtrace.first
+			return "%p: %s from %s" % [ msg.class, msg.message, bt ]
+		else
+			return msg.inspect
+		end
 	end
 
 end # class Loggability::Formatter::Default

data/lib/loggability/formatter/html.rb

@@ -1,13 +1,13 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen_string_literal: true
 
-require 'loggability' unless defined?( Loggability )
 require 'loggability/formatter' unless defined?( Loggability::Formatter )
+require 'loggability/formatter/default'
 
 
-# The default log formatter class.
-class Loggability::Formatter::HTML < Loggability::Formatter
+# Output logs as HTML
+class Loggability::Formatter::HTML < Loggability::Formatter::Default
 
 	# The default HTML fragment that'll be used as the template for each log message.
 	HTML_LOG_FORMAT = %q{

data/lib/loggability/formatter/structured.rb

@@ -0,0 +1,35 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# frozen_string_literal: true
+
+require 'time'
+require 'json'
+
+require 'loggability/formatter' unless defined?( Loggability::Formatter )
+
+
+# Output logs as JSON.
+class Loggability::Formatter::Structured < Loggability::Formatter
+
+	# The version of the format output
+	LOG_FORMAT_VERSION = 1
+
+
+	### Format a message of the specified +severity+ using the given +time+,
+	### +progname+, and +message+.
+	def call( severity, time, progname, message )
+		severity ||= 'DEBUG'
+		time ||= Time.now
+		entry = {
+			'@version' => LOG_FORMAT_VERSION,
+			'@timestamp' => time.iso8601( 3 ),
+			'level' => severity,
+			'progname' => progname,
+			'message' => message,
+		}
+
+		return JSON.generate( entry )
+	end
+
+end # class Loggability::Formatter::Default
+

data/lib/loggability/log_device.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'loggability' unless defined?( Loggability )
+
+
+# An abstract base class for logging devices. A device manages the actual writing of messages
+# to whatever destination logs are supposed to be shipped to, along with any buffering,
+# encoding, or serialization that needs to be done.
+#
+# Log devices are loadable by name via the ::create method if they are declared in a
+# directory named `loggability/log_device/` in the gem path.
+#
+# Concrete log devices are required to implement two methods: #write and #close.
+#
+# [write]
+#   Takes one argument, which is the message that needs to be written.
+#
+# [close]
+#   Close any open filehandles or connections established by the device.
+class Loggability::LogDevice
+
+
+	# Regexp used to split up logging devices in config lines
+	DEVICE_TARGET_REGEX = /^([\s*a-z]\w*)(?:\[(.*)\])?/
+
+
+	### Parses out the target class name and its arguments from the +target_spec+
+	### then requires the subclass and instantiates it by passing the arguments.
+	### The +target_spec+ comes from a config file in the format of:
+	###
+	###   logging:
+	###     datadog[data_dog_api_key]
+	###
+	### In the above example:
+	### * "datadog" is the log device to send logs to
+	### * "data_dog_api_key" is the argument that will be passed onto the datadog
+	###   log device's constructor
+	def self::parse_device_spec( target_spec )
+		targets = target_spec.split( ';' ).compact
+		return targets.map do |t|
+			target_subclass = t[ DEVICE_TARGET_REGEX, 1 ]&.strip.to_sym
+			target_subclass_args = t[ DEVICE_TARGET_REGEX, 2 ]
+
+			self.create( target_subclass, target_subclass_args )
+		end
+	end
+
+
+	### Requires the subclass and instantiates it with the passed-in arguments and
+	### then returns an instance of it.
+	def self::create( target, *target_args )
+		modname = target.to_s.capitalize
+
+		self.load_device_type( target ) unless self.const_defined?( modname, false )
+		subclass = self.const_get( modname, false )
+
+		return subclass.new( *target_args )
+	rescue NameError => err
+		raise LoadError, "failed to load %s LogDevice: %s" % [ target, err.message ]
+	end
+
+
+	### Attempt to load a LogDevice of the given +type+.
+	def self::load_device_type( type )
+		require_path = "loggability/log_device/%s" % [ type.to_s.downcase ]
+		require( require_path )
+	end
+
+
+	### Write a +message+ to the device. This needs to be overridden by concrete
+	### subclasses; calling this implementation will raise an NotImplementedError.
+	def write( message )
+		raise NotImplementedError, "%s is not implemented by %s" % [ __callee__, self.class.name ]
+	end
+
+
+	### Close the device. This needs to be overridden by concrete subclasses;
+	### calling this implementation will raise an NotImplementedError.
+	def close
+		raise NotImplementedError, "%s is not implemented by %s" % [ __callee__, self.class.name ]
+	end
+
+end # class Loggability::LogDevice
+