CI observability enhancements. (#1193)

- Adds a a `--log-root` option to `swift system start`, propagating the
value as `CONTAINER_LOG_ROOT` to services for logging to files instead
of the OS log facility. This is not a "production" capability as it
neither merges nor rotates logs.
- Currently we don't collect logs on CI builds, and we don't have
permission to run the `log` command there. The PR adds `--log-root` to
the CI test phase, archives the results, and uploads the archive as an
artifact.
- Use FilePath from swift-system for the log root. Foundation URL is a
bit of a footgun for filesystem paths, so unless we identify a
showstopper, we should incrementally transition to this type everywhere
except where we really need network URLs.
- Output the hostname of the CI runner at the start of the test phase so
we can identify runner-specific issues where they exist.
- Fix formatting for log messages with multiple metadata items, and fix
unstructured messages on instances that weren't found using `grep -r
'log\.' Sources`.
- Adds command reference documentation for `--log-root`.

Sources/ContainerPlugin/LogRoot.swift

@@ -0,0 +1,39 @@
+//===----------------------------------------------------------------------===//
+// 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 Foundation
+import SystemPackage
+
+/// Provides the application data root path.
+public struct LogRoot {
+
+    private static let envPath = ProcessInfo.processInfo.environment[Self.environmentName].flatMap {
+        $0.isEmpty ? nil : FilePath($0)
+    }
+
+    /// The environment variable that if set, determines the root directory for log files.
+    /// Otherwise, the application uses the macOS log facility.
+    public static let environmentName = "CONTAINER_LOG_ROOT"
+
+    /// The path object for the log file root directory
+    public static let path = envPath.map {
+        guard !$0.isAbsolute else { return $0 }
+        return FilePath(FileManager.default.currentDirectoryPath).appending($0.components)
+    }
+
+    /// The pathname to the log file root directory
+    public static let pathname = path?.string
+}

Sources/ContainerPlugin/PluginLoader.swift

@@ -17,12 +17,15 @@
 import ContainerizationOS
 import Foundation
 import Logging
+import SystemPackage
 
 public struct PluginLoader: Sendable {
     private let appRoot: URL
 
     private let installRoot: URL
 
+    private let logRoot: FilePath?
+
     private let pluginDirectories: [URL]
 
     private let pluginFactories: [PluginFactory]
@@ -39,6 +42,7 @@ public struct PluginLoader: Sendable {
     public init(
         appRoot: URL,
         installRoot: URL,
+        logRoot: FilePath?,
         pluginDirectories: [URL],
         pluginFactories: [PluginFactory],
         log: Logger? = nil
@@ -48,6 +52,7 @@ public struct PluginLoader: Sendable {
         self.pluginResourceRoot = pluginResourceRoot
         self.appRoot = appRoot
         self.installRoot = installRoot
+        self.logRoot = logRoot
         self.pluginDirectories = pluginDirectories
         self.pluginFactories = pluginFactories
         self.log = log
@@ -223,6 +228,12 @@ extension PluginLoader {
         var env = Self.filterEnvironment()
         env[ApplicationRoot.environmentName] = appRoot.path(percentEncoded: false)
         env[InstallRoot.environmentName] = installRoot.path(percentEncoded: false)
+        if let logRoot {
+            env[LogRoot.environmentName] =
+                logRoot.isAbsolute
+                ? logRoot.string
+                : FilePath(FileManager.default.currentDirectoryPath).appending(logRoot.components).string
+        }
 
         let processedArgs = (args ?? ["start"]) + (debug ? ["--debug"] : [])
         let plist = LaunchPlist(