module Loggability

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

REVISION

VCS revision

VERSION

Package version constant

Attributes

log_hosts[R]

Public Class Methods

Logger( device ) click to toggle source

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 71
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 ) click to toggle source

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

# File lib/loggability.rb, line 110
def self::[]( logclient )
        key = self.log_host_key_for( logclient )
        key ||= GLOBAL_KEY

        loghost = self.log_hosts[ key ] or
                raise ArgumentError, "no log host set up for %p yet." % [ key ]
        return loghost.logger
end
clear_loghosts() click to toggle source

Clear out all log hosts except for ones which start with '_'. This is intended to be used for testing.

# File lib/loggability.rb, line 122
def self::clear_loghosts
        self.log_hosts.delete_if {|key,_| !key.to_s.start_with?('_') }
end
log_host?( object ) click to toggle source

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

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

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 95
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 ) click to toggle source

Register the specified host as a log host. It should already have been extended with LogHostMethods.

# File lib/loggability.rb, line 80
def self::register_loghost( host )
        key = host.log_host_key
        if self.log_hosts.key?( key )
                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
end
version_string( include_buildnum=false ) click to toggle source

Return the library's version string

# File lib/loggability.rb, line 62
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

Aggregate Methods

↑ top

Public Class Methods

aggregate( methodname, arg, &block ) click to toggle source

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 133
def self::aggregate( methodname, arg, &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 )
        end
end
format_as( formatter )
Alias for: format_with
format_with( formatter ) click to toggle source
format_as( 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 210
def self::format_with( formatter )
        self.aggregate( :format_with, formatter )
end
Also aliased as: format_as, formatter=
formatted_with( formatter, &block ) click to toggle source

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 223
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 click to toggle source

: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 150
def self::level=( newlevel )
        self.aggregate( :level=, newlevel )
end
output_to( destination ) click to toggle source
write_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 178
def self::output_to( newdevice )
        self.aggregate( :output_to, newdevice )
end
Also aliased as: write_to
outputting_to( newdevice, &block ) click to toggle source

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 190
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 ) click to toggle source

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 159
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( newdevice )
Alias for: output_to

Configurability Support

↑ top

Public Class Methods

configure( config=nil ) click to toggle source

Configurability API – configure logging.

# File lib/loggability.rb, line 277
def self::configure( config=nil )
        if config
                self.log.debug "Configuring Loggability with custom config."
                confighash = config.to_hash

                # Set up all loggers with defaults first
                if defaultspec = confighash.delete( :__default__ ) || confighash.delete( '__default__' )
                        level, format, target = self.parse_config_spec( defaultspec )
                        Loggability.level = level if level
                        Loggability.format_as( format ) if format
                        Loggability.output_to( target ) if target
                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 ]
                        level, format, target = self.parse_config_spec( logspec )
                        Loggability[ key ].level = level if level
                        Loggability[ key ].format_with( format ) if format
                        Loggability[ key ].output_to( target ) if target
                end
        else
                self.log.debug "Configuring Loggability with defaults."
        end
end
parse_config_spec( spec ) click to toggle source

Parse the specified spec into level,

# File lib/loggability.rb, line 310
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
                else
                        target
                end

        return severity, format, target
end

LogClient API

↑ top

Public Instance Methods

log_to( loghost ) click to toggle source

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 257
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 ) click to toggle source

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 240
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