itchy 0.0.1

data/lib/itchy/event_handlers/base_event_handler.rb

@@ -0,0 +1,82 @@
+module Itchy::EventHandlers
+  # Basic handler implementing required methods. Can be used
+  # as a dummy for testing purposes.
+  class BaseEventHandler
+    TEMPFILE_BASE = 'vmcatcher_event_metadata_archive'
+    EVENT_FILE_REGEXP = /^(?<time>\d+)_(?<type>[[:alnum:]]+)_(?<dc_identifier>[[[:alnum:]]-]+)\.json$/
+
+    attr_reader :vmcatcher_configuration, :options
+
+    # Event handler constructor.
+    #
+    # @param vmcatcher_configuration [Itchy::VmcatcherConfiguration] current vmcatcher configuration
+    # @param options [Settingslogic] current itchy configuration
+    def initialize(vmcatcher_configuration, options)
+      unless vmcatcher_configuration.is_a?(Itchy::VmcatcherConfiguration)
+        fail ArgumentError, '\'vmcatcher_configuration\' must be an instance of ' \
+                            'Itchy::VmcatcherConfiguration!'
+      end
+
+      @vmcatcher_configuration = vmcatcher_configuration
+      @options = options || ::Hashie::Mash.new
+    end
+
+    # Triggers an archiving procedure on the registered event.
+    #
+    # @param vmcatcher_event [Itchy::VmcatcherEvent] event being archived
+    def archive!(vmcatcher_event)
+      unless vmcatcher_event.is_a?(Itchy::VmcatcherEvent)
+        fail ArgumentError, '\'vmcatcher_event\' must be an instance of ' \
+                            'Itchy::VmcatcherEvent!'
+      end
+
+      Itchy::Log.info "[#{self.class.name}] Saving " \
+                             "#{vmcatcher_event.type.inspect} " \
+                             "for #{vmcatcher_event.dc_identifier.inspect}"
+
+      temp_file = ::Tempfile.new(TEMPFILE_BASE)
+      permanent_file_path = ::File.join(
+        options.metadata_dir,
+        "#{::Time.now.to_i}_#{vmcatcher_event.type || 'Unknown'}_#{vmcatcher_event.dc_identifier || 'NoID'}.json"
+      )
+
+      temp_file.write(vmcatcher_event.to_pretty_json)
+      temp_file.flush
+
+      ::FileUtils.cp(temp_file.path, permanent_file_path)
+      temp_file.close
+
+      true
+    end
+
+    # Handling procedure
+    def handle!(vmcatcher_event, _event_file)
+      unless vmcatcher_event.is_a?(Itchy::VmcatcherEvent)
+        fail ArgumentError, '\'vmcatcher_event\' must be an instance of ' \
+                'Itchy::VmcatcherEvent!'
+            end
+    end
+
+    # Save created descriptor to descriptor directory. Every descriptor
+    # is stored in its own directory.
+    #
+    # @param descriptor [String] json form of appliance descriptor
+    # @param name [String] name of appliance descriptor (event name)
+    def save_descriptor(descriptor, name)
+      name.slice! @options.metadata_dir
+      dir_name = name
+      dir_name.slice! '.json'
+      ::FileUtils.mkdir_p "#{@options.descriptor_dir}/#{dir_name}"
+      File.open("#{@options.descriptor_dir}#{dir_name}/#{name}.json", 'w') { |f| f.write(descriptor) }
+    end
+
+    protected
+
+    # Creates an image transformer instance with options.
+    #
+    # @return [ImageTransformer] image transformer instance
+    def image_transformer_instance
+      @image_transformer_instance_cache ||= Itchy::ImageTransformer.new(options)
+    end
+  end
+end

data/lib/itchy/event_handlers/expire_postfix_event_handler.rb

@@ -0,0 +1,30 @@
+module Itchy::EventHandlers
+  # Handler for ExpirePostfix event (image expired).
+  class ExpirePostfixEventHandler < BaseEventHandler
+    # Handles an ExpirePostfix event.
+    #
+    # @param vmcatcher_event [Itchy::VmcatcherEvent] vmcatcher event to handle
+    # @param event_name [String] name of the event
+    def handle!(vmcatcher_event, event_name)
+      super
+      Itchy::Log.info "[#{self.class.name}] Handling expired image " \
+                             "for #{vmcatcher_event.dc_identifier.inspect}"
+      save_descriptor(create_descriptor(vmcatcher_event), event_name)
+    end
+
+    private
+
+    # Create appliance descriptor from VMCATCHER_EVENT metadata.
+    #
+    # @param metadata [Itchy::VmcatcherEvent] vmcatcher event to get metadata from
+    # @return [String] json form of created description
+    def create_descriptor(metadata)
+      Itchy::Log.debug "[#{self.class.name}] Creating appliance descriptor"
+      appliance = ::Cloud::Appliance::Descriptor::Appliance.new action: :expiration
+      appliance.version = metadata.hv_version
+      appliance.identifier = metadata.dc_identifier
+
+      descriptor = appliance.to_json
+    end
+  end
+end

data/lib/itchy/event_handlers/expire_prefix_event_handler.rb

@@ -0,0 +1,9 @@
+module Itchy::EventHandlers
+  # Handler for ExpirePrefix event (image will be expired).
+  class ExpirePrefixEventHandler < BaseEventHandler
+    def handle!(vmcatcher_event, event_file)
+      super
+      Itchy::Log.warn "[#{self.class.name}] Just ignoring #{vmcatcher_event.type.inspect}"
+    end
+  end
+end

data/lib/itchy/event_handlers/process_postfix_event_handler.rb

@@ -0,0 +1,9 @@
+module Itchy::EventHandlers
+  # Handler for ProcessPostfix event (finished cache update).
+  class ProcessPostfixEventHandler < BaseEventHandler
+    def handle!(vmcatcher_event, event_file)
+      super
+      Itchy::Log.warn "[#{self.class.name}] Just ignoring #{vmcatcher_event.type.inspect}"
+    end
+  end
+end

data/lib/itchy/event_handlers/process_prefix_event_handler.rb

@@ -0,0 +1,10 @@
+module Itchy::EventHandlers
+  # Handler for ProcessPrefix event (starting cache update).
+  class ProcessPrefixEventHandler < BaseEventHandler
+    def handle!(vmcatcher_event, file)
+      super
+      Itchy::Log.info "[#{self.class.name}] Handling #{vmcatcher_event.type.inspect}" \
+        'This kind of event is just logged, nothing to process.'
+    end
+  end
+end

data/lib/itchy/event_handlers/subscription_image_new_event_handler.rb

@@ -0,0 +1,9 @@
+module Itchy::EventHandlers
+  # Handler for SubscriptionImageNew event (new image added to image list).
+  class SubscriptionImageNewEventHandler < BaseEventHandler
+    def handle!(vmcatcher_event, event_file)
+      super
+      Itchy::Log.warn "[#{self.class.name}] Just ignoring #{vmcatcher_event.type.inspect}"
+    end
+  end
+end

data/lib/itchy/event_handlers.rb

@@ -0,0 +1,8 @@
+# Wrapper for all available vmcatcher event handlers.
+module Itchy::EventHandlers; end
+
+# Load base handler first
+require File.join(File.dirname(__FILE__), 'event_handlers', 'base_event_handler')
+
+# Load all available event handlers
+Dir.glob(File.join(File.dirname(__FILE__), 'event_handlers', '*.rb')) { |handler_file| require handler_file.chomp('.rb') }

data/lib/itchy/event_processer.rb

@@ -0,0 +1,103 @@
+module Itchy
+  # Process stored evenets.
+  class EventProcesser
+    attr_reader :vmc_configuration, :options
+
+    # Creates and processer instance for stored vmcatcher events.
+    #
+    # @param vmc_configuration [Itchy::Vmcatcher::Configuration] vmcatcher configuration
+    # @param options [Hashie::Mash] hask-like structure with options
+    def initialize(vmc_configuration, options)
+      fail ArgumentError, '"vmc_configuration" must be an instance ' \
+        'of Itchy::VmcatcherConfiguration' unless vmc_configuration.is_a? Itchy::VmcatcherConfiguration
+
+      @vmc_configuration = vmc_configuration
+      @options = options
+    end
+
+    # Processing method for events. For each event calls respective
+    # event handler. And after processing of each event, stored event
+    # file is deleted.
+    def process!
+      Itchy::Log.info "[#{self.class.name}] Processing eventes stored in #{options.metadata_dir}"
+
+      archived_events do |event, event_file|
+        begin
+          
+          begin
+            event_handler = Itchy::EventHandlers.const_get("#{event.type}EventHandler")
+            event_handler = event_handler.new(vmc_configuration, options)
+            event_handler.handle!(event, event_file)
+          rescue => ex
+            Itchy::Log.error "[#{self.class.name}] Due to error #{ex.message} event #{event_file}" \
+              "was not processed!!! Continuing with next stored event."
+            next
+          end
+
+          begin
+            clean_event!(event, event_file)
+          rescue => ex
+            Itchy::Log.error "[#{self.class.name}] Event #{event_file} was processed, but not cleaned!!!"
+          end
+
+        end
+      end
+    end
+
+    # Prepares archived event for processing. That means inspect directory with
+    # stored event files, and create VmcatcherEvent from each file.
+    def archived_events(&block)
+      arch_events = ::Dir.glob(::File.join(options.metadata_dir, '*.json'))
+      arch_events.sort!
+      Itchy::Log.debug "[#{self.class.name}] Foud events: #{arch_events.inspect}"
+      arch_events.each do |json|
+        json_short = json.split(::File::SEPARATOR).last
+
+        unless Itchy::EventHandlers::BaseEventHandler::EVENT_FILE_REGEXP =~ json_short
+          Itchy::Log.error "[#{self.class.name}] #{json.inspect} doesn't match the required format"
+          next
+        end
+
+        vmc_event_from_json = read_event(json)
+        block.call(vmc_event_from_json, json) if vmc_event_from_json
+      end
+    end
+
+    # Creates VmcatcherEvent instance.
+    #
+    # @param json json [String] path to file containing json representation
+    # of vmcatcher event
+    #
+    # @return [VmcatcherEvent] instance representing event
+    def read_event(json)
+      Itchy::VmcatcherEvent.new(::File.read(json))
+    rescue => ex
+      Itchy::Log.error '[]Failed to load event!!!'
+      return ex
+    end
+
+    # Deletes event file.
+    #
+    # @param event [VmcatcherEvent] event for cleaning
+    # @param event_file [String] path to file containing event info
+    def clean_event!(_event, event_file)
+      Itchy::Log.info "[#{self.class.name}] Cleaning up"
+
+      begin
+        ::FileUtils.rm_f event_file
+      rescue => ex
+        Itchy::Log.fatal 'Failed to clean up event!!!'
+        return ex
+      end
+    end
+
+    # Checks if description directory exists and its readable.
+    def check_descriptor_dir
+      Itchy::Log.debug "[#{self.class.name}] Checking root descriptor dir #{options.descriptor_dir.inspect}"
+      fail ArgumentError, 'Root descriptor directory' \
+                          'is not a directory!' unless File.directory? options.descriptor_dir
+      fail ArgumentError, 'Root descriptor directory' \
+        'is not readable!' unless File.readable? opitons.descriptor_dir
+    end
+  end
+end

data/lib/itchy/format_converter.rb

@@ -0,0 +1,43 @@
+module Itchy
+  # Converting different image formats
+  class FormatConverter
+    # Creates and converter instance for converting image to requried format
+    #
+    # @param unpacking_dir [String] path to directory where image is stored
+    # @param metadata [VmcatcherEvent] metadata of event corresponding to image
+    # @param vmcatcher_configuration [VmcatcherConfiguration] vmcatcher configuration
+    def initialize(unpacking_dir, metadata, vmcatcher_configuration)
+      unless vmcatcher_configuration.is_a?(Itchy::VmcatcherConfiguration)
+        fail ArgumentError, '\'vmcatcher_configuration\' must be an instance of ' \
+                            'Itchy::VmcatcherConfiguration!'
+      end
+
+      @unpacking_dir = unpacking_dir
+      @metadata = metadata
+      @vmcatcher_configuration = vmcatcher_configuration
+    end
+
+    # Converts image to required format. It uses Mixlib::ShelOut.
+    #
+    # @param file_format [String] actual format of the image
+    # @param required_format [String] required format
+    # @param output_dir [String] path to a directory where converted image should be stored
+    def convert!(file_format, required_format, output_dir)
+      Itchy::Log.info "[#{self.class.name}] Converting image " \
+                             "#{@metadata.dc_identifier.inspect} from " \
+                             "original format: #{file_format} to " \
+                             "required format: #{required_format}."
+
+      convert_cmd = Mixlib::ShellOut.new("qemu-img convert -f #{file_format} -O #{required_format} #{@unpacking_dir}/#{@metadata.dc_identifier} #{output_dir}/#{@metadata.dc_identifier}")
+      convert_cmd.run_command
+      begin
+        convert_cmd.error!
+      rescue Mixlib::ShellOut::ShellCommandFailed, Mixlib::ShellOut::CommandTimeout,
+             Mixlib::Shellout::InvalidCommandOption => ex
+        Itchy::Log.fatal "[#{self.class.name}] Converting of image failed with " \
+          "error messages #{convert_cmd.stderr}."
+        fail Itchy::Errors::FormatConvertingError, ex
+      end
+    end
+  end
+end

data/lib/itchy/helpers/vmcatcher_env_helper.rb

@@ -0,0 +1,44 @@
+module Itchy::Helpers
+  # Wraps static helper methods for accessing environment variables
+  # provided by vmcatcher.
+  module VmcatcherEnvHelper
+    # Selects only relevant +env+ entries and throws the rest away.
+    # Throws Itchy::Errors::EnvLookupError if the result is
+    # empty.
+    #
+    # @param env [Object] environment object convertible to a hash
+    # @param relevant_keys [Array] an array of string keys to look for in +env+
+    # @return [Hash] cleaned up hash containing only relevant entries
+    def self.select_from_env(env, relevant_keys)
+      Itchy::Log.debug "[#{name}] Looking for " \
+                              "#{relevant_keys.inspect} in #{env.inspect}"
+      env = env.select { |key, _| relevant_keys.include? key }
+
+      if env.blank?
+        Itchy::Log.fatal "[#{name}] No relevant information " \
+                                "found in 'env'"
+        fail(
+          Itchy::Errors::EnvLookupError,
+          'Environment look-up failed! Result is empty!'
+        )
+      end
+
+      env
+    end
+
+    # Converts +env+ object to a hash.
+    #
+    # @param env [Object] environment object convertible to a hash
+    # @return [Hash] converted environment object
+    def self.normalize_env(env)
+      return env if env.is_a? Hash
+
+      fail(
+        Itchy::Errors::EnvLookupError,
+        "'env' must be convertible to a hash!"
+      ) unless env.respond_to?(:to_hash)
+
+      env.to_hash
+    end
+  end
+end

data/lib/itchy/helpers.rb

@@ -0,0 +1,5 @@
+# Wrapper for all available helpers.
+module Itchy::Helpers; end
+
+# Load all available helpers
+Dir.glob(File.join(File.dirname(__FILE__), 'helpers', '*.rb')) { |helper_file| require helper_file.chomp('.rb') }

data/lib/itchy/image_transformer.rb

@@ -0,0 +1,220 @@
+module Itchy
+  # Wraps image format conversion methods and helpers.
+  class ImageTransformer
+    # Registered image formats and archives
+    KNOWN_IMAGE_ARCHIVES = %w(ova tar).freeze
+    KNOWN_IMAGE_FORMATS  = %w(cow dmg parallels qcow qcow2 raw vdi vmdk vhd).freeze
+
+    # Archive format string msg
+    ARCHIVE_STRING = 'POSIX tar archive'
+
+    # REGEX pattern for getting image format
+    FORMAT_PATTERN = /format:\s(.*?)$/
+
+    # Creates a class instance.
+    #
+    # @param options [Hash] configuration options
+    def initialize(options = {})
+      @options = options
+      @inputs = ([] << KNOWN_IMAGE_FORMATS << KNOWN_IMAGE_ARCHIVES).flatten
+
+      fail ArgumentError, 'Unsupported input image format enabled in configuration! ' \
+           "#{@inputs.inspect}" unless (@options.input_image_formats - @inputs).empty?
+      # fail "Unsupported output image format enabled in configuration! " \
+      #     "#{KNOWN_IMAGE_FORMATS.inspect}" unless (@options.required_format - KNOWN_IMAGE_FORMATS).empty?
+    end
+
+    # Transforms image(s) associated with the given event to formats
+    # preferred by the underlying image datastore. This process includes
+    # unpacking of archive & conversion of image files.
+    #
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    # @param vmcatcher_configuration [Itchy::VmcatcherConfiguration] current VMC configuration
+    # @return [String] directory with converted images for further processing
+    def transform!(metadata, vmcatcher_configuration)
+      Itchy::Log.info "[#{self.class.name}] Transforming image format " \
+                             "for #{metadata.dc_identifier.inspect}"
+      begin
+        if archived?(metadata.dc_identifier.inspect)
+          unpacking_dir = unpack_archived!(metadata, vmcatcher_configuration)
+          file_format = inspect_unpacked_dir(unpacking_dir, metadata)
+        else
+          file_format = format(orig_image_file(metadata, vmcatcher_configuration))
+          unpacking_dir = copy_unpacked!(metadata, vmcatcher_configuration)
+        end
+        if file_format == @options.required_format
+          copy_same_format(unpacking_dir, metadata)
+        else
+          converter = Itchy::FormatConverter.new(unpacking_dir, metadata, vmcatcher_configuration)
+          converter.convert!(file_format, @options.required_format, @options.output_dir)
+        end
+      rescue Itchy::Errors::FileInspectingError, Itchy::Errors::FormatConvertingError,
+             Itchy::Errors::WorkingWithFilesError => ex
+        fail Itchy::Errors::ImageTransformingError, ex
+      end
+    end
+
+    private
+
+    # Checks the given format against a list of available
+    # image formats.
+    #
+    # @param unpacking_dir [String] name and path of the checked file
+    # @return [String] image format
+    def format(file)
+      image_format_tester = Mixlib::ShellOut.new("qemu-img info #{file}")
+      image_format_tester.run_command
+      begin
+        image_format_tester.error!
+      rescue => ex
+        Itchy::Log.error "[#{self.class.name}] Checking file format for" \
+                                "#{file} failed!"
+        fail Itchy::Errors::FileInspectingError, ex
+      end
+      file_format = image_format_tester.stdout.scan(FORMAT_PATTERN)[0].flatten.first
+      unless KNOWN_IMAGE_FORMATS.include? file_format
+        Itchy::Log.error "Image format #{file_format} is unknown and not supported!"
+        fail Itchy::Errors::FileInspectingError
+      end
+      file_format
+    end
+
+    #
+    #
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    # @param vmcatcher_configuration [Itchy::VmcatcherConfiguration] current VMC configuration
+    # @return [String] output directory with unpacked files
+    def unpack_archived!(metadata, vmcatcher_configuration)
+      Itchy::Log.info "[#{self.class.name}] Unpacking image from archive " \
+                             "for #{metadata.dc_identifier.inspect}"
+
+      unpacking_dir = prepare_image_temp_dir(metadata, vmcatcher_configuration)
+      tar_cmd = ::Mixlib::ShellOut.new('/bin/tar',
+                                       "--restrict -C #{unpacking_dir} " \
+                                       "-xvf #{orig_image_file(metadata, vmcatcher_configuration)}",
+                                       env: nil, cwd: '/tmp')
+      tar_cmd.run_command
+      begin
+        tar_cmd.error!
+      rescue => ex
+        Itchy::Log.error "Unpacking of archive failed with #{tar_cmd.stderr}"
+        fail Itchy::Errors::WorkingWithFilesError, ex
+      end
+
+      unpacking_dir
+    end
+
+    # Inspect unppacked .ova or .tar files. So far, it checks if there is only one
+    # image file of known format and if it is, it's renamed to dc_identifier end its
+    # format is determined. Otherwise (for now) its unsupported situation.
+    #
+    # @param directory [String] name of directory where '.ova' or '.tar' is unpacked
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    # @return [String] format of image or nil.
+    def inspect_unpacked_dir(directory, metadata, _identifier)
+      dir = Dir.new directory
+      counter = 0
+      files = dir['*']
+      files each do |file|
+        file_format = format("#{directory}/#{file}")
+        if KNOWN_IMAGE_FORMATS.include? file_format
+          counter += 1
+          # unsupported ova content (more than one disk)
+          return nil if counter > 1
+          File.new("#{directory}/#{file}", 'r').rename(file, "#{metadata.dc_identifier}.#{file_format}")
+        end
+      end
+      return nil if counter == 0
+
+      file_format
+    end
+
+    #
+    #
+    # @param directory [String] name of directory where image is saved
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    def copy_same_format(directory, metadata)
+      Itchy::Log.info "[#{self.class.name}] Image #{metadata.dc_identifier.inspect} " \
+        'is already in the required format. Copying it to output directory.'
+
+      begin
+        ::FileUtils.ln_sf("#{directory}/#{metadata.dc_identifier}", @options.output_dir)
+      rescue => ex
+        Itchy::Log.fatal "[#{self.class.name}] Failed to create a link (copy) " \
+          "for #{metadata.dc_identifier.inspect}: " \
+          "#{ex.message}"
+        fail Itchy::Errors::WorkingWithFilesError, ex
+      end
+    end
+
+    #
+    #
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    # @param vmcatcher_configuration [Itchy::VmcatcherConfiguration] current VMC configuration
+    # @return [String] output directory with copied files
+    def copy_unpacked!(metadata, vmcatcher_configuration)
+      Itchy::Log.info "[#{self.class.name}] Copying image " \
+                             "for #{metadata.dc_identifier.inspect}"
+      unpacking_dir = prepare_image_temp_dir(metadata, vmcatcher_configuration).flatten.first
+      begin
+        ::FileUtils.ln_sf(
+          orig_image_file(metadata, vmcatcher_configuration),
+          unpacking_dir
+        )
+      rescue => ex
+        Itchy::Log.fatal "[#{self.class.name}] Failed to create a link (copy) " \
+                                "for #{metadata.dc_identifier.inspect}: " \
+                                "#{ex.message}"
+        fail Itchy::Errors::WorkingWithFilesError, ex
+      end
+
+      unpacking_dir
+    end
+
+    #
+    #
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    # @param vmcatcher_configuration [Itchy::VmcatcherConfiguration] current VMC configuration
+    # @return [String] path to the original image downloaded by VMC
+    def orig_image_file(metadata, vmcatcher_configuration)
+      "#{vmcatcher_configuration.cache_dir_cache}/#{metadata.dc_identifier}"
+    end
+
+    #
+    #
+    # @param metadata [Itchy::VmcatcherEvent] event metadata
+    # @param vmcatcher_configuration [Itchy::VmcatcherConfiguration] current VMC configuration
+    # @return [String] path to the newly created image directory
+    def prepare_image_temp_dir(metadata, vmcatcher_configuration)
+      temp_dir = "#{vmcatcher_configuration.cache_dir_cache}/temp/#{metadata.dc_identifier}"
+
+      begin
+        ::FileUtils.mkdir_p temp_dir
+      rescue => ex
+        Itchy::Log.fatal "[#{self.class.name}] Failed to create a directory " \
+                                "for #{metadata.dc_identifier.inspect}: " \
+                                "#{ex.message}"
+        fail Itchy::Errors::WorkingWithFilesError, ex
+      end
+    end
+
+    # Checks if file is archived image (format ova or tar)
+    #
+    # @param file [String] inspected file name
+    # @return [Boolean] archived or not
+    def archived?(file)
+      image_format_tester = Mixlib::ShellOut.new("file #{file}")
+      image_format_tester.run_command
+      begin
+        image_format_tester.error!
+      rescue
+        Itchy::Log.error "[#{self.class.name}] Checking file format for" \
+          "#{file} failed with #{image_format_tester.stderr}"
+        fail Itchy::Errors::FileInspectingError, ex
+                                
+      end
+      temp = image_format_tester.stdout
+      temp.include? ARCHIVE_STRING
+    end
+  end
+end

data/lib/itchy/log.rb

@@ -0,0 +1,78 @@
+module Itchy
+  # Handles static logging from the entire application
+  # without the need for a traveling logger instance.
+  class Log
+    include ::Logger::Severity
+
+    attr_reader :logger, :log_prefix
+
+    SUBSCRIPTION_HANDLE = 'itchy.log'
+
+    # Creates a new itchy logger instance. Subsequent logging can be
+    # then performed via static Itchy::Log methods.
+    #
+    # @param log_dev [IO,String] The log device.  This is a filename (String) or IO object (typically +STDOUT+,
+    # @param log_prefix [String] String placed in front of every logged message
+    #  +STDERR+, or an open file).
+    def initialize(log_dev, log_prefix = '[itchy]')
+      if log_dev.is_a? ::Logger
+        @logger = log_dev
+      else
+        @logger = ::Logger.new(log_dev)
+      end
+
+      @log_prefix = log_prefix.blank? ? '' : log_prefix.strip
+
+      # subscribe to log messages and send to logger
+      @log_subscriber = ActiveSupport::Notifications.subscribe(self.class::SUBSCRIPTION_HANDLE) do |_name, _start, _finish, _id, payload|
+        @logger.log(payload[:level], "#{@log_prefix} #{payload[:message]}") if @logger
+      end
+    end
+
+    # Closes active logger subscription.
+    def close
+      ActiveSupport::Notifications.unsubscribe(@log_subscriber)
+    end
+
+    # Sets current logging level.
+    #
+    # @param severity [::Logger::Severity] severity
+    def level=(severity)
+      @logger.level = severity
+    end
+
+    # Gets current logging level.
+    #
+    # @return [::Logger::Severity]
+    def level
+      @logger.level
+    end
+
+    # @see info
+    def self.debug(message)
+      ActiveSupport::Notifications.instrument(self::SUBSCRIPTION_HANDLE, level: ::Logger::DEBUG, message: message)
+    end
+
+    # Log an +INFO+ message.
+    #
+    # @param message [String] message the message to log; does not need to be a String
+    def self.info(message)
+      ActiveSupport::Notifications.instrument(self::SUBSCRIPTION_HANDLE, level: ::Logger::INFO, message: message)
+    end
+
+    # @see info
+    def self.warn(message)
+      ActiveSupport::Notifications.instrument(self::SUBSCRIPTION_HANDLE, level: ::Logger::WARN, message: message)
+    end
+
+    # @see info
+    def self.error(message)
+      ActiveSupport::Notifications.instrument(self::SUBSCRIPTION_HANDLE, level: ::Logger::ERROR, message: message)
+    end
+
+    # @see info
+    def self.fatal(message)
+      ActiveSupport::Notifications.instrument(self::SUBSCRIPTION_HANDLE, level: ::Logger::FATAL, message: message)
+    end
+  end
+end