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

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

#le(*msg) ⇒ Object 



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

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

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

Note:

This method only executes if LoggerTraceRefinement::ENABLED is true.

Note:

The redis_instance can be a Redis object, Redis::Future (used in pipelined and multi blocks), or nil (when the redis connection isn’t relevant).

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

Examples:

Familia.trace :LOAD, Familia.redis(uri), objkey, caller(1..1) if
Familia.debug?

Parameters:

  • label (Symbol) —

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

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

    The Redis 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) 


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

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

  # Usually redis_instance is a Redis 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
  # redis connection isn't relevant.
  instance_id = if redis_instance
    case redis_instance
    when Redis
      redis_instance.id.respond_to?(:to_s) ? redis_instance.id.to_s : redis_instance.class.name
    when Redis::Future
      "Redis::Future"
    else
      redis_instance.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