Module: NRSER::Log

Extended by:
SingleForwardable
Includes:
Mixin
Defined in:
lib/nrser/log/formatters/color.rb,
lib/nrser/log/formatters/mixin.rb,
lib/nrser/log.rb

Overview

Unified logging support via SemanticLogger.

See Also:

Defined Under Namespace

Modules: Appender, Formatters, Mixin Classes: Logger

Utility Class Methods collapse

Setup Class Methods collapse

Class Method Summary collapse

Methods included from Mixin

included, #logger, #logger=

Class Method Details

.appender ⇒ SemanticLogger::Subscriber | nil

The current “main” appender (destination), if any.

This is just to simplify things in simple cases, you can always still add multiple appenders.

Returns:

  • (SemanticLogger::Subscriber | nil) 


436
437
438
 
# File 'lib/nrser/log.rb', line 436

def self.appender
  @appender
end

.body(*tokens) ⇒ Object 



497
498
499
 
# File 'lib/nrser/log.rb', line 497

def self.body *tokens
  formatter.body( *tokens ) if body?
end

.body=(tokens) ⇒ Object 



502
503
504
505
506
 
# File 'lib/nrser/log.rb', line 502

def self.body= tokens
  if body?
    formatter.body = tokens
  end
end

.body? ⇒ Boolean

Returns:

  • (Boolean) 


492
493
494
 
# File 'lib/nrser/log.rb', line 492

def self.body?
  formatter && formatter.respond_to?( :body )
end

.formatter ⇒ nil, SemanticLogger::Formatters::Default

Short-cut for ‘.appender.formatter`.

Returns:

  • (nil) —

    If there is no appender.

  • (SemanticLogger::Formatters::Default) —

    If there is an appender, the appender’s ‘#formatter` attribute.



449
450
451
 
# File 'lib/nrser/log.rb', line 449

def self.formatter
  appender.formatter if appender
end

.header(*tokens) ⇒ nil, HeaderTokens

Calls ‘.formatter.header` if there is a header?.

Parameters:

  • *tokens (Array<Symbol>) —

    Optional list of token symbols to set as the header format.

    When empty, the method works as a getter, returning the current header format tokens.

Returns:

  • (nil) —

    If there is no appender or it’s formatter doesn’t have a header.

  • (HeaderTokens) —

    The current header tokens.

See Also:



480
481
482
 
# File 'lib/nrser/log.rb', line 480

def self.header *tokens
  formatter.header( *tokens ) if header?
end

.header=(tokens) ⇒ Object 



485
486
487
488
489
 
# File 'lib/nrser/log.rb', line 485

def self.header= tokens
  if header?
    formatter.header = tokens
  end
end

.header? ⇒ Boolean

Is there a header formatter?

Returns:

  • (Boolean) —

    ‘true` if there is an formatter and it responds to ’:header’.

    If it returns ‘false`, it means there is no appender attached or it’s formatter does not mix in NRSER::Log::Formatters::Mixin.

    In this case you can’t read or write to the header, so header= won’t do anything.



465
466
467
 
# File 'lib/nrser/log.rb', line 465

def self.header?
  formatter && formatter.respond_to?( :header )
end

.level ⇒ :trace | :debug | :info | :warn | :error | :fatal

Global / default log level, which we always normalize to a symbol.

Returns:

  • (:trace | :debug | :info | :warn | :error | :fatal) 


222
223
224
 
# File 'lib/nrser/log.rb', line 222

def self.level
  level_sym_for SemanticLogger.default_level
end

.level=(level) ⇒ :trace | :debug | :info | :warn | :error | :fatal

Set the global default log level.

Returns:

  • (:trace | :debug | :info | :warn | :error | :fatal) —

    Log level symbol.

Raises:

  • When ‘level` is invalid.



246
247
248
 
# File 'lib/nrser/log.rb', line 246

def self.level= level
  SemanticLogger.default_level = level_sym_for level
end

.level_from_ENV(prefix:) ⇒ Object 



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/nrser/log.rb', line 251

def self.level_from_ENV prefix:
  if NRSER.truthy? ENV["#{ prefix }_TRACE"]
    return :trace
  elsif NRSER.truthy? ENV["#{ prefix }_DEBUG"]
    return :debug
  end
  
  level = ENV["#{ prefix }_LOG_LEVEL"]
  
  unless level.nil? || level == ''
    return level
  end
  
  nil
end

.level_index ⇒ Fixnum

Note:

There is some funkiness around level indexes that I think/hope I wrote down somewhere, so use with some caution/research.

Integer level index. Forwards to SemanticLogger.default_level_index.

Returns:

  • (Fixnum) 


235
236
237
 
# File 'lib/nrser/log.rb', line 235

def self.level_index
  SemanticLogger.default_level_index
end

.level_sym_for(level) ⇒ :trace | :debug | :info | :warn | :error | :fatal

Normalize a level name or number to a symbol, raising if it’s not valid.

Relies on Semantic Logger’s “internal” SemanticLogger.level_to_index method.

Parameters:

  • Representation (Symbol | String | Integer) —

    of a level in one of the following formats:

    1. Symbol - verified as member of SemanticLogger::LEVELS and returned.

    2. String - accepts string representations of the level symbols, case insensitive.

    3. Integer - interpreted as a Ruby StdLib Logger / Rails Logger level, which are different than Semantic Logger’s!

Returns:

  • (:trace | :debug | :info | :warn | :error | :fatal) —

    Log level symbol.

Raises:

  • When ‘level` is invalid.

See Also:



209
210
211
212
213
214
215
 
# File 'lib/nrser/log.rb', line 209

def self.level_sym_for level
  if SemanticLogger::LEVELS.include? level
    level
  else
    SemanticLogger.index_to_level SemanticLogger.level_to_index( level )
  end
end

.logger_for(subject) ⇒ Object

Class Methods



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/nrser/log.rb', line 91

def self.logger_for subject
  # key = logger_type_and_name_from subject
  # 
  # if @__loggers__.key? key
  #   ref = @__loggers__[key]
  # 
  #   if ref.weakref_alive?
  #     return
  # 
  instance = NRSER::Log::Logger.new subject
end

.logger_type_and_name_from(subject) ⇒ return_type

TODO:

Document logger_name_and_type method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/nrser/log.rb', line 119

def self.logger_type_and_name_from subject
  case subject
  when String
    [:string, subject]
    
  when Module
    [:const, subject.safe_name]
    
  when Array
    # NOTE  Prob bad to use {NRSER::Types} here since logging gets
    #       required so early, and we want it to *work* then... seems like
    #       it would introduce lots of dependency mess. So just use plain
    #       ol' Ruby.
    unless  subject.length == 2 &&
            subject[0].is_a?( Symbol ) &&
            subject[1].is_a?( String )
      raise NRSER::ArgumentError.new \
        "Subject arrays must be [Symbol, String]; received", subject,
        subject: subject,
        details: -> {
          <<~END
            When passing an {Array}, it must be a pair:
            
            1.  `[0]` must be a {Symbol} that is the logger's subject
                *type*.
                
            2.  `[1]` must be a {String} that is the logger's subject
                *name*.
          END
        }
    end
    
    pair = subject.dup
    pair[0] = :const if [:module, :class].include? pair[0]
    pair
    
  when Hash
    unless subject.length == 1
      raise NRSER::ArgumentError.new \
        "Hash subjects must be a single key/value pair",
        subject: subject
    end
    
    pair = subject.first
    
    unless  pair[0].is_a?( Symbol ) &&
            pair[1].is_a?( String )
      raise NRSER::ArgumentError.new \
        "Subject hashes must be a Symbol key and String value",
        subject: subject
    end
    
    pair[0] = :const if [:module, :class].include? pair[0]
    
    pair
    
  else
    raise NRSER::TypeError.new \
      "Expected `subject` to be String, Module, Array or Hash, ",
      "found #{ subject.class }",
      subject: subject
  end
end

.processor ⇒ SemanticLogger::Subscriber

Shortcut to SemanticLogger::Processor.instance.

Returns:

  • (SemanticLogger::Subscriber) —

    You would think this would be a SemanticLogger::Processor, but it’s actually an appender (SemanticLogger::Subscriber is the base class of appenders, sigh…).



419
420
421
 
# File 'lib/nrser/log.rb', line 419

def self.processor
  SemanticLogger::Processor.instance
end

.setup!(level: nil, dest: nil, sync: nil, say_hi: :debug, application: nil, env_var_prefix: nil, header: nil, body: nil) ⇒ nil

Setup logging.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (nil) 


280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/nrser/log.rb', line 280

def self.setup! level: nil,
                dest: nil,
                sync: nil,
                say_hi: :debug,
                application: nil,
                env_var_prefix: nil,
                header: nil,
                body: nil
  
  unless @__mutex__.try_lock
    raise ThreadError, <<~END
      Mutex is already held.
      
      You should pretty generally NOT have multiple threads trying to
      setup logging at once or re-enter {NRSER::Log.setup}!
    END
  end
  
  # Wrap around everything to make sure we release the mutex
  begin
    # Setup main appender if needed
    setup_appender! dest
    
    # Set sync/async processor state
    setup_sync! sync
    
    # If we didn't receive a level, check the ENV
    if level.nil?
      if env_var_prefix.nil? && !application.nil?
        env_var_prefix = application.gsub( /[^a-zA-Z0-0_]+/, '_' ).upcase
      end
      
      level = level_from_ENV prefix: env_var_prefix
    end
    
    # If we ended up with a level, try to set it (will only log a warning
    # if it fails, not raise, which could crash things on boot)
    setup_level! level unless level.nil?
    
    self.application = application unless application.nil?
    
    # Setup formatter header and body tokens, if needed
    setup_formatter_tokens! :header, header
    setup_formatter_tokens! :body, body
    
  ensure
    # Make sure we release the mutex; don't need to hold it for the rest
    @__mutex__.unlock
  end
  
  # Name the main thread so that `process_info` doesn't look so lame
  setup_main_thread_name!
  
  # Possibly say hi
  setup_say_hi say_hi, dest, sync
  
  nil
  
rescue Exception => error
  # Suppress errors in favor of a warning
  
  logger.warn \
    message: "Error setting up logging",
    payload: {
      args: {
        level: level,
        dest: dest,
        env_var_prefix: env_var_prefix,
        say_hi: say_hi,
      },
    },
    exception: error
  
  nil
end

.setup_for_CLI!(dest: $stderr, sync: true, **kwds) ⇒ nil

Call setup! with some default keywords that are nice for CLI apps.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (nil) 


362
363
364
365
366
 
# File 'lib/nrser/log.rb', line 362

def self.setup_for_CLI! dest: $stderr,
                        sync: true,
                        **kwds
  setup! dest: dest, sync: sync, **kwds
end

.setup_for_console!(dest: $stderr, sync: true, header: { delete: :process_info }, **kwds) ⇒ nil

Call setup! with some default keywords that are nice for interactive session (console/REPL) usage.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (nil) 


378
379
380
381
382
383
384
385
386
387
 
# File 'lib/nrser/log.rb', line 378

def self.setup_for_console! dest: $stderr,
                            sync: true,
                            header: { delete: :process_info },
                            **kwds
  setup! \
    dest: dest,
    sync: sync,
    header: header,
    **kwds
end

.setup_for_rspec!(dest: $stderr, sync: true, header: { delete: :process_info }, **kwds) ⇒ nil

Call setup! but provides default for running RSpec tests: sync, write to

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (nil) 


396
397
398
399
400
401
402
403
404
405
 
# File 'lib/nrser/log.rb', line 396

def self.setup_for_rspec! dest: $stderr,
                            sync: true,
                            header: { delete: :process_info },
                            **kwds
  setup! \
    dest: dest,
    sync: sync,
    header: header,
    **kwds
end

.sync? ⇒ Boolean

Returns:

  • (Boolean) 


424
425
426
 
# File 'lib/nrser/log.rb', line 424

def self.sync?
  processor.is_a? NRSER::Log::Appender::Sync
end