Module: Familia::Logging

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

Overview

The Logging module provides logging capabilities for Familia.

Familia uses a custom FamiliaLogger that extends the standard Ruby Logger with a TRACE level for detailed debugging output.

== Log Levels (from most to least verbose):

  • TRACE: Extremely detailed debugging (controlled by FAMILIA_TRACE env var)
  • DEBUG: Detailed debugging information
  • INFO: General informational messages
  • WARN: Warning messages
  • ERROR: Error messages
  • FATAL: Fatal errors that cause termination

== Usage: # Use default logger Familia.info "Connection established" Familia.warn "Cache miss"

# Set custom logger Familia.logger = Logger.new('familia.log')

# Trace-level debugging (requires FAMILIA_TRACE=true) Familia.trace :LOAD, redis_client, "user:123", "from cache"

Instance Method Summary collapse

Instance Method Details

#info(msg) ⇒ true

Log an informational message.

Examples:

Familia.info "Redis connection established"

Parameters:

  • msg (String) —

    The message to log

Returns:

  • (true) 


221
222
223
 
# File 'lib/familia/logging.rb', line 221

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

#ld(msg) ⇒ true?

Log a debug message (only when Familia.debug? is true).

Short for "log debug". Only outputs when FAMILIA_DEBUG environment variable is set to '1' or 'true'.

Examples:

Familia.ld "Cache lookup for user:123"
# Only outputs when FAMILIA_DEBUG=true

Parameters:

  • msg (String) —

    The message to log

Returns:

  • (true, nil) —

    Returns true if logged, nil if debug disabled



249
250
251
 
# File 'lib/familia/logging.rb', line 249

def ld(msg)
  logger.debug(msg) if Familia.debug?
end

#le(msg) ⇒ true

Log an error message.

Short for "log error".

Examples:

Familia.le "Failed to deserialize value: #{e.message}"

Parameters:

  • msg (String) —

    The message to log

Returns:

  • (true) 


263
264
265
 
# File 'lib/familia/logging.rb', line 263

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

#logger ⇒ FamiliaLogger

Get the logger instance, initializing with defaults if not yet set

Examples:

Set a custom logger

Familia.logger = Logger.new('familia.log')

Use the default logger

Familia.logger.info "Connection established"

Returns:



186
187
188
189
190
191
 
# File 'lib/familia/logging.rb', line 186

def logger
  @logger ||= FamiliaLogger.new($stderr).tap do |log|
    log.progname = name
    log.formatter = LogFormatter.new
  end
end

#logger=(new_logger) ⇒ Logger

Set a custom logger instance.

Allows replacing the default FamiliaLogger with any Logger-compatible object. Useful for integrating with application logging frameworks.

Examples:

Use Rails logger

Familia.logger = Rails.logger

Custom file logger

Familia.logger = Logger.new('familia.log').tap do |log|
  log.level = Logger::INFO
end

Parameters:

  • new_logger (Logger) —

    The logger to use

Returns:

  • (Logger) —

    The logger that was set



209
210
211
 
# File 'lib/familia/logging.rb', line 209

def logger=(new_logger)
  @logger = new_logger
end

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

Note:

Controlled by FAMILIA_TRACE environment variable (set to '1', 'true', or 'yes')

Note:

The instance_id can be a Redis client, Redis::Future, or nil

Logs a structured trace message for debugging Familia operations.

This method only executes when both FAMILIA_TRACE and FAMILIA_DEBUG environment variables are enabled.

Examples:

Familia.trace :LOAD, redis_client, "user:123", "from cache"
# Output: T, 10-05 20:43:09.843 pid:123 [456/789]: [LOAD] #<Redis> -> user:123 <-from cache

Parameters:

  • label (Symbol) —

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

  • instance_id (Object) (defaults to: nil) —

    The object instance being traced (e.g., Redis client)

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

    An identifier or key related to the operation being traced

  • extra_context (String, nil) (defaults to: nil) —

    Any extra details to include

Returns:

  • (nil) 


287
288
289
290
291
292
 
# File 'lib/familia/logging.rb', line 287

def trace(label, instance_id = nil, ident = nil, extra_context = nil)
  return unless trace_enabled? && Familia.debug?

  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) ⇒ true

Log a warning message.

Examples:

Familia.warn "Cache miss for key: user:123"

Parameters:

  • msg (String) —

    The message to log

Returns:

  • (true) 


233
234
235
 
# File 'lib/familia/logging.rb', line 233

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