loggability 0.15.1 → 0.18.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dd5d6f5605a1a639a0143107b4079272e35bb7ffba9e2b76b150c1fab57e11f
-  data.tar.gz: aef9016eb5f208d0d168d8e4aac0b03047851b582f8afcb437b37bb9f9b5ad4d
+  metadata.gz: 1b2c4fcb2846387b2e46bb742c60358c79cad2569644325e3db8995bfc4f1367
+  data.tar.gz: 8ee45fa6eaf6cfea8d84d8410877bd90053d71a4d692f0a391209d14702430d7
 SHA512:
-  metadata.gz: e14c6919279635835bd126a7c878ef69149811640cd4c632022e1677c18abfb3ebadc67fe8a12e9d35e35a94296e2c3ca32614c0c998ed9089b8e9b72d25ec56
-  data.tar.gz: d2481edb5e1a26dcc7f2a78420831d127b9951dd36e02e898bbd7fded829895083071627d9d78616fbad692937eb05edbdd39456efa0034aae4647cce597c484
+  metadata.gz: bcc3cc14f69340ca900ccd458c57e6a85d1b6b895614843ca9427e061f43320ccc7149034091afb0c4ff2bf3ada6a6dcbd05e4f94432224e3bd38b0a6ad1c6b1
+  data.tar.gz: c451e216cd87c63794169f0932650f34f78ae99a0eda842497fbef91df1eaf2564500a6160bdf10eb73f81d900cb320f81d4f207e03f0360c8b3df98a92345cb

data/History.rdoc

@@ -2,6 +2,53 @@
 
 ---
 
+== v0.18.2 [2020-12-28] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Make the version spec even less specific.
+
+
+== v0.18.1 [2020-12-28] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Change version spec to work with Ruby 3 versions.
+
+
+== v0.18.0 [2020-12-24] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add memory management to the http log device
+- Add a dead-simple log server example
+- Update for Ruby 3, add my updated gem cert
+
+Thanks again to Mahmood Khan <mkhan1484@gmail.com> for the patch.
+
+
+== v0.17.0 [2020-02-27] Michael Granger <ged@faeriemud.org>
+
+Bugfixes:
+
+- Fix the construction of the client in the http log device
+
+Improvements:
+
+- Add support for log devices to the aggregate #output_to
+
+
+
+== v0.16.0 [2020-02-24] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Expose a "log device" API and add the ability to write to multiple devices
+- Add a device for logging to an HTTP service
+
+Thanks to Mahmood Khan <mkhan1484@gmail.com> for the patch.
+
+
 == v0.15.1 [2020-01-09] Michael Granger <ged@faeriemud.org>
 
 Bugfixes:

data/Manifest.txt

@@ -1,9 +1,5 @@
 .simplecov
-ChangeLog
 History.rdoc
-Manifest.txt
-README.md
-Rakefile
 lib/loggability.rb
 lib/loggability/constants.rb
 lib/loggability/formatter.rb
@@ -14,8 +10,16 @@ lib/loggability/formatter/structured.rb
 lib/loggability/logclient.rb
 lib/loggability/logger.rb
 lib/loggability/loghost.rb
+lib/loggability/log_device.rb
+lib/loggability/log_device/appending.rb
+lib/loggability/log_device/datadog.rb
+lib/loggability/log_device/file.rb
+lib/loggability/log_device/http.rb
 lib/loggability/override.rb
 lib/loggability/spechelpers.rb
+Manifest.txt
+Rakefile
+README.md
 spec/helpers.rb
 spec/loggability/formatter/color_spec.rb
 spec/loggability/formatter/default_spec.rb
@@ -24,6 +28,10 @@ spec/loggability/formatter/structured_spec.rb
 spec/loggability/formatter_spec.rb
 spec/loggability/logger_spec.rb
 spec/loggability/loghost_spec.rb
+spec/loggability/log_device/appending_spec.rb
+spec/loggability/log_device/datadog_spec.rb
+spec/loggability/log_device/file_spec.rb
+spec/loggability/log_device/http_spec.rb
 spec/loggability/override_spec.rb
 spec/loggability/spechelpers_spec.rb
 spec/loggability_spec.rb

data/Rakefile

@@ -3,7 +3,7 @@
 require 'rake/deveiate'
 
 Rake::DevEiate.setup( 'loggability' ) do |project|
-	project.required_ruby_version = '~> 2.5'
+	project.required_ruby_version = ['>= 2.5']
 	project.publish_to = 'deveiate:/usr/local/www/public/code'
 end
 

data/lib/loggability.rb

@@ -9,7 +9,7 @@ require 'date'
 module Loggability
 
 	# Package version constant
-	VERSION = '0.15.1'
+	VERSION = '0.18.2'
 
 	# The key for the global logger (Loggability's own logger)
 	GLOBAL_KEY = :__global__
@@ -29,7 +29,7 @@ module Loggability
 			(?<severity>(?i:debug|info|warn|error|fatal))
 		    (?:
 				\s+
-				(?<target>(?:[\w\-/:\.]|\\[ ])+)
+				(?<target>(?:[\w\-/:\.\[\]]|\\[ ])+)
 			)?
 			(?: \s+\(
 				(?<format>\w+)
@@ -38,10 +38,16 @@ module Loggability
 		$
 	}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
 
 
 	##
@@ -55,10 +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'
 
 
 	### Cast the given +device+ to a Loggability::Logger, if possible, and return it. If
@@ -144,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
 
@@ -189,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
@@ -321,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/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
+

data/lib/loggability/log_device/appending.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'loggability/logger' unless defined?( Loggability::Logger )
+
+# A log device that appends to the object it's constructed with instead of writing
+# to a file descriptor or a file.
+class Loggability::LogDevice::Appending < Loggability::LogDevice
+
+	### Create a new +Appending+ log device that will append content to +array+.
+	def initialize( target )
+		@target = target || []
+	end
+
+
+	######
+	public
+	######
+
+	# The target of the log device
+	attr_reader :target
+
+
+	### Append the specified +message+ to the target.
+	def write( message )
+		@target << message
+	end
+
+
+	### No-op -- this is here just so Logger doesn't complain
+	def close; end
+
+end # class Loggability::LogDevice::Appending

data/lib/loggability/log_device/datadog.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'uri'
+require 'socket'
+require 'net/https'
+require 'json'
+require 'concurrent'
+require 'loggability/logger' unless defined?( Loggability::Logger )
+
+require 'loggability/log_device/http'
+
+
+# A log device that sends logs to Datadog's HTTP endpoint
+# for receiving logs
+class Loggability::LogDevice::Datadog < Loggability::LogDevice::Http
+
+	### Datadog's HTTP endpoint URL for sending logs to
+	DEFAULT_ENDPOINT = URI( "https://http-intake.logs.datadoghq.com/v1/input" )
+
+	### The max number of messages that can be sent to datadog in a single payload
+	MAX_BATCH_SIZE = 480
+
+	### The max size in bytes for a single message.
+	### Limiting the message size to 200kB	to leave room for other info such as
+	### tags, metadata, etc.
+	### DataDog's max size for a single log entry is 256kB
+	MAX_MESSAGE_BYTESIZE = 204_800
+
+	### The max size in bytes of all messages in the batch.
+	### Limiting the total messages size to 4MB to leave room for other info such as
+	### tags, metadata, etc.
+	### Datadog's max size for the entire payload is 5MB
+	MAX_BATCH_BYTESIZE = 4_194_304
+
+	# Override the default HTTP device options for sending logs to DD
+	DEFAULT_OPTIONS = {
+		max_batch_size: MAX_BATCH_SIZE,
+		max_message_bytesize: MAX_MESSAGE_BYTESIZE,
+		max_batch_bytesize: MAX_BATCH_BYTESIZE,
+	}
+
+
+	### Create a new Datadog
+	def initialize( api_key, endpoint=DEFAULT_ENDPOINT, options={} )
+		if endpoint.is_a?( Hash )
+			options = endpoint
+			endpoint = DEFAULT_ENDPOINT
+		end
+
+		super( endpoint, options )
+
+		@api_key = api_key
+		@hostname = Socket.gethostname
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The name of the current host
+	attr_reader :hostname
+
+	##
+	# The configured Datadog API key
+	attr_reader :api_key
+
+
+	### Format an individual log +message+ for Datadog.
+	def format_log_message( message )
+		return {
+			hostname: self.hostname,
+			message: message
+		}.to_json
+	end
+
+
+	### Overridden to add the configured API key to the headers of each request.
+	def make_batch_request
+		request = super
+
+		request[ 'DD-API-KEY' ] = self.api_key
+
+		return request
+	end
+
+end # class Loggability::LogDevice::Datadog

data/lib/loggability/log_device/file.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'logger'
+require 'loggability/logger' unless defined?( Loggability::Logger )
+
+# A log device that delegates to the ruby's default Logger's file device and writes
+# to a file descriptor or a file.
+class Loggability::LogDevice::File < Loggability::LogDevice
+
+	### Create a new +File+ device that will write to the file using the built-in ruby's +File+ log device
+	def initialize( target )
+		@target = ::Logger::LogDevice.new( target )
+	end
+
+
+	######
+	public
+	######
+
+	# The target of the log device
+	attr_reader :target
+
+
+	### Append the specified +message+ to the target.
+	def write( message )
+		self.target.write( message )
+	end
+
+
+	### close the file
+	def close
+		self.target.close
+	end
+
+end # class Loggability::LogDevice::File