Allow running agent in debugging mode for specific node task (#4838)

This change introduces a new knob called VSTSAGENT_DEBUG_TASK which can be set to either task GUID or task name and version (like AzureCLIV2). Once set, the agent will execute node process for any pipeline run which includes this task in debug mode, which will wait for the debugger to be attached.

Author: kboom

src/Agent.Listener/Agent.cs

@@ -216,6 +216,13 @@ public async Task<int> ExecuteCommand(CommandSettings command)
                 Trace.Info($"Set agent startup type - {startType}");
                 HostContext.StartupType = startType;
 
+                bool debugModeEnabled = command.GetDebugMode();
+                settings.DebugMode = debugModeEnabled;
+                store.SaveSettings(settings);
+                if (debugModeEnabled)
+                {
+                    Trace.Warning("Agent is running in debug mode, don't use it in production");
+                }
                 if (PlatformUtil.RunningOnWindows)
                 {
                     if (store.IsAutoLogonConfigured())

src/Agent.Listener/CommandLine/RunAgent.cs

@@ -18,5 +18,8 @@ public class RunAgent : BaseCommand
 
         [Option(Constants.Agent.CommandLine.Args.StartupType)]
         public string StartupType { get; set; }
+
+        [Option(Constants.Agent.CommandLine.Flags.DebugMode)]
+        public bool DebugMode { get; set; }
     }
 }

src/Agent.Listener/CommandSettings.cs

@@ -544,6 +544,11 @@ public bool GetRunOnce()
                    TestFlag(Run?.RunOnce, Constants.Agent.CommandLine.Flags.Once);
         }
 
+        public bool GetDebugMode()
+        {
+            return TestFlag(Run?.DebugMode, Constants.Agent.CommandLine.Flags.DebugMode);
+        }
+
         public bool GetDeploymentPool()
         {
             return TestFlag(Configure?.DeploymentPool, Constants.Agent.CommandLine.Flags.DeploymentPool);

src/Agent.Sdk/Knob/AgentKnobs.cs

@@ -199,6 +199,12 @@ public class AgentKnobs
             new EnvironmentKnobSource("VSTSAGENT_TRACE"),
             new BuiltInDefaultKnobSource(string.Empty));
 
+        public static readonly Knob DebugTask = new Knob(
+            nameof(DebugTask),
+            "If the agent executes a task which ID or name matches the value provided, it will run the task so that it will wait for debugger to attach",
+            new EnvironmentKnobSource("VSTSAGENT_DEBUG_TASK"),
+            new BuiltInDefaultKnobSource(string.Empty));
+
         public static readonly Knob DumpJobEventLogs = new Knob(
             nameof(DumpJobEventLogs),
             "If true, dump event viewer logs",

src/Agent.Worker/Handlers/NodeHandler.cs

@@ -224,6 +224,21 @@ public async Task RunAsync()
             var sigtermTimeout = TimeSpan.FromMilliseconds(AgentKnobs.ProccessSigtermTimeout.GetValue(ExecutionContext).AsInt());
             var useGracefulShutdown = AgentKnobs.UseGracefulProcessShutdown.GetValue(ExecutionContext).AsBoolean();
 
+            var configStore = HostContext.GetService<IConfigurationStore>();
+            var agentSettings = configStore.GetSettings();
+            if (agentSettings.DebugMode)
+            {
+                var debugTask = AgentKnobs.DebugTask.GetValue(ExecutionContext).AsString();
+                if (!string.IsNullOrEmpty(debugTask))
+                {
+                    if (string.Equals(Task?.Id.ToString("D"), debugTask, StringComparison.OrdinalIgnoreCase) || string.Equals(Task?.Name, debugTask, StringComparison.OrdinalIgnoreCase))
+                    {
+                        arguments = $"--inspect-brk {arguments}";
+                    }
+                }
+            }
+            
+
             try
             {
                 // Execute the process. Exit code 0 should always be returned.

src/Microsoft.VisualStudio.Services.Agent/ConfigurationStore.cs

@@ -132,6 +132,9 @@ public string Fingerprint
 
         [DataMember(EmitDefaultValue = false)]
         public int MaxDedupParallelism { get; set; }
+        
+        [DataMember(EmitDefaultValue = false)]
+        public bool DebugMode { get; set; }
     }
 
     [DataContract]

src/Microsoft.VisualStudio.Services.Agent/Constants.cs

@@ -225,6 +225,7 @@ public static class Flags
                     public const string NoRestart = "norestart";
                     public const string LaunchBrowser = "launchbrowser";
                     public const string Once = "once";
+                    public const string DebugMode = "debug";
                     public const string RunAsAutoLogon = "runasautologon";
                     public const string RunAsService = "runasservice";
                     public const string PreventServiceStart = "preventservicestart";