Class: Hoodoo::Logger

Inherits:
Object
  • Object
show all
Defined in:
lib/hoodoo/logger/logger.rb,
lib/hoodoo/logger/fast_writer.rb,
lib/hoodoo/logger/slow_writer.rb,
lib/hoodoo/logger/writer_mixin.rb,
lib/hoodoo/logger/flattener_mixin.rb,
lib/hoodoo/logger/writers/file_writer.rb,
lib/hoodoo/logger/writers/stream_writer.rb,
lib/hoodoo/logger/writers/log_entries_dot_com_writer.rb

Overview

Multiple output logging via local code or external services. Instantiate a new Logger, then use #add to add instances of writer classes to the collection of log writers. When #report, #debug, #info, #warn or #error are called, a corresponding log message is sent once to each of the writers, provided that the configured logging level (#level, #level=) allows it.

By default, a new logger instance has no configured writers so logged messages will not go anywhere. You must use #add to add at least one writer for the instance to be useful.

Some writer classes are provided by Hoodoo, including:

  • Hoodoo::Logger::StreamWriter - write to output streams, typically expected to be fast, e.g. unredirected $stdout or $stderr.

  • Hoodoo::Logger::FileWriter - write to files, typically expected to be relatively slow.

Some loggers can preserve structural logged data (see #report) while others flatten all log messages. For example, Hoodoo::Logger::StreamWriter must flatten messages but a custom writer that, say, persisted messages in a database should be able to preserve structure.

Writers are either considered fast or slow. Fast writers are called inline as soon as a message gets logged. Slow writers are called asynchronously via a Thread. A Queue is used to buffer messages for slow writers; if this gets too large, messages may be dropped. Once the slow writer catches up, a warn level log message is automatically logged to report the number of dropped messages in the interim.

To create a new custom writer class of any name/namespace, just subclass Hoodoo::Logger::FastWriter or Hoodoo::Logger::SlowWriter - see those classes for details.

Defined Under Namespace

Modules: Communicator, FlattenerMixin, WriterMixin Classes: FastCommunicator, FastWriter, FileWriter, Payload, SlowCommunicator, SlowWriter, StreamWriter

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(component = :Middleware) ⇒ Logger

Create a new logger instance. Once created, use #add to add writers.

component

Flat logging methods (see #debug, #info, #warn and #error) are internally logged through the structured logger (see #report) using the component (again, see #report) optionally passed here as a Symbol or String. Default is :Middleware.



57
58
59
60
61
62
 
# File 'lib/hoodoo/logger/logger.rb', line 57

def initialize( component = :Middleware )
  @level     = :debug
  @pool      = Hoodoo::Communicators::Pool.new
  @component = component
  @writers   = {}
end

Instance Attribute Details

#level ⇒ Object

Return or set the current log level. This is :debug by default.



151
152
153
 
# File 'lib/hoodoo/logger/logger.rb', line 151

def level
  @level
end

Instance Method Details

#add(*writer_instances) ⇒ Object

Add a new writer instance to this logger. Example:

file_writer   = Hoodoo::Logger::FileWriter.new( 'output.log' )
stdout_writer = Hoodoo::Logger::StreamWriter.new

@logger = Hoodoo::Logger.new

logger.add( file_writer   )
logger.add( stdout_writer )

# ...then later...

logger.report( ... ) # -> Sends to "output.log" and $stdout
writer_instances

One or more instances of a subclass of Hoodoo::Logger::FastWriter or Hoodoo::Logger::SlowWriter, passed as one or more comma-separated parameters.



83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/hoodoo/logger/logger.rb', line 83

def add( *writer_instances )
  writer_instances.each do | writer_instance |
    communicator = if writer_instance.is_a?( Hoodoo::Logger::FastWriter )
      FastCommunicator.new( writer_instance, self )
    elsif writer_instance.is_a?( Hoodoo::Logger::SlowWriter )
      SlowCommunicator.new( writer_instance, self )
    else
      raise "Hoodoo::Logger\#add: Only instances of Hoodoo::Logger::FastWriter or Hoodoo::Logger::SlowWriter can be added - #{ writer_instance.class.name } was given"
    end

    @pool.add( communicator )
    @writers[ writer_instance ] = communicator
  end
end

#debug(*args) ⇒ Object

Write a debug log message, provided the log level is :debug.

The logging data is unstructured, but gets passed to #report for structured logging under the component specified in the constructor and code ‘log’.

Calling #report is recommended over unstructured direct logging.

*args

One or more arguments that will be treated as strings and written in the presented order to the log, each on its own line of output (“\n” terminated).



222
223
224
 
# File 'lib/hoodoo/logger/logger.rb', line 222

def debug( *args )
  self.report( :debug, @component, :log, { '_data' => args } )
end

#error(*args) ⇒ Object

Write an error log message, regardless of logging level.

The logging data is unstructured, but gets passed to #report for structured logging under the component specified in the constructor and code ‘log’.

Calling #report is recommended over unstructured direct logging.

*args

One or more arguments that will be treated as strings and written in the presented order to the log, each on its own line of output (“\n” terminated).



272
273
274
 
# File 'lib/hoodoo/logger/logger.rb', line 272

def error( *args )
  self.report( :error, @component, :log, { '_data' => args } )
end

#info(*args) ⇒ Object

Write an info log message, provided the log level is :debug or :info.

The logging data is unstructured, but gets passed to #report for structured logging under the component specified in the constructor and code ‘log’.

Calling #report is recommended over unstructured direct logging.

*args

One or more arguments that will be treated as strings and written in the presented order to the log, each on its own line of output (“\n” terminated).



239
240
241
 
# File 'lib/hoodoo/logger/logger.rb', line 239

def info( *args )
  self.report( :info, @component, :log, { '_data' => args } )
end

#instances ⇒ Object

Returns an array of all log writer instances currently in use, in order of addition. See #add.



130
131
132
133
134
135
136
137
 
# File 'lib/hoodoo/logger/logger.rb', line 130

def instances

  # Implicit ordering relies on Ruby >= 1.9 documented behaviour of
  # preserving order of addition to a Hash.
  #
  @writers.keys

end

#remove(writer_instance) ⇒ Object

Remove a writer instance from this logger. If the instance has not been previously added, no error is raised.

Slow writers may take a while to finish processing and shut down in the background. As a result, this method might take a while to return. Internal default timeouts may even mean that the writer is still running (possibly entirely hung).

writer_instance

An instance of a subclass of Hoodoo::Logger::FastWriter or Hoodoo::Logger::SlowWriter.



110
111
112
113
 
# File 'lib/hoodoo/logger/logger.rb', line 110

def remove( writer_instance )
  communicator = @writers[ writer_instance ]
  @pool.remove( communicator ) unless communicator.nil?
end

#remove_all ⇒ Object

Remove all writer instances from this logger.

Slow writers may take a while to finish processing and shut down in the background. As a result, this method might take a while to return. Internal default timeouts may even mean that one or more slow writers are still running (possibly entirely hung).



122
123
124
125
 
# File 'lib/hoodoo/logger/logger.rb', line 122

def remove_all
  @pool.terminate()
  @writers = {}
end

#report(log_level, component, code, data) ⇒ Object

Logs a message using the structured logger. Whether or not log data is written in a stuctured manner depends upon the writer(s) in use (see #add). Structured writers preserve data structures like hashes or arrays rather than (say) dumping things out as strings into flat output streams.

As with flat logging methods #debug, #info, #warn and #error, a message is only logged if the logging threshold level (see #level=) is set to an equal or lower level.

log_level

Log level as a symbol - one of, from most trivial to most severe, :debug, :info, :warn or :error.

component

Component; for example, the resource name for a specific resource endpoint implementation, ‘Middleware’ for Hoodoo middleware itself, or some other name you think is useful. String or Symbol.

code

Component-defined code. Think of this in a manner similar to platform error codes, appearing after the “.”; messages related to the same thing should share the same code. The intent is to produce log data that someone can filter on code to get useful information about that specific aspect of a service implementation’s behaviour.

data

A Hash containing the level-, component- and code-dependent payload data to be logged.



197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/hoodoo/logger/logger.rb', line 197

def report( log_level, component, code, data )
  return unless self.report?( log_level )

  @pool.communicate(
    Payload.new(
      log_level: log_level,
      component: component,
      code:      code,
      data:      data
    )
  )
end

#report?(log_level) ⇒ Boolean

Given the log level configuration of this instance - see #level= and #level - should a message of the given log level be reported? Returns true if so else false.

This is mostly for internal use but external callers might find it useful from time to time, especially in tests.

log_level

Log level of interest as a Symbol - debug, info, warn or error.

Returns:

  • (Boolean) 


163
164
165
166
167
168
 
# File 'lib/hoodoo/logger/logger.rb', line 163

def report?( log_level )
  return false if log_level == :debug && @level != :debug
  return false if log_level == :info  && @level != :debug && @level != :info
  return false if log_level == :warn  && @level != :debug && @level != :info && @level != :warn
  return true
end

#wait ⇒ Object

Wait for all writers to finish writing all log messages sent up to the point of calling. Internal default timeouts for slow writers mean that hung or extremely slow/backlogged writers may not have finished by the time the call returns, but it’s necessary to enforce a timeout else this call may never return at all.



145
146
147
 
# File 'lib/hoodoo/logger/logger.rb', line 145

def wait
  @pool.wait()
end

#warn(*args) ⇒ Object

Write a warn log message, provided the log level is :debug, :info or :warn.

The logging data is unstructured, but gets passed to #report for structured logging under the component specified in the constructor and code ‘log’.

Calling #report is recommended over unstructured direct logging.

*args

One or more arguments that will be treated as strings and written in the presented order to the log, each on its own line of output (“\n” terminated).



256
257
258
 
# File 'lib/hoodoo/logger/logger.rb', line 256

def warn( *args )
  self.report( :warn, @component, :log, { '_data' => args } )
end