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 LoggerTraceRefinement 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 LoggerTraceRefinement 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 LoggerTraceRefinement refine Logger do TRACE = 0

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

using LoggerTraceRefinement

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 LoggerTraceRefinement 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 LoggerTraceRefinement 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.



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

def logger
  @logger
end

Instance Method Details

#info(*msg) ⇒ Object 



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

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

#ld(*msg) ⇒ Object 



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

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

  @logger.debug(*msg)
end

#le(*msg) ⇒ Object 



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

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

#trace(label, dbclient, ident, context = nil) ⇒ nil

Note:

This method only executes if LoggerTraceRefinement::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, caller(1..1) if
Familia.debug?

Parameters:

  • label (Symbol) —

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

  • dbclient (Redis, Redis::Future, nil) —

    The Database instance or Future being used.

  • ident (String) —

    An identifier or key related to the operation being traced.

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

    The calling context, typically obtained from caller or caller.first. Default is nil.

Returns:

  • (nil) 


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
 
# File 'lib/familia/logging.rb', line 148

def trace(label, dbclient, ident, context = nil)
  return unless LoggerTraceRefinement::ENABLED

  # Usually dbclient is a Database object, but it could be
  # a Redis::Future which is what is used inside of pipelined
  # and multi blocks. In some contexts it's nil where the
  # database connection isn't relevant.
  instance_id = if dbclient
                  case dbclient
                  when Redis
                    dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
                  when Redis::Future
                    'Redis::Future'
                  else
                    dbclient.class.name
                  end
                end

  codeline = if context
               context = [context].flatten
               context.reject! { |line| line =~ %r{lib/familia} }
               context.first
             end

  @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
end

#warn(*msg) ⇒ Object 



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

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