# .NET GC capture (ETW): privileges and environment requirements
This document describes who must run elevated, why, and what operators and security teams should expect when using the yc-360 script .NET GC capture feature (ETW–based collection via the CLR provider).
.NET GC logs are collected using Event Tracing for Windows (ETW) against the CLR provider. Starting that trace session is a privileged operation on Windows: the capture utility must run with Administrator elevation; otherwise it will not enable the provider and will exit with a clear error.
Elevation applies to the diagnostic tool (and any wrapper such as yc-360 that launches it with an inherited token). The target .NET application does not need to run as Administrator unless your own policies require it.
Customers do not need to turn on a separate, global “ETW” switch in Windows, the tool creates a session-local trace when it runs. In hardened environments, Group Policy, EDR, or other controls may still limit tracing even when the process is elevated; see Enterprise and security considerations below.
# How GC capture works (short)
The tool uses ETW to subscribe to the CLR provider (Microsoft-Windows-DotNETRuntime) with keywords focused on GC, heap/type names, and related events. Events are then filtered to the target process ID and written to JSON output.
Starting a real-time ETW session that receives these events is a privileged operation on Windows. The TraceEvent–based session used here follows the same model as other performance and diagnostics tools (e.g. PerfView–style collection).
# Why Administrator (elevated) is required
On Windows, creating and controlling many user–mode ETW trace sessions requires elevated rights (commonly described as "Run as administrator"). The GC capture path explicitly verifies elevation before enabling the provider:
- If the process is not elevated, it logs a clear message and does not start the ETW session.
So elevation is not optional for this code path: it is a hard requirement enforced at runtime.
Practical implication: whoever launches yc-360 script must do so from an elevated context-typically an elevated Command Prompt, PowerShell, or a scheduled task configured to run with highest privileges.
# What customers must do
Run the GC capture command elevated
- Right–click the shell → Run as administrator, or ensure your automation (script, agent, scheduler) runs the tool with administrative privileges.
Propagate elevation to the wrapper
- If another script spawns the yc-360 script, the parent process must already be elevated so the child inherits an elevated token (or the script must explicitly relaunch elevated-depending on your design).
Keep the tool and target on the same machine
- GC collection is local to the machine where the .NET process runs.
Customers do not need to:
- Install a separate "ETW driver" for this feature.
- Turn on a global "ETW" toggle in Windows for the whole machine (the tool creates its own trace session when run).
# Enterprise and security considerations
Even with an elevated administrator token, capture can fail or be incomplete in locked–down environments:
- Endpoint protection / EDR may restrict kernel or user–mode tracing APIs or inject delays.
- Group Policy or security baselines sometimes limit performance diagnostics or logging features.
- Least–privilege environments may block interactive "Run as administrator"; in that case use an approved elevated service account or Task Scheduler task with "Run with highest privileges" for the capture job.
If GC capture works on a developer workstation but fails in production, compare UAC elevation, script host, and security product policies-not only "is ETW enabled."
# Troubleshooting
| Symptom | What to check |
|---|---|
| Message that the tool must run as Administrator | Launch the shell or automation elevated (e.g. "Run as administrator"). |
| Capture starts but no / few events | Confirm the correct PID; confirm the process is .NET and still running during the capture window; review security software logs. |
| Works locally, fails in CI / server | Verify the build agent or task runs with elevated rights where required; some agents run as a service account without admin. |
# FAQ
1. Do we need to "enable ETW" in Windows for yc-360 script?
No. There is no separate product setting to turn ETW on globally. The tool creates its own ETW session when it runs. What matters is that the process is allowed to create that session—hence Administrator elevation for this implementation.
2. Must the yc-360 script run as Administrator?
Yes. The script checks for elevation and will not start the trace session without it.
3. Must the monitored .NET application run as Administrator?
No, unless your organization requires it for other reasons. Elevation is required for the collector, not the application under test.
4. Why does ETW need admin at all?
On Windows, creating and controlling real-time ETW sessions for many providers (including the CLR diagnostic provider used here) is restricted to elevated contexts. This matches how other system-wide and provider-level tracing tools behave.
5. Can Group Policy or antivirus block this even when we are admin?
Sometimes. Elevation satisfies the OS gate for the session, but EDR, GPO, or security baselines can still interfere with tracing APIs or delay events. Treat “run as admin” as necessary but not always sufficient in locked-down estates.
6. Do we need to install anything extra for ETW on the server?
No extra "ETW package" is required for standard Windows Server / Windows 10+ for this CLR provider path. The tool uses the built-in ETW infrastructure.