Loggability

module

Included Modules: Loggability::Constants; Loggability::LogClient::InstanceMethods

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

anchor

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

anchor

[]( logclient )

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

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

        return self.log_hosts[ key ].logger
end

anchor

clear_loghosts()

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

# File lib/loggability.rb, line 115
def self::clear_loghosts
        self.log_hosts.delete_if {|key,_| !key.to_s.start_with?('_') }
end

anchor

log_host?( object )

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

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

anchor

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

anchor

register_loghost( host )

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

anchor

version_string( include_buildnum=false )

Return the library’s version string

# File lib/loggability.rb, line 57
def self::version_string( include_buildnum=false )
        vstring = "%s %s" % [ self.name, VERSION ]
        vstring << " (build %s)" % [ REVISION[%r: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
        return vstring
end

Aggregate Methods

↑ top

Public Class Methods

anchor

aggregate( methodname, arg, &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 126
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

anchor

format_as( formatter )

Alias for: format_with

anchor

format_with( formatter )
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 173
def self::format_with( formatter )
        self.aggregate( :format_with, formatter )
end

Also aliased as: format_as , formatter=

anchor

formatter=( formatter )

Alias for: format_with

anchor

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 143
def self::level=( newlevel )
        self.aggregate( :level=, newlevel )
end

anchor

output_to( destination )
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 156
def self::output_to( newdevice )
        self.aggregate( :output_to, newdevice )
end

Also aliased as: write_to

anchor

write_to( newdevice )

Alias for: output_to

Configurability Support

↑ top

Public Class Methods

anchor

configure( config=nil )

Configurability API – configure logging.

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

anchor

parse_config_spec( spec )

Parse the specified spec into level,

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

anchor

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

anchor

log_as( key )

# File lib/loggability.rb, line 223
def log_as( key )
        self.extend( Loggability::LogHost )
        self.log_host_key = key.to_sym
        self.logger = self.default_logger = Loggability::Logger.new
        Loggability.register_loghost( self )
end