fix(service): improve error diagnostics for distribution start failures

localization/strings/en-US/Resources.resw

@@ -1036,9 +1036,29 @@ Falling back to NAT networking.</value>
     <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment>
   </data>
   <data name="MessageDistributionFailedToStart" xml:space="preserve">
-    <value>The distribution failed to start. Error code: {}, failure step: {}</value>
+    <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value>
     <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment>
   </data>
+  <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve">
+    <value>The distribution failed to start because WSL could not mount the distribution's virtual disk. Failure step: {} ({}). Linux error code: {}.
+Check the distribution's disk and any disk-related settings in .wslconfig, such as 'swapFile', before trying again.</value>
+    <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment>
+  </data>
+  <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve">
+    <value>format the distribution's virtual disk</value>
+  </data>
+  <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve">
+    <value>mount the distribution's virtual disk</value>
+  </data>
+  <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve">
+    <value>launch the distribution</value>
+  </data>
+  <data name="MessageCreateInstanceStepRunTar" xml:space="preserve">
+    <value>complete distribution import</value>
+  </data>
+  <data name="MessageCreateInstanceStepUnknown" xml:space="preserve">
+    <value>start the distribution</value>
+  </data>
   <data name="MessageDiskCorrupted" xml:space="preserve">
     <value>The distribution failed to start because its virtual disk is corrupted.</value>
   </data>

src/windows/service/exe/WslCoreInstance.cpp

@@ -15,6 +15,29 @@ Module Name:
 #include "precomp.h"
 #include "WslCoreInstance.h"
 
+namespace {
+std::wstring CreateInstanceStepDescription(_In_ LX_MINI_CREATE_INSTANCE_STEP step)
+{
+    switch (step)
+    {
+    case LxInitCreateInstanceStepFormatDisk:
+        return wsl::shared::Localization::MessageCreateInstanceStepFormatDisk();
+
+    case LxInitCreateInstanceStepMountDisk:
+        return wsl::shared::Localization::MessageCreateInstanceStepMountDisk();
+
+    case LxInitCreateInstanceStepLaunchSystemDistro:
+        return wsl::shared::Localization::MessageCreateInstanceStepLaunchDistribution();
+
+    case LxInitCreateInstanceStepRunTar:
+        return wsl::shared::Localization::MessageCreateInstanceStepRunTar();
+
+    default:
+        return wsl::shared::Localization::MessageCreateInstanceStepUnknown();
+    }
+}
+} // namespace
+
 WslCoreInstance::WslCoreInstance(
     _In_ HANDLE UserToken,
     _In_ wil::unique_socket& InitSocket,
@@ -57,17 +80,49 @@ WslCoreInstance::WslCoreInstance(
         }
     }
 
+    const auto stepDescription = CreateInstanceStepDescription(result.FailureStep);
+    WSL_LOG(
+        "CreateInstanceGuestResult",
+        TraceLoggingValue(m_configuration.Name.c_str(), "distroName"),
+        TraceLoggingValue(m_instanceId, "instanceId"),
+        TraceLoggingValue(m_runtimeId, "vmId"),
+        TraceLoggingValue(result.Result, "linuxError"),
+        TraceLoggingValue(static_cast<int>(result.FailureStep), "failureStep"),
+        TraceLoggingValue(stepDescription.c_str(), "failureStepDescription"),
+        TraceLoggingValue(result.Pid, "pid"),
+        TraceLoggingValue(result.ConnectPort, "connectPort"));
+
     if (result.Result != 0)
     {
+        WSL_LOG(
+            "CreateInstanceGuestFailure",
+            TraceLoggingLevel(WINEVENT_LEVEL_WARNING),
+            TraceLoggingValue(m_configuration.Name.c_str(), "distroName"),
+            TraceLoggingValue(m_instanceId, "instanceId"),
+            TraceLoggingValue(m_runtimeId, "vmId"),
+            TraceLoggingValue(result.Result, "linuxError"),
+            TraceLoggingValue(static_cast<int>(result.FailureStep), "failureStep"),
+            TraceLoggingValue(stepDescription.c_str(), "failureStepDescription"));
+
         // N.B. EUCLEAN (117) can be returned if the disk's journal is corrupted.
         if ((result.Result == EINVAL || result.Result == 117) && result.FailureStep == LxInitCreateInstanceStepMountDisk)
         {
             THROW_HR(WSL_E_DISK_CORRUPTED);
         }
+        else if (result.FailureStep == LxInitCreateInstanceStepMountDisk)
+        {
+            wsl::windows::common::ExecutionContext stepContext(wsl::windows::common::Context::MountDisk);
+            THROW_HR_WITH_USER_ERROR(
+                E_FAIL,
+                wsl::shared::Localization::MessageDistributionFailedToStartMountDisk(
+                    static_cast<int>(result.FailureStep), stepDescription, result.Result));
+        }
         else
         {
             THROW_HR_WITH_USER_ERROR(
-                E_FAIL, wsl::shared::Localization::MessageDistributionFailedToStart(result.Result, static_cast<int>(result.FailureStep)));
+                E_FAIL,
+                wsl::shared::Localization::MessageDistributionFailedToStart(
+                    static_cast<int>(result.FailureStep), stepDescription, result.Result));
         }
     }
 

src/windows/service/exe/WslCoreVm.cpp

@@ -1164,10 +1164,23 @@ std::shared_ptr<LxssRunningInstance> WslCoreVm::CreateInstance(
     _In_ ULONG ExportFlags,
     _Out_opt_ ULONG* ConnectPort)
 {
+    WSL_LOG(
+        "CreateInstanceAttachDiskBegin",
+        TraceLoggingValue(Configuration.Name.c_str(), "distroName"),
+        TraceLoggingValue(InstanceId, "instanceId"),
+        TraceLoggingValue(m_runtimeId, "vmId"));
+
     // Add the VHD to the machine.
     auto lock = m_lock.lock_exclusive();
     const auto lun = AttachDiskLockHeld(Configuration.VhdFilePath.c_str(), DiskType::VHD, MountFlags::None, {}, false, m_userToken.get());
 
+    WSL_LOG(
+        "CreateInstanceAttachDiskEnd",
+        TraceLoggingValue(Configuration.Name.c_str(), "distroName"),
+        TraceLoggingValue(InstanceId, "instanceId"),
+        TraceLoggingValue(m_runtimeId, "vmId"),
+        TraceLoggingValue(lun, "lun"));
+
     // Launch the init daemon and create the instance.
     int flags = LxMiniInitMessageFlagNone;
     std::wstring sharedMemoryRoot{};
@@ -1208,6 +1221,21 @@ std::shared_ptr<LxssRunningInstance> WslCoreVm::CreateInstance(
     message.WriteString(message->UserProfileOffset, userProfile);
     m_miniInitChannel.SendMessage<LX_MINI_INIT_MESSAGE>(message.Span());
 
+    WSL_LOG(
+        "CreateInstanceLaunchMessageSent",
+        TraceLoggingValue(Configuration.Name.c_str(), "distroName"),
+        TraceLoggingValue(InstanceId, "instanceId"),
+        TraceLoggingValue(m_runtimeId, "vmId"),
+        TraceLoggingValue(static_cast<int>(MessageType), "messageType"),
+        TraceLoggingValue(flags, "flags"),
+        TraceLoggingValue(WI_IsFlagSet(flags, LxMiniInitMessageFlagLaunchSystemDistro), "launchSystemDistro"));
+
+    WSL_LOG(
+        "CreateInstanceAwaitGuestResult",
+        TraceLoggingValue(Configuration.Name.c_str(), "distroName"),
+        TraceLoggingValue(InstanceId, "instanceId"),
+        TraceLoggingValue(m_runtimeId, "vmId"));
+
     return CreateInstanceInternal(
         InstanceId, Configuration, ReceiveTimeout, DefaultUid, ClientLifetimeId, WI_IsFlagSet(flags, LxMiniInitMessageFlagLaunchSystemDistro), ConnectPort);
 }