Module: Familia::Logging

Included in:
Familia
Defined in:
lib/familia/logging.rb

Overview

The Logging module provides a set of methods and constants for logging messages at various levels of severity. It is designed to be used with the Ruby Logger class to facilitate logging in applications.

== Constants: Logger::TRACE:: A custom log level for trace messages, typically used for very detailed debugging information.

== Methods: trace:: Logs a message at the TRACE level. This method is only available if the Familia::Refinements::LoggerTrace is used.

debug:: Logs a message at the DEBUG level. This is used for low-level system information for debugging purposes.

info:: Logs a message at the INFO level. This is used for general information about system operation.

warn:: Logs a message at the WARN level. This is used for warning messages, typically for non-critical issues that require attention.

error:: Logs a message at the ERROR level. This is used for error messages, typically for critical issues that require immediate attention.

fatal:: Logs a message at the FATAL level. This is used for very severe error events that will presumably lead the application to abort.

== Usage: To use the Logging module, you need to include the Familia::Refinements::LoggerTrace module and use the using keyword to enable the refinement. This will add the TRACE log level and the trace method to the Logger class.

Example: require 'logger'

module Familia::Refinements::LoggerTrace refine Logger do TRACE = 0

  def trace(progname = nil, &block)
    add(TRACE, nil, progname, &block)
  end
end

end

using Familia::Refinements::LoggerTrace

logger = Logger.new(STDOUT) logger.trace("This is a trace message") logger.debug("This is a debug message") logger.info("This is an info message") logger.warn("This is a warning message") logger.error("This is an error message") logger.fatal("This is a fatal message")

In this example, the Familia::Refinements::LoggerTrace module is defined with a refinement for the Logger class. The TRACE constant and trace method are added to the Logger class within the refinement. The using keyword is used to apply the refinement in the scope where it's needed.

== Conditions: The trace method and TRACE log level are only available if the Familia::Refinements::LoggerTrace module is used with the using keyword. Without this, the Logger class will not have the trace method or the TRACE log level.

== Minimum Ruby Version: This module requires Ruby 2.0.0 or later to use refinements.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



104
105
106
 
# File 'lib/familia/logging.rb', line 104

def logger
  @logger
end

Instance Method Details

#info(*msg) ⇒ Object 



109
110
111
 
# File 'lib/familia/logging.rb', line 109

def info(*msg)
  @logger.info(*msg)
end

#ld(*msg) ⇒ Object 



117
118
119
120
121
 
# File 'lib/familia/logging.rb', line 117

def ld(*msg)
  return unless Familia.debug?

  @logger.debug(*msg)
end

#le(*msg) ⇒ Object 



123
124
125
 
# File 'lib/familia/logging.rb', line 123

def le(*msg)
  @logger.error(*msg)
end

#trace(label, instance_id = nil, ident = nil, extra_context = nil) ⇒ nil

Note:

This method only executes if Familia::Refinements::LoggerTrace::ENABLED is true.

Note:

The dbclient can be a Database object, Redis::Future (used in pipelined and multi blocks), or nil (when the database connection isn't relevant).

Logs a trace message for debugging purposes if Familia.debug? is true.

Examples:

Familia.trace :LOAD, Familia.dbclient(uri), objkey if Familia.debug?

Parameters:

  • label (Symbol) —

    A label for the trace message (e.g., :EXPAND, :FROMREDIS, :LOAD, :EXISTS).

  • instance_id (defaults to: nil)
  • ident (String) (defaults to: nil) —

    An identifier or key related to the operation being traced.

  • extra_context (Array<String>, String, nil) (defaults to: nil) —

    Any extra details to include.

Returns:

  • (nil) 


145
146
147
148
149
150
151
 
# File 'lib/familia/logging.rb', line 145

def trace(label, instance_id = nil, ident = nil, extra_context = nil)
  return unless Familia::Refinements::LoggerTrace::ENABLED

  # Let the other values show nothing when nil, but make it known for the focused value
  ident_str = (ident.nil? ? '<nil>' : ident).to_s
  @logger.trace format('[%s] %s -> %s <-%s', label, instance_id, ident_str, extra_context)
end

#warn(*msg) ⇒ Object 



113
114
115
 
# File 'lib/familia/logging.rb', line 113

def warn(*msg)
  @logger.warn(*msg)
end