Module: NRSER::Log

Extended by:
SingleForwardable
Includes:
Mixin
Defined in:
lib/nrser/log/formatters/color.rb,
lib/nrser/log/types.rb,
lib/nrser/log/plugin.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, Types Classes: Logger, Plugin

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) 


532
533
534
 
# File 'lib/nrser/log.rb', line 532

def self.appender
  @appender
end

.body(*tokens) ⇒ Object 



593
594
595
 
# File 'lib/nrser/log.rb', line 593

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

.body=(tokens) ⇒ Object 



598
599
600
601
602
 
# File 'lib/nrser/log.rb', line 598

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

.body? ⇒ Boolean

Returns:

  • (Boolean) 


588
589
590
 
# File 'lib/nrser/log.rb', line 588

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

.env_var_prefix ⇒ nil, ...

Get the current ENV var prefix to use looking for config (when values are not explictly provided).

Returns:

  • (nil) —

    A prefix has not been sucessfully set, and we couldn’t figure one out from application.

  • (false) —

    Looking for config in ENV has been explicitly disabled.

  • (String) —

    The ENV var name prefix we’ll use looking for logging config.



260
261
262
263
264
265
266
 
# File 'lib/nrser/log.rb', line 260

def self.env_var_prefix
  return @env_var_prefix unless @env_var_prefix.nil?

  return application.to_s.env_varize unless application.nil?
  
  return nil
end

.env_var_prefix=(prefix) ⇒ nil, String | false

Set the env_var_prefix.

Parameters:

  • prefix (String | false) —

    Value to set the prefix to. ‘false` disables looking up config in the ENV.

    If anything other than ‘false` or a String that satisfies Sys::Env.var_name? is passed a warning will be logged, the value will be ignored, and `nil` will be returned.

Returns:

  • (nil) —

    ‘prefix` was a bad value and the internal variable was not set. A warning was also logged.

  • (String | false) —

    The value was set to ‘prefix`.



286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/nrser/log.rb', line 286

def self.env_var_prefix= prefix
  unless prefix == false || NRSER::Sys::Env.var_name?( prefix )
    logger.warn \
      "Bad NRSER::Log.env_var_prefix; must `false` or a String matching" +
      "#{ NRSER::Sys::Env::VAR_NAME_RE }. Ignoring...",
      value: prefix
    
    return nil
  end

  @env_var_prefix = prefix
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.



545
546
547
 
# File 'lib/nrser/log.rb', line 545

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:



576
577
578
 
# File 'lib/nrser/log.rb', line 576

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

.header=(tokens) ⇒ Object 



581
582
583
584
585
 
# File 'lib/nrser/log.rb', line 581

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.



561
562
563
 
# File 'lib/nrser/log.rb', line 561

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) 


218
219
220
 
# File 'lib/nrser/log.rb', line 218

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.



242
243
244
 
# File 'lib/nrser/log.rb', line 242

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

.level_from_env(prefix: self.env_var_prefix) ⇒ nil, ...

Try to find a log level in the ENV.

Parameters:

  • prefix: (String | false | nil) (defaults to: self.env_var_prefix) —

    The prefix to look under.

Returns:

  • (nil) —

    We either didn’t look or we didn’t find.

  • (Symbol) —

    One of SemanticLogger::LEVELS, returned because we found a NRSER.truthy? ‘<prefix>_DEBUG` or `<prefix>_TRACE`.

  • (String) —

    Value found at ‘<prefix>_LOG_LEVEL`. **Note that this may not be a valid level - this method does NOT check!**.



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/nrser/log.rb', line 316

def self.level_from_env prefix: self.env_var_prefix
  # Bail with a `nil` if we can't figure out a prefix (it's `nil`) or
  # looking in the ENV has been disabled (it's `false`).
  return nil unless 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) 


231
232
233
 
# File 'lib/nrser/log.rb', line 231

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:



205
206
207
208
209
210
211
 
# File 'lib/nrser/log.rb', line 205

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



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

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.



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
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
 
# File 'lib/nrser/log.rb', line 115

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…).



515
516
517
 
# File 'lib/nrser/log.rb', line 515

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:

  • env_var_prefix: (String | false | nil) (defaults to: nil) —

    Prefix to ENV var names to look for logging setup config under, like ‘<prefix>_LOG_LEVEL`, `<prefix>_DEBUG` and `<prefix>_TRACE`.

    If ‘nil` (the default), we’ll try to use ‘application` to guess a prefix.

    You can disable any ENV lookups by passing ‘false`.

Returns:

  • (nil) 


355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/nrser/log.rb', line 355

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 so that any logging *in here* hopefully
    # has somewhere to go
    setup_appender! dest

    # Set the application, which we may use for the ENV var prefix
    self.application = application unless application.nil?

    # Set the ENV var prefix, if we received one
    self.env_var_prefix = env_var_prefix unless env_var_prefix.nil?
    
    # Set sync/async processor state
    setup_sync! sync
    
    # If we didn't receive a level, check the ENV
    if level.nil?
      level = level_from_env
    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?
    
    # 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:

  • env_var_prefix: (String | false | nil) —

    Prefix to ENV var names to look for logging setup config under, like ‘<prefix>_LOG_LEVEL`, `<prefix>_DEBUG` and `<prefix>_TRACE`.

    If ‘nil` (the default), we’ll try to use ‘application` to guess a prefix.

    You can disable any ENV lookups by passing ‘false`.

Returns:

  • (nil) 


438
439
440
441
442
 
# File 'lib/nrser/log.rb', line 438

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

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

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

Parameters:

  • add_main_logger: (Boolean) (defaults to: true) —

    Define a ‘logger` method at the top level (global) that gets a logger for the main object.

Returns:

  • (nil) 


462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'lib/nrser/log.rb', line 462

def self.setup_for_console! add_main_logger: true,
                            application: $0,
                            dest: $stderr,
                            header: { delete: :process_info },
                            sync: true,
                            **kwds
  setup! \
    dest: dest,
    sync: sync,
    header: header,
    application: application,
    **kwds
  
  if add_main_logger
    TOPLEVEL_BINDING.eval <<~END
      def logger
        NRSER::Log[self]
      end
    END
  end

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:

  • env_var_prefix: (String | false | nil) —

    Prefix to ENV var names to look for logging setup config under, like ‘<prefix>_LOG_LEVEL`, `<prefix>_DEBUG` and `<prefix>_TRACE`.

    If ‘nil` (the default), we’ll try to use ‘application` to guess a prefix.

    You can disable any ENV lookups by passing ‘false`.

Returns:

  • (nil) 


492
493
494
495
496
497
498
499
500
501
 
# File 'lib/nrser/log.rb', line 492

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) 


520
521
522
 
# File 'lib/nrser/log.rb', line 520

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