Class: NRSER::Log::Logger

Inherits:
SemanticLogger::Logger
  • Object
show all
Defined in:
lib/nrser/log/logger.rb

Overview

Extension of SemanticLogger::Logger to add and customize behavior.

Defined Under Namespace

Classes: Catcher

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(subject, level: nil, filter: nil) ⇒ Logger

Overrides SemanticLogger::Logger#initialize¹ to extend “subject” support to instances (as well as modules/classes and strings).

> ¹ SemanticLogger::Logger#initialize is just a proxy to > SemanticLogger::Base#initialize, which is what this implementation > is based off.

Parameters:

  • subject (Module | String | INSTANCE) —

    Name of the class, module, or other identifier for which the log messages are being logged

  • level: (nil | Symbol) (defaults to: nil) —

    Only allow log entries of this level or higher to be written to this appender For example if set to :warn, this appender would only log ‘:warn` and `:fatal` log messages when other appenders could be logging `:info` and lower.

  • filter: (nil | Regexp | Proc<(SemanticLogger::Log) => Boolean>) (defaults to: nil) —

    1. RegExp: Only include log messages where the class name matches the supplied regular expression. All other messages will be ignored.

    2. Proc: Only include log messages where the supplied Proc returns ‘true`.

Raises:



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/nrser/log/logger.rb', line 108

def initialize subject, level: nil, filter: nil
  # Support filtering all messages to this logger using a Regular Expression
  # or Proc
  unless filter.nil? || filter.is_a?( Regexp ) || filter.is_a?( Proc )
    raise NRSER::TypeError,
      ":filter must be a Regexp or Proc",
      filter: filter,
      subject: subject,
      level: level
  end

  @filter = filter.is_a?(Regexp) ? filter.freeze : filter
  
  # @name   = klass.is_a?(String) ? klass : klass.name
  case subject
  when String
    @name = subject
    @awesome_name = subject
    @type = :string
    
  when Module
    @name = subject.safe_name
    @awesome_name = subject.ai multiline: true, raw: true
    @type = subject.is_a?( Class ) ? :class : :module
    
  else
    @name = subject.to_s
    @awesome_name = subject.ai multiline: true, raw: true
    @type = :instance
    
  end
  
  if level.nil?
    # Allow the global default level to determine this loggers log level
    @level_index = nil
    @level       = nil
  else
    self.level = level
  end
end

Instance Attribute Details

#awesome_name ⇒ String (readonly)

TODO document ‘awesome_name` attribute.

Returns:



74
75
76
 
# File 'lib/nrser/log/logger.rb', line 74

def awesome_name
  @awesome_name
end

Instance Method Details

#catch(**options) ⇒ Catcher

A sweet way to try something and just log any Exception.

Useful for situations where the operation is question is not necessary or can not be allowed to propagate errors, but you would like to record and/or let the user know that it failed.

Create a new Catcher for this logger that defines the log methods (‘#error`, `warn`, … `:trace`) to also accept blocks that will be executed in a `begin`/`rescue`.

If the block raises, the catcher will call the log method, adding the caught Exception.

Examples:

Log any error as a warning

logger.catch.warn do
  something_that_may_raise
end

# We should "always" get to here

Log any error as warning with message and payload

logger.catch.warn(
  "This thing failed!",
  some_detail: some_value,
) do
  something_that_may_raise
end

# We should "always" get to here

Return a custom value on error

result = logger.catch( on_fail: :blue ).debug do
  what_is_your_favorite_color?
end

Parameters:

Returns:



193
194
195
 
# File 'lib/nrser/log/logger.rb', line 193

def catch **options
  Catcher.new self, **options
end

#with_level(level, &block) ⇒ RESULT

Set the level for the execution of ‘&block`, restoring it to it’s previous level afterwards.

Like what SemanticLogger::Logger#silence does (which just forwards to SemanticLogger.silence), but applies only to this logger (where as SemanticLogger::Logger#silence applies on to the global default level).

Useful for quickly turning down the log level to see trace/debug output from a specific section.

Parameters:

  • level (Symbol?) —

    One of SemanticLogger::LEVELS or ‘nil` to use the global default level.

  • Proc<() (Proc<() => RESULT] &block Block to execute with the `level`.) —

    > RESULT] &block

    Block to execute with the ‘level`.

Returns:

  • (RESULT) —

    Whatever ‘&block` returns.



217
218
219
220
221
222
223
224
225
226
 
# File 'lib/nrser/log/logger.rb', line 217

def with_level level, &block
  prior_level = @level
  self.level = level
  
  begin
    block.call
  ensure
    self.level = prior_level
  end
end