Update to AutoTrace (#24936)

* * Add license headers to autotrace.h|cpp
* use W() macro for getting correct string literal type
* formalize env vars to be COMPlus_* style
* add documentation
* modify cmake files to have the flag and set default value to 0

* Fix typo

5 files changed, 55 insertions, 9 deletions

diff --git a/Documentation/workflow/AutomatedStressTestingForDiagnosticServer.md b/Documentation/workflow/AutomatedStressTestingForDiagnosticServer.md
new file mode 100644
index 0000000000..33787fb4ee
--- /dev/null
+++ b/Documentation/workflow/AutomatedStressTestingForDiagnosticServer.md
@@ -0,0 +1,23 @@
+#AutoTrace: 
+
+> see: `src/vm/autotrace.h|cpp` for the code
+
+AutoTrace is used to run automated testing of the Diagnostic Server based tracing and specifically
+EventPipe.  The feature itself is enabled via the feature flag `-DFEATURE_AUTO_TRACE`.
+
+## Mechanism:
+
+AutoTrace injects a waitable event into the startup path of the runtime and waits on that event until
+some number of Diagnostics IPC (see: Diagnostics IPC in the dotnet/diagnostics repo) connections have occurred.
+The runtime then creates some number of processes using a supplied path that typically are Diagnostics IPC based tracers.
+Once all the tracers have connected to the server, the event will be signaled and execution will continue as normal.
+
+## Use:
+
+Two environment variables dictate behavior:
+- `COMPlus_AutoTrace_N_Tracers`: The number of tracers to create.  Should be a number in `[0,64]` where `0` will bypass the wait for attach.
+- `COMPlus_AutoTrace_Command`: The path to the executable to be invoked.  Typically this will be a `run.sh|cmd` script.
+
+> (NB: you should `cd` into the directory you intend to execute `COMPlus_AutoTrace_Command` from as the first line of the script.)
+
+Once turned on, AutoTrace will run the specified command `COMPlus_AutoTrace_N_Tracers` times.
diff --git a/clrfeatures.cmake b/clrfeatures.cmake
index bb4f09f2a3..0326762971 100644
--- a/clrfeatures.cmake
+++ b/clrfeatures.cmake
@@ -23,3 +23,7 @@ endif(NOT DEFINED FEATURE_INTERPRETER)
 if(NOT DEFINED FEATURE_STANDALONE_GC)
   set(FEATURE_STANDALONE_GC 1)
 endif(NOT DEFINED FEATURE_STANDALONE_GC)
+
+if(NOT DEFINED FEATURE_AUTO_TRACE)
+  set(FEATURE_AUTO_TRACE 0)
+endif(NOT DEFINED FEATURE_AUTO_TRACE)
diff --git a/src/vm/CMakeLists.txt b/src/vm/CMakeLists.txt
index b9fd16ae05..412f91201a 100644
--- a/src/vm/CMakeLists.txt
+++ b/src/vm/CMakeLists.txt
@@ -4,8 +4,6 @@ set(CMAKE_INCLUDE_CURRENT_DIR ON)
 include_directories(BEFORE ${CMAKE_CURRENT_SOURCE_DIR})
 include_directories(${ARCH_SOURCES_DIR})
 
-# EventPipe stress testing support
-# add_definitions(-DFEATURE_AUTO_TRACE)
 add_definitions(-DUNICODE)
 add_definitions(-D_UNICODE)
 
diff --git a/src/vm/autotrace.cpp b/src/vm/autotrace.cpp
index 90529dd808..75afe90845 100644
--- a/src/vm/autotrace.cpp
+++ b/src/vm/autotrace.cpp
@@ -1,3 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+/**
+ *
+ * AutoTrace: This infrastructure is used to run automated testing of Diagnostic Server based tracing via
+ * EventPipe.  The feature itself is enabled via the feature flag FEATURE_AUTO_TRACE.
+ * 
+ * Two environment variables dictate behavior:
+ * - COMPlus_AutoTrace_N_Tracers: a number in [0,64] where 0 will disable the feature
+ * - COMPlus_AutoTrace_Command: The path to an executable to be invoked.  Typically this will be a "run.sh|cmd".
+ *  > (NB: you should `cd` into the directory you intend to execute `COMPlus_AutoTrace_Command` from as the first line of the script.)
+ * 
+ * Once turned on, AutoTrace will run the specified command `COMPlus_AutoTrace_N_Tracers` times.  There is an event that will pause execution
+ * of the runtime until all the tracers have attached.  Once all the tracers are attached, execution will continue normally.
+ * 
+ * This logic is easily modified to accommodate testing other mechanisms related to the Diagnostic Server.
+ * 
+ */
+
 #include "common.h" // Required for pre-compiled header
 
 #ifdef FEATURE_AUTO_TRACE
@@ -7,16 +28,12 @@
 
 HANDLE auto_trace_event;
 static size_t g_n_tracers = 1;
-#ifdef __apple__
-static const WCHAR* command_format = L"%hs -p %d";
-#else
-static const WCHAR* command_format = u"%hs -p %d";
-#endif // __apple__
+static const WCHAR* command_format = W("%hs -p %d");
 static WCHAR* command = nullptr;
 
 void auto_trace_init()
 {
-    char *nAutoTracersValue = getenv("N_AUTO_TRACERS");
+    char *nAutoTracersValue = getenv("COMPlus_AutoTrace_N_Tracers");
     if (nAutoTracersValue != NULL)
     {
         g_n_tracers = strtoul(nAutoTracersValue, NULL, 10);
@@ -24,7 +41,7 @@ void auto_trace_init()
 
     // Get the command to run auto-trace.  Note that the `-p <pid>` option
     // will be automatically added for you
-    char *commandTextValue = getenv("AUTO_TRACE_CMD");
+    char *commandTextValue = getenv("COMPlus_AutoTrace_Command");
     if (commandTextValue != NULL)
     {
         DWORD currentProcessId = GetCurrentProcessId();
diff --git a/src/vm/autotrace.h b/src/vm/autotrace.h
index e450b3295d..e3c5393567 100644
--- a/src/vm/autotrace.h
+++ b/src/vm/autotrace.h
@@ -1,3 +1,7 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
 #ifndef __AUTO_TRACE_H__
 #define __AUTO_TRACE_H__
 #ifdef FEATURE_AUTO_TRACE