Use StderrLogHandler for rich logging features. (apple#1066)

- Facilitates apple#507, apple#642.
- Plumb logger with logger option access into every command.
- StderrLogHandler allows logging to be enhanced for ANSI color mode for
log levels, JSONL log output, replacing `--debug` with `--level level`.
- Global logger is now just an Application.swift fileprivate only used
for initial args processing.
- Log with timestamp at debug and trace level.
- Metadata output is crude at present; we can refine this in a
follow-up.

Author: jglogan

Sources/ContainerCommands/Application.swift

@@ -25,17 +25,18 @@ import Foundation
 import Logging
 import TerminalProgress
 
+// This logger is only used until `asyncCommand.run()`.
 // `log` is updated only once in the `validate()` method.
-nonisolated(unsafe) var log = {
-    LoggingSystem.bootstrap(StreamLogHandler.standardError)
+private nonisolated(unsafe) var bootstrapLogger = {
+    LoggingSystem.bootstrap({ _ in StderrLogHandler() })
     var log = Logger(label: "com.apple.container")
     log.logLevel = .info
     return log
 }()
 
-public struct Application: AsyncParsableCommand {
+public struct Application: AsyncLoggableCommand {
     @OptionGroup
-    var global: Flags.Global
+    public var logOptions: Flags.Logging
 
     public init() {}
 
@@ -171,16 +172,16 @@ public struct Application: AsyncParsableCommand {
             installRoot: systemHealth.installRoot,
             pluginDirectories: pluginDirectories,
             pluginFactories: pluginFactories,
-            log: log
+            log: bootstrapLogger
         )
     }
 
     public func validate() throws {
         // Not really a "validation", but a cheat to run this before
         // any of the commands do their business.
         let debugEnvVar = ProcessInfo.processInfo.environment["CONTAINER_DEBUG"]
-        if self.global.debug || debugEnvVar != nil {
-            log.logLevel = .debug
+        if self.logOptions.debug || debugEnvVar != nil {
+            bootstrapLogger.logLevel = .debug
         }
         // Ensure we're not running under Rosetta.
         if try isTranslated() {

Sources/ContainerCommands/AsyncLoggableCommand.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+import ContainerAPIClient
+import ContainerLog
+import Logging
+
+public protocol AsyncLoggableCommand: AsyncParsableCommand {
+    var logOptions: Flags.Logging { get }
+}
+
+extension AsyncLoggableCommand {
+    /// A shared logger instance configured based on the command's options
+    public var log: Logger {
+        var logger = Logger(label: "container", factory: { _ in StderrLogHandler() })
+
+        logger.logLevel = logOptions.debug ? .debug : .info
+
+        return logger
+    }
+}

Sources/ContainerCommands/BuildCommand.swift

@@ -27,7 +27,7 @@ import NIO
 import TerminalProgress
 
 extension Application {
-    public struct BuildCommand: AsyncParsableCommand {
+    public struct BuildCommand: AsyncLoggableCommand {
         public init() {}
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
@@ -122,6 +122,9 @@ extension Application {
         @Option(name: .long, help: ArgumentHelp("Builder shim vsock port", valueName: "port"))
         var vsockPort: UInt32 = 8088
 
+        @OptionGroup
+        public var logOptions: Flags.Logging
+
         @Argument(help: "Build directory")
         var contextDir: String = "."
 
@@ -145,7 +148,7 @@ extension Application {
                         group.cancelAll()
                     }
 
-                    group.addTask { [vsockPort, cpus, memory] in
+                    group.addTask { [vsockPort, cpus, memory, log] in
                         while true {
                             do {
                                 let container = try await ClientContainer.get(id: "buildkit")
@@ -166,6 +169,7 @@ extension Application {
                                 try await BuilderStart.start(
                                     cpus: cpus,
                                     memory: memory,
+                                    log: log,
                                     progressUpdate: progress.handler
                                 )
 

Sources/ContainerCommands/Builder/Builder.swift

@@ -15,9 +15,10 @@
 //===----------------------------------------------------------------------===//
 
 import ArgumentParser
+import ContainerAPIClient
 
 extension Application {
-    public struct BuilderCommand: AsyncParsableCommand {
+    public struct BuilderCommand: AsyncLoggableCommand {
         public init() {}
 
         public static let builderResourceDir = "builder"
@@ -30,5 +31,8 @@ extension Application {
                 BuilderStop.self,
                 BuilderDelete.self,
             ])
+
+        @OptionGroup
+        public var logOptions: Flags.Logging
     }
 }

Sources/ContainerCommands/Builder/BuilderDelete.swift

@@ -20,7 +20,7 @@ import ContainerizationError
 import Foundation
 
 extension Application {
-    public struct BuilderDelete: AsyncParsableCommand {
+    public struct BuilderDelete: AsyncLoggableCommand {
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "delete"
@@ -33,7 +33,7 @@ extension Application {
         var force = false
 
         @OptionGroup
-        var global: Flags.Global
+        public var logOptions: Flags.Logging
 
         public init() {}
 

Sources/ContainerCommands/Builder/BuilderStart.swift

@@ -24,10 +24,11 @@ import ContainerizationError
 import ContainerizationExtras
 import ContainerizationOCI
 import Foundation
+import Logging
 import TerminalProgress
 
 extension Application {
-    public struct BuilderStart: AsyncParsableCommand {
+    public struct BuilderStart: AsyncLoggableCommand {
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "start"
@@ -45,7 +46,7 @@ extension Application {
         var memory: String = "2048MB"
 
         @OptionGroup
-        var global: Flags.Global
+        public var logOptions: Flags.Logging
 
         public init() {}
 
@@ -60,11 +61,11 @@ extension Application {
                 progress.finish()
             }
             progress.start()
-            try await Self.start(cpus: self.cpus, memory: self.memory, progressUpdate: progress.handler)
+            try await Self.start(cpus: self.cpus, memory: self.memory, log: log, progressUpdate: progress.handler)
             progress.finish()
         }
 
-        static func start(cpus: Int64?, memory: String?, progressUpdate: @escaping ProgressUpdateHandler) async throws {
+        static func start(cpus: Int64?, memory: String?, log: Logger, progressUpdate: @escaping ProgressUpdateHandler) async throws {
             await progressUpdate([
                 .setDescription("Fetching BuildKit image"),
                 .setItemsName("blobs"),
@@ -256,6 +257,7 @@ extension Application {
             )
 
             try await container.startBuildKit(progressUpdate, taskManager)
+            log.debug("starting BuildKit and BuildKit-shim")
         }
     }
 }
@@ -278,8 +280,6 @@ extension ClientContainer {
             try await process.start()
             await taskManager?.finish()
             try io.closeAfterStart()
-
-            log.debug("starting BuildKit and BuildKit-shim")
         } catch {
             try? await stop()
             try? await delete()

Sources/ContainerCommands/Builder/BuilderStatus.swift

@@ -21,7 +21,7 @@ import ContainerizationExtras
 import Foundation
 
 extension Application {
-    public struct BuilderStatus: AsyncParsableCommand {
+    public struct BuilderStatus: AsyncLoggableCommand {
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "status"
@@ -36,7 +36,7 @@ extension Application {
         var quiet = false
 
         @OptionGroup
-        var global: Flags.Global
+        public var logOptions: Flags.Logging
 
         public init() {}
 

Sources/ContainerCommands/Builder/BuilderStop.swift

@@ -20,7 +20,7 @@ import ContainerizationError
 import Foundation
 
 extension Application {
-    public struct BuilderStop: AsyncParsableCommand {
+    public struct BuilderStop: AsyncLoggableCommand {
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "stop"
@@ -29,7 +29,7 @@ extension Application {
         }
 
         @OptionGroup
-        var global: Flags.Global
+        public var logOptions: Flags.Logging
 
         public init() {}
 

Sources/ContainerCommands/Container/ContainerCreate.swift

@@ -22,7 +22,7 @@ import Foundation
 import TerminalProgress
 
 extension Application {
-    public struct ContainerCreate: AsyncParsableCommand {
+    public struct ContainerCreate: AsyncLoggableCommand {
         public init() {}
 
         public static let configuration = CommandConfiguration(
@@ -45,7 +45,7 @@ extension Application {
         var imageFetchFlags: Flags.ImageFetch
 
         @OptionGroup
-        var global: Flags.Global
+        public var logOptions: Flags.Logging
 
         @Argument(help: "Image name")
         var image: String

Sources/ContainerCommands/Container/ContainerDelete.swift

@@ -20,7 +20,7 @@ import ContainerizationError
 import Foundation
 
 extension Application {
-    public struct ContainerDelete: AsyncParsableCommand {
+    public struct ContainerDelete: AsyncLoggableCommand {
         public init() {}
 
         public static let configuration = CommandConfiguration(
@@ -35,7 +35,7 @@ extension Application {
         var force = false
 
         @OptionGroup
-        var global: Flags.Global
+        public var logOptions: Flags.Logging
 
         @Argument(help: "Container IDs")
         var containerIds: [String] = []
@@ -82,6 +82,7 @@ extension Application {
             var failed = [String]()
             let force = self.force
             let all = self.all
+            let logger = log
             try await withThrowingTaskGroup(of: String?.self) { group in
                 for container in containers {
                     group.addTask {
@@ -97,7 +98,7 @@ extension Application {
                             print(container.id)
                             return nil
                         } catch {
-                            log.error("failed to delete container \(container.id): \(error)")
+                            logger.error("failed to delete container \(container.id): \(error)")
                             return container.id
                         }
                     }