Module: Postburner::Logging

Extended by:
ActiveSupport::Concern
Included in:
Job
Defined in:
app/concerns/postburner/logging.rb

Overview

Concern providing logging and exception tracking for Postburner jobs.

Provides methods for adding timestamped log entries and tracking exceptions in the job’s PostgreSQL audit trail. All logs are stored in JSONB arrays with timestamps, levels, and elapsed time tracking.

Examples:

Basic logging

class MyJob < Postburner::Job
  def perform(args)
    log "Starting processing"
    # ... work ...
    log! "Critical checkpoint reached"
  end
end

Exception tracking

class MyJob < Postburner::Job
  def perform(args)
    process_data(args)
  rescue => e
    log_exception!(e)
    raise
  end
end

Instance Method Summary collapse

Instance Method Details

#log(message, options = {}) ⇒ Array<Array>

Note:

Invalid log levels are coerced to :error

Appends a log message to the job’s logs array.

Adds timestamped log entry to in-memory logs array with bkid, level, message, and elapsed time. Does NOT persist to database immediately. Use #log! to persist immediately.

Examples:

log "Processing started"
log "Warning: rate limit approaching", level: :warning
log "Critical error occurred", level: :error

Parameters:

  • message (String) —

    Log message to append

  • options (Hash) (defaults to: {}) —

    Log options

Options Hash (options):

  • :level (Symbol) —

    Log level (:debug, :info, :warning, :error) - defaults to :info

Returns:

  • (Array<Array>) —

    Updated logs array

See Also:

  • #log!
  • #elapsed_ms
  • LOG_LEVELS


121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'app/concerns/postburner/logging.rb', line 121

def log(message, options={})
  options[:level] ||= :info
  options[:level] = :error unless LOG_LEVELS.member?(options[:level])

  self.logs << [
    Time.current, # time
    {
      bkid:     self.bkid,
      level:    options[:level], # level
      message:  message, # message
      elapsed:  self.elapsed_ms, # ms from start
    }
  ]
end

#log!(message, options = {}) ⇒ void

This method returns an undefined value.

Appends a log message and immediately persists to database.

Calls #log to append message, then persists logs array to database. Use this for important log messages that should be saved immediately.

Examples:

log! "Job started"
log! "Payment processed successfully", level: :info
log! "Retrying failed request", level: :warning

Parameters:

  • message (String) —

    Log message to append

  • options (Hash) (defaults to: {}) —

    Log options

Options Hash (options):

  • :level (Symbol) —

    Log level (:debug, :info, :warning, :error)

See Also:



154
155
156
157
 
# File 'app/concerns/postburner/logging.rb', line 154

def log!(message, options={})
  self.log(message, options)
  self.update_column :logs, self.logs
end

#log_exception(exception) ⇒ Array<Array>

Tracks an exception in the job’s errata array.

Appends exception details to the in-memory errata array with timestamp, class, message, and backtrace. Does NOT persist to database immediately. Use #log_exception! to persist immediately.

Examples:

begin
  # ... risky operation ...
rescue => e
  log_exception(e)
  raise
end

Parameters:

  • exception (Exception) —

    The exception to track

Returns:

  • (Array<Array>) —

    Updated errata array

See Also:



62
63
64
65
66
67
68
69
70
71
72
 
# File 'app/concerns/postburner/logging.rb', line 62

def log_exception(exception)
  self.errata << [
    Time.current,
    {
      bkid:       self.bkid,
      class:      exception.class,
      message:    exception.message,
      backtrace:  exception.backtrace,
    }
  ]
end

#log_exception!(exception) ⇒ void

This method returns an undefined value.

Tracks an exception and immediately persists to database.

Calls #log_exception to append exception details, then persists both errata and error_count to database via #persist_metadata!.

Examples:

begin
  # ... risky operation ...
rescue => e
  log_exception!(e)
  raise
end

Parameters:

  • exception (Exception) —

    The exception to track

See Also:



93
94
95
96
 
# File 'app/concerns/postburner/logging.rb', line 93

def log_exception!(exception)
  self.log_exception(exception)
  self.persist_metadata!
end