Module: Postburner::Tracked

Extended by:
ActiveSupport::Concern
Defined in:
lib/postburner/tracked.rb

Overview

Concern for ActiveJob classes to opt-in to PostgreSQL tracking.

Simply include this module in your ActiveJob class to enable full audit trail persistence in PostgreSQL. Without this, jobs execute as “default” jobs (Beanstalkd only, no PostgreSQL overhead).

Examples:

Opt-in to tracking

class ProcessPayment < ApplicationJob
  include Postburner::Tracked  # ← Enables PostgreSQL audit trail

  def perform(payment_id)
    log "Processing payment #{payment_id}"
    # ... work ...
    log! "Payment processed successfully"
  end
end

Without tracking (default mode)

class SendEmail < ApplicationJob
  # No Postburner::Tracked - executes as default job

  def perform(email)
    # Fast execution, no PostgreSQL overhead
  end
end

Instance Method Summary collapse

Instance Method Details

#bk ⇒ Beaneater::Job?

Returns the Beanstalkd job object for direct queue operations.

Provides access to the underlying Beaneater job object through the TrackedJob wrapper. Use this to perform Beanstalkd operations like touch, bury, release, etc.

Examples:

Extend TTR during long operation

def perform(file_id)
  file = File.find(file_id)
  file.each_line do |line|
    # ... process line ...
    bk&.touch  # Extend TTR
  end
end

Other Beanstalkd operations

bk&.bury              # Bury the job
bk&.release(pri: 0)   # Release with priority
bk&.stats             # Get job statistics

Returns:

  • (Beaneater::Job, nil) —

    Beanstalkd job object or nil if not available

See Also:



144
145
146
 
# File 'lib/postburner/tracked.rb', line 144

def bk
  postburner_job&.bk
end

#extend! ⇒ void

This method returns an undefined value.

Extends the job’s time-to-run (TTR) in Beanstalkd.

Convenience method that calls touch on the Beanstalkd job, extending the TTR by the original TTR value. Use this during long-running operations to prevent the job from timing out.

Examples:

Process large file line by line

def perform(file_id)
  file = File.find(file_id)
  file.each_line do |line|
    # ... process line ...
    extend!  # Extend TTR to prevent timeout
  end
end

See Also:



167
168
169
 
# File 'lib/postburner/tracked.rb', line 167

def extend!
  postburner_job&.extend!
end

#log(message, level: :info) ⇒ void

This method returns an undefined value.

Appends a log message to the job’s audit trail.

Only available for tracked jobs. Logs are stored in the Postburner::Job record’s ‘logs` JSONB array.

Examples:

def perform(user_id)
  log "Starting user processing"
  # ... work ...
  log "Completed successfully", level: :info
end

Parameters:

  • message (String) —

    Log message

  • level (Symbol) (defaults to: :info) —

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



58
59
60
 
# File 'lib/postburner/tracked.rb', line 58

def log(message, level: :info)
  postburner_job&.log(message, level: level)
end

#log!(message, level: :info) ⇒ void

This method returns an undefined value.

Appends a log message and immediately persists to database.

Use this for important log messages that should be saved immediately rather than batched with other updates.

Examples:

def perform(payment_id)
  log! "Critical: Processing high-value payment #{payment_id}"
end

Parameters:

  • message (String) —

    Log message

  • level (Symbol) (defaults to: :info) —

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



77
78
79
 
# File 'lib/postburner/tracked.rb', line 77

def log!(message, level: :info)
  postburner_job&.log!(message, level: level)
end

#log_exception(exception) ⇒ void

This method returns an undefined value.

Tracks an exception in the job’s errata array.

Appends exception details (class, message, backtrace) to the in-memory errata array. Does NOT persist immediately.

Examples:

def perform(user_id)
  process_user(user_id)
rescue => e
  log_exception(e)
  raise
end

Parameters:

  • exception (Exception) —

    The exception to track



98
99
100
 
# File 'lib/postburner/tracked.rb', line 98

def log_exception(exception)
  postburner_job&.log_exception(exception)
end

#log_exception!(exception) ⇒ void

This method returns an undefined value.

Tracks an exception and immediately persists to database.

Examples:

def perform(user_id)
  process_user(user_id)
rescue CriticalError => e
  log_exception!(e)
  raise
end

Parameters:

  • exception (Exception) —

    The exception to track



116
117
118
 
# File 'lib/postburner/tracked.rb', line 116

def log_exception!(exception)
  postburner_job&.log_exception!(exception)
end