Add output logging framework with OTel and file backends

Introduce a pluggable output logging system that captures deploy output
and ships it to configurable destinations via a new `output:` section
in deploy.yml.

    output:
      otel:
        endpoint: http://otel-gateway:4318
      file:
        path: /var/log/kamal/

OTel backend ships OTLP log records via HTTP to /v1/logs. Structured
lifecycle events (kamal.start/complete/failed) mark command boundaries
with deployment metadata. Stream output lines are tagged per-host
(server.address) and by stream type (log.iostream). Format follows
OTel semantic conventions: standard attributes where applicable
(deployment.*, exception.*, service.*), custom attributes namespaced
under kamal.*.

File backend writes one timestamped log file per command
(e.g. 20260327_143022_production_deploy.log) with a completion/failure
summary line at the end.

Key design decisions:
- `modify` method replaces `with_lock` as the integration point for all
  infrastructure-modifying commands, scoping output capture and
  instrumenting deploy lifecycle via ActiveSupport::Notifications
- SSHKit output captured via custom Formatter with thread-local context
  for per-host and stream type tagging
- Best-effort: output logger failures never block or fail a deploy

Co-Authored-By: Donal McBreen <donal@37signals.com>

Author: lewispb

lib/kamal/cli/accessory.rb

@@ -4,7 +4,7 @@
 class Kamal::Cli::Accessory < Kamal::Cli::Base
   desc "boot [NAME]", "Boot new accessory service on host (use NAME=all to boot all accessories)"
   def boot(name, prepare: true)
-    with_lock do
+    modify(lock: true) do
       if name == "all"
         KAMAL.accessory_names.each { |accessory_name| boot(accessory_name) }
       else
@@ -42,7 +42,7 @@ def boot(name, prepare: true)
 
   desc "upload [NAME]", "Upload accessory files to host", hide: true
   def upload(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           accessory.files.each do |(local, config)|
@@ -61,7 +61,7 @@ def upload(name)
 
   desc "directories [NAME]", "Create accessory directories on host", hide: true
   def directories(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           accessory.directories.each do |(local, config)|
@@ -76,7 +76,7 @@ def directories(name)
 
   desc "reboot [NAME]", "Reboot existing accessory on host (stop container, remove container, start new container; use NAME=all to boot all accessories)"
   def reboot(name)
-    with_lock do
+    modify(lock: true) do
       if name == "all"
         KAMAL.accessory_names.each { |accessory_name| reboot(accessory_name) }
       else
@@ -91,7 +91,7 @@ def reboot(name)
 
   desc "start [NAME]", "Start existing accessory container on host"
   def start(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           execute *KAMAL.auditor.record("Started #{name} accessory"), verbosity: :debug
@@ -107,7 +107,7 @@ def start(name)
 
   desc "stop [NAME]", "Stop existing accessory container on host"
   def stop(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           execute *KAMAL.auditor.record("Stopped #{name} accessory"), verbosity: :debug
@@ -124,7 +124,7 @@ def stop(name)
 
   desc "restart [NAME]", "Restart existing accessory container on host"
   def restart(name)
-    with_lock do
+    modify(lock: true) do
       stop(name)
       start(name)
     end
@@ -213,7 +213,7 @@ def logs(name)
 
   desc "pull_image [NAME]", "Pull accessory image on host", hide: true
   def pull_image(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           execute *KAMAL.auditor.record("Pull #{name} accessory image"), verbosity: :debug
@@ -227,7 +227,7 @@ def pull_image(name)
   option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
   def remove(name)
     confirming "This will remove all containers, images and data directories for #{name}. Are you sure?" do
-      with_lock do
+      modify(lock: true) do
         if name == "all"
           KAMAL.accessory_names.each { |accessory_name| remove_accessory(accessory_name) }
         else
@@ -239,7 +239,7 @@ def remove(name)
 
   desc "remove_container [NAME]", "Remove accessory container from host", hide: true
   def remove_container(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           execute *KAMAL.auditor.record("Remove #{name} accessory container"), verbosity: :debug
@@ -251,7 +251,7 @@ def remove_container(name)
 
   desc "remove_image [NAME]", "Remove accessory image from host", hide: true
   def remove_image(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           execute *KAMAL.auditor.record("Removed #{name} accessory image"), verbosity: :debug
@@ -263,7 +263,7 @@ def remove_image(name)
 
   desc "remove_service_directory [NAME]", "Remove accessory directory used for uploaded files and data directories from host", hide: true
   def remove_service_directory(name)
-    with_lock do
+    modify(lock: true) do
       with_accessory(name) do |accessory, hosts|
         on(hosts) do
           execute *accessory.remove_service_directory
@@ -277,7 +277,7 @@ def remove_service_directory(name)
   option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
   def upgrade(name)
     confirming "This will restart all accessories" do
-      with_lock do
+      modify(lock: true) do
         host_groups = options[:rolling] ? KAMAL.accessory_hosts : [ KAMAL.accessory_hosts ]
         host_groups.each do |hosts|
           host_list = Array(hosts).join(",")

lib/kamal/cli/app.rb

@@ -1,7 +1,7 @@
 class Kamal::Cli::App < Kamal::Cli::Base
   desc "boot", "Boot app on servers (or reboot app if already running)"
   def boot
-    with_lock do
+    modify(lock: true) do
       say "Get most recent version available as an image...", :magenta unless options[:version]
       using_version(version_or_latest) do |version|
         say "Start container with version #{version} (or reboot if already running)...", :magenta
@@ -42,7 +42,7 @@ def boot
 
   desc "start", "Start existing app container on servers"
   def start
-    with_lock do
+    modify(lock: true) do
       on_roles(KAMAL.roles, hosts: KAMAL.app_hosts, parallel: KAMAL.config.boot.parallel_roles) do |host, role|
         app = KAMAL.app(role: role, host: host)
         execute *KAMAL.auditor.record("Started app version #{KAMAL.config.version}"), verbosity: :debug
@@ -61,7 +61,7 @@ def start
 
   desc "stop", "Stop app container on servers"
   def stop
-    with_lock do
+    modify(lock: true) do
       on_roles(KAMAL.roles, hosts: KAMAL.app_hosts, parallel: KAMAL.config.boot.parallel_roles) do |host, role|
         app = KAMAL.app(role: role, host: host)
         execute *KAMAL.auditor.record("Stopped app", role: role), verbosity: :debug
@@ -233,7 +233,7 @@ def logs
 
   desc "remove", "Remove app containers and images from servers"
   def remove
-    with_lock do
+    modify(lock: true) do
       stop
       remove_containers
       remove_images
@@ -243,7 +243,7 @@ def remove
 
   desc "live", "Set the app to live mode"
   def live
-    with_lock do
+    modify(lock: true) do
       on_roles(KAMAL.roles, hosts: KAMAL.proxy_hosts) do |host, role|
         execute *KAMAL.app(role: role, host: host).live if role.running_proxy?
       end
@@ -256,7 +256,7 @@ def live
   def maintenance
     maintenance_options = { drain_timeout: options[:drain_timeout] || KAMAL.config.drain_timeout, message: options[:message] }
 
-    with_lock do
+    modify(lock: true) do
       on_roles(KAMAL.roles, hosts: KAMAL.proxy_hosts) do |host, role|
         execute *KAMAL.app(role: role, host: host).maintenance(**maintenance_options) if role.running_proxy?
       end
@@ -265,7 +265,7 @@ def maintenance
 
   desc "remove_container [VERSION]", "Remove app container with given version from servers", hide: true
   def remove_container(version)
-    with_lock do
+    modify(lock: true) do
       on_roles(KAMAL.roles, hosts: KAMAL.app_hosts) do |host, role|
         execute *KAMAL.auditor.record("Removed app container with version #{version}", role: role), verbosity: :debug
         execute *KAMAL.app(role: role, host: host).remove_container(version: version)
@@ -275,7 +275,7 @@ def remove_container(version)
 
   desc "remove_containers", "Remove all app containers from servers", hide: true
   def remove_containers
-    with_lock do
+    modify(lock: true) do
       on_roles(KAMAL.roles, hosts: KAMAL.app_hosts) do |host, role|
         execute *KAMAL.auditor.record("Removed all app containers", role: role), verbosity: :debug
         execute *KAMAL.app(role: role, host: host).remove_containers
@@ -285,7 +285,7 @@ def remove_containers
 
   desc "remove_images", "Remove all app images from servers", hide: true
   def remove_images
-    with_lock do
+    modify(lock: true) do
       on(hosts_removing_all_roles) do
         execute *KAMAL.auditor.record("Removed all app images"), verbosity: :debug
         execute *KAMAL.app.remove_images
@@ -295,7 +295,7 @@ def remove_images
 
   desc "remove_app_directories", "Remove the app directories from servers", hide: true
   def remove_app_directories
-    with_lock do
+    modify(lock: true) do
       on(hosts_removing_all_roles) do |host|
         execute *KAMAL.server.remove_app_directory, raise_on_non_zero_exit: false
         execute *KAMAL.auditor.record("Removed #{KAMAL.config.app_directory}"), verbosity: :debug
@@ -347,7 +347,7 @@ def version_or_latest
 
     def with_lock_if_stopping
       if options[:stop]
-        with_lock { yield }
+        modify(lock: true) { yield }
       else
         yield
       end

lib/kamal/cli/base.rb

@@ -72,6 +72,17 @@ def print_runtime
         puts "  Finished all in #{sprintf("%.1f seconds", runtime)}"
       end
 
+      def modify(lock: false)
+        KAMAL.modify(command: command, subcommand: subcommand) do
+          lock ? with_lock { yield } : yield
+        end
+      end
+
+      def say(message = "", *)
+        super
+        KAMAL.log(message.to_s)
+      end
+
       def with_lock
         if KAMAL.holding_lock?
           yield