Feature: Add optional output to maintenance task to display output from the task

Author: scotttam

README.md

@@ -579,6 +579,49 @@ module Maintenance
 end
 ```
 
+### Task Output
+
+Maintenance tasks can log output during execution, which is displayed in the web UI.
+
+To use this feature:
+
+1. Run the migration to add the `output` column to your database:
+   ```bash
+   rails generate migration AddOutputToMaintenanceTasksRuns output:text
+   rails db:migrate
+   ```
+
+2. Use the `log_output` method in your task's `process` method:
+
+```ruby
+module Maintenance
+  class DataCleanupTask < MaintenanceTasks::Task
+    def collection
+      User.where(last_sign_in_at: nil)
+    end
+
+    def process(user)
+      log_output("Processing user: #{user.email} (ID: #{user.id})")
+      
+      if user.created_at < 1.year.ago
+        log_output("  -> Marking user for cleanup")
+        user.update!(cleanup_flag: true)
+        log_output("  -> Successfully processed")
+      else
+        log_output("  -> Skipping: user created recently")
+      end
+    end
+  end
+end
+```
+
+The output:
+- Is stored in the database with the run record
+- Persists permanently and can be viewed anytime
+- Is displayed in a formatted box on the run details page
+- Updates in real-time as the task executes
+
+
 ### Subscribing to instrumentation events
 
 If you are interested in actioning a specific task event, please refer to the

app/jobs/concerns/maintenance_tasks/task_job_concern.rb

@@ -119,6 +119,10 @@ def task_iteration(input)
     def before_perform
       @run = arguments.first
       @task = @run.task
+      # Set the run as an instance variable on the task to enable features
+      # like log_output that need to write data back to the run.
+      # This creates a bidirectional reference between the Run and Task.
+      @task.instance_variable_set(:@run, @run)
       if @task.has_csv_content?
         @task.csv_content = @run.csv_file.download
       end

app/models/maintenance_tasks/run.rb

@@ -443,6 +443,20 @@ def masked_arguments
       argument_filter.filter(arguments)
     end
 
+    # Appends output to the existing output in the database if the column exists.
+    #
+    # @param new_output [String] the output to append.
+    def append_output(new_output)
+      return unless self.class.column_names.include?("output")
+      
+      # Reload output from database to get the latest value
+      current_output = self.class.where(id: id).pluck(:output).first || ""
+      separator = current_output.present? ? "\n" : ""
+      updated_output = current_output + separator + new_output
+      
+      self.class.where(id: id).update_all(output: updated_output)
+    end
+
     private
 
     def instrument_status_change

app/models/maintenance_tasks/task.rb

@@ -41,7 +41,7 @@ class NotFoundError < NameError; end
 
     define_callbacks :start, :complete, :error, :cancel, :pause, :interrupt
 
-    attr_accessor :metadata
+    attr_accessor :metadata, :output
 
     class << self
       # Finds a Task with the given name.
@@ -335,5 +335,14 @@ def count
     def enumerator_builder(cursor:)
       nil
     end
+
+    # Appends a message to the task output.
+    #
+    # @param message [String] the message to append to the output.
+    def log_output(message)
+      return unless defined?(@run) && @run
+
+      @run.append_output(message)
+    end
   end
 end

app/views/maintenance_tasks/runs/_output.html.erb

@@ -0,0 +1,7 @@
+<% if output.present? %>
+  <div class="content">
+    <h6 class="title is-6">Task Output</h6>
+    <pre class="box has-background-light"><%= output %></pre>
+  </div>
+  <hr>
+<% end %>

app/views/maintenance_tasks/runs/_run.html.erb

@@ -26,6 +26,7 @@
   <%= render "maintenance_tasks/runs/arguments", arguments: run.masked_arguments %>
   <%= tag.hr if run.csv_file.present? || run.arguments.present? && run.metadata.present? %>
   <%= render "maintenance_tasks/runs/metadata", metadata: run.metadata %>
+  <%= render "maintenance_tasks/runs/output", output: run.output if run.respond_to?(:output) %>
 
   <div class="buttons">
     <% if run.paused? %>

db/migrate/20250117000000_add_output_to_maintenance_tasks_runs.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddOutputToMaintenanceTasksRuns < ActiveRecord::Migration[7.0]
+  def change
+    add_column(:maintenance_tasks_runs, :output, :text)
+  end
+end

test/dummy/app/tasks/maintenance/output_test_task.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Maintenance
+  class OutputTestTask < MaintenanceTasks::Task
+    def collection
+      (1..5).to_a
+    end
+
+    def process(element)
+      log_output("Processing element #{element}")
+      log_output("Square of #{element} is #{element * element}")
+    end
+  end
+end

test/dummy/db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2023_06_22_035229) do
+ActiveRecord::Schema.define(version: 2025_01_17_000000) do
   create_table "active_storage_attachments", force: :cascade do |t|
     t.string "name", null: false
     t.string "record_type", null: false
@@ -52,19 +52,20 @@
     t.string "error_class"
     t.string "error_message"
     t.text "backtrace"
-    t.datetime "created_at", precision: 6, null: false
-    t.datetime "updated_at", precision: 6, null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
     t.text "arguments"
     t.integer "lock_version", default: 0, null: false
     t.text "metadata"
+    t.text "output"
     t.index ["task_name", "status", "created_at"], name: "index_maintenance_tasks_runs", order: { created_at: :desc }
   end
 
   create_table "posts", force: :cascade do |t|
     t.string "title"
     t.string "content"
-    t.datetime "created_at", precision: 6, null: false
-    t.datetime "updated_at", precision: 6, null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
   end
 
   add_foreign_key "active_storage_attachments", "active_storage_blobs", column: "blob_id"

test/models/maintenance_tasks/task_data_index_test.rb

@@ -20,12 +20,15 @@ class TaskDataIndexTest < ActiveSupport::TestCase
         "Maintenance::NoCollectionTask",
         # duplicate due to fixtures containing two active runs of this task
         "Maintenance::NoCollectionTask",
+        "Maintenance::OutputTestTask",
         "Maintenance::ParamsTask",
         "Maintenance::TestTask",
         "Maintenance::UpdatePostsInBatchesTask",
         "Maintenance::UpdatePostsModulePrependedTask",
         "Maintenance::UpdatePostsTask",
         "Maintenance::UpdatePostsThrottledTask",
+        "MaintenanceTasks::TaskOutputTest::NoCollectionTaskWithOutput",
+        "MaintenanceTasks::TaskOutputTest::TestTaskWithOutput",
       ]
       assert_equal expected, TaskDataIndex.available_tasks.map(&:name)
     end