Loggability module

Included Modules

Loggability::Constants

A mixin that provides a top-level logging subsystem based on Logger.

Constants

AGGREGATE_METHODS: The methods that are delegated across all loggers
CONFIG_DEFAULTS: Configuration defaults
GLOBAL_KEY: The key for the global logger (Loggability’s own logger)
LOGSPEC_PATTERN: Regexp for parsing logspec lines in the config
VERSION: Package version constant

Attributes

config RW
log_hosts R

Public Class Methods

Logger( device )

Cast the given device to a Loggability::Logger, if possible, and return it. If it can’t be converted, raises a ArgumentError.

# File lib/loggability.rb, line 67
def self::Logger( device )
        return device if device.is_a?( Loggability::Logger )
        return Loggability::Logger.from_std_logger( device ) if device.is_a?( ::Logger )
        return Loggability::Logger.new( device )
end

[]( logclient )

Return the Loggability::Logger for the loghost associated with logclient.

# File lib/loggability.rb, line 127
def self::[]( logclient )
        loghost = self.log_host_for( logclient )
        return loghost.logger
end

log_host?( object )

Returns true if there is a log host associated with the given object.

# File lib/loggability.rb, line 120
def self::log_host?( object )
        key = self.log_host_key_for( object ) or return false
        return self.log_hosts.key?( key )
end

log_host_for( object )

Return the log host for object, if any. Raises an ArgumentError if the object doesn’t have an associated log host.

# File lib/loggability.rb, line 108
def self::log_host_for( object )
        key = self.log_host_key_for( object )
        key ||= GLOBAL_KEY

        loghost = self.log_hosts[ key ] or
                raise ArgumentError, "no log host set up for %p yet." % [ key ]

        return loghost
end

log_host_key_for( object )

Return the log host key for object, using its log_host_key method if it has one, or returning it as a Symbol if it responds to to_sym. Returns nil if no key could be derived.

# File lib/loggability.rb, line 99
def self::log_host_key_for( object )
        return object.log_host_key if object.respond_to?( :log_host_key )
        return object.to_sym if object.respond_to?( :to_sym )
        return nil
end

register_loghost( host )

# File lib/loggability.rb, line 76
def self::register_loghost( host )
        key = host.log_host_key
        if self.log_hosts.key?( key )
                # raise "Can't set a log host for nil" if key.nil?
                self.logger.warn "Replacing existing log host for %p (%p) with %p" %
                        [ key, self.log_hosts[key], host ]
        end

        #self.logger.debug "Registering %p log host: %p" % [ key, host ] if self.logger
        self.log_hosts[ key ] = host
        if (( logspec = Loggability.config[key] ))
                self.apply_config( host.logger, logspec )
        elsif (( defaultspec = (Loggability.config[:__default__] || Loggability.config['__default__']) ))
                self.apply_config( host.logger, defaultspec )
        else
                self.apply_config( host.logger, CONFIG_DEFAULTS[:__default__] )
        end
end

reset()

Clear out all registered log hosts and reset the default logger. This is mostly intended for facilitating tests.

# File lib/loggability.rb, line 135
def self::reset
        self.log_hosts.clear
        self.logger = self.default_logger = Loggability::Logger.new
        Loggability.register_loghost( self )
end

Aggregate Methods

↑ top

Public Class Methods

aggregate( methodname, *args, &block )

Call the method with the given methodname across the loggers of all loghosts with the given arg and/or block.

# File lib/loggability.rb, line 148
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, *args, &block )
        end
end

for_log_host( *hosts, &block )

Alias for: for_logger

for_log_hosts( *hosts, &block )

Alias for: for_logger

for_logger( *hosts, &block )

Aggregate method: override one or more settings for the duration of the block for only the given hosts. If no block is given returns a Loggability::Override object that will override the specified log hosts whenever its #call method is called.

# File lib/loggability.rb, line 253
def self::for_logger( *hosts, &block )
        override = Loggability::Override.for_logger( *hosts )

        if block
                return override.call( &block )
        else
                return override
        end
end

Also aliased as: for_loggers , for_log_host , for_log_hosts

for_loggers( *hosts, &block )

Alias for: for_logger

format_as( formatter )
formatter = formatter

Alias for: format_with

format_with( formatter )
formatter = formatter

:method: format_with

Aggregate method: set all loggers to log with the given formatter. See Loggability::Logger#format_with for more info.

# File lib/loggability.rb, line 225
def self::format_with( formatter )
        self.aggregate( :format_with, formatter )
end

Also aliased as: format_as , formatter=

formatted_with( formatter, &block )

Aggregate method: set all loggers to log with the given formatter for the duration of the block, restoring the original formatters afterward. If no block is given, returns a Loggability::Override object that will override all formatters whenever its #call method is called.

# File lib/loggability.rb, line 238
def self::formatted_with( formatter, &block )
        override = Loggability::Override.formatted_with( formatter )

        if block
                return override.call( &block )
        else
                return override
        end
end

formatter = formatter

Alias for: format_with

level = newlevel

:method: level=

Aggregate method: set the log level on all loggers to newlevel. See Loggability::Logger#level= for more info.

# File lib/loggability.rb, line 165
def self::level=( newlevel )
        self.aggregate( :level=, newlevel )
end

output_to( destination )

:method: output_to

Aggregate method: set all loggers to log to destination. See Loggability::Logger#output_to for more info.

# File lib/loggability.rb, line 193
def self::output_to( newdevice, *args )
        self.aggregate( :output_to, newdevice, *args )
end

Also aliased as: write_to

outputting_to( newdevice, &block )

Aggregate method: set all loggers to log to destination for the duration of the block, restoring the original destination afterward. If no block is given, returns a Loggability::Override object that will log to destination whenever its #call method is called.

# File lib/loggability.rb, line 205
def self::outputting_to( newdevice, &block )
        override = Loggability::Override.outputting_to( newdevice )

        if block
                return override.call( &block )
        else
                return override
        end
end

with_level( level, &block )

Aggregate method: set the log level on all loggers to level for the duration of the block, restoring the original levels afterward. If no block is given, returns a Loggability::Override object that set the log level to level while its #call method is being called.

# File lib/loggability.rb, line 174
def self::with_level( level, &block )
        override = Loggability::Override.with_level( level )

        if block
                return override.call( &block )
        else
                return override
        end
end

write_to( destination )

Alias for: output_to

Configurability Support

↑ top

Public Class Methods

apply_config( logger, logspec )

Configure the specified logger (or anything that ducktypes the same) with the configuration specified by logspec.

# File lib/loggability.rb, line 307
def self::apply_config( logger, logspec )
        level, format, target = self.parse_config_spec( logspec )
        logger.level = level if level
        logger.format_with( format ) if format
        logger.output_to( target ) if target
end

configure( new_config=nil )

Configurability API – configure logging.

# File lib/loggability.rb, line 342
def self::configure( new_config=nil )
        if new_config
                self.config = new_config.dup.freeze
                confighash = new_config.to_hash

                # Set up all loggers with defaults first
                if defaultspec = confighash.delete( :__default__ ) || confighash.delete( '__default__' )
                        self.apply_config( self, defaultspec )
                end

                # Then let individual configs override.
                confighash.each do |key, logspec|
                        unless Loggability.log_host?( key )
                                self.log.debug "  no such log host %p; skipping" % [ key ]
                                next
                        end

                        # self.log.debug "  configuring logger for %p: %s" % [ key, logspec ]
                        self.apply_config( Loggability[key], logspec )
                end
        else
                self.config = self.defaults.dup.freeze
        end
end

parse_config_spec( spec )

Parse the specified spec into level,

# File lib/loggability.rb, line 316
def self::parse_config_spec( spec )
        match = LOGSPEC_PATTERN.match( spec ) or
                raise ArgumentError, "Couldn't parse logspec: %p" % [ spec ]
        # self.log.debug "  parsed config spec %p -> %p" % [ spec, match ]
        severity, target, format = match.captures

        target = case target
                when 'STDOUT' then $stdout
                when 'STDERR' then $stderr
                when /:/ then Loggability::LogDevice.parse_device_spec( target )
                else
                        target
                end

        return severity, format, target
end

LogClient API

↑ top

Public Instance Methods

log_to( loghost )

Register as a log client that will log to to the given loghost, which can be either the key the host registered with, or the log host object itself. Log messages can be written to the loghost via the LogClient API, which is automatically included.

# File lib/loggability.rb, line 292
def log_to( loghost )
        extend( Loggability::LogClient )
        include( Loggability::LogClient::InstanceMethods ) if self.is_a?( Class )

        self.log_host_key = Loggability.log_host_key_for( loghost )
end

LogHost API

↑ top

Public Instance Methods

log_as( key )

Register as a log host associated with the given key, add the methods from LogHost, and install a Loggability::Logger.

# File lib/loggability.rb, line 275
def log_as( key )
        extend( Loggability::LogHost )
        include( Loggability::LogClient::InstanceMethods ) if self.is_a?( Class )

        self.log_host_key = key.to_sym
        self.logger = self.default_logger = Loggability::Logger.new
        Loggability.register_loghost( self )
end