We first released DTrace on Windows as a preview with the Windows 10 May 2019 Update. The feedback and reaction from our community was very gratifying. Thank you for taking the time to use DTrace on Windows and providing us with valuable feedback.
We have been quiet since the initial preview release, and today we are ready to talk about the updates we have made to DTrace on Windows. All of these changes are available in the latest Windows 10 Insider Preview (20H1) build, starting with 19041.21.
With these changes, we are now positioned to have customers broadly use DTrace on Windows.
Key resources
Removed kernel debugger requirement
This was the biggest hinderance in using DTrace on Windows internally and externally. We knew going in that we need to solve this, but we also knew that it would take time to solve this correctly. In 20H1, we have now removed the kernel debugger requirement. Windows kernel now relies on Virtualization-based Security (VBS) to securely insert dynamic trace points into kernel code. By relying on VBS, we can now safely and securely insert dynamic tracepoints in the kernel without disabling PatchGuard (enabling kernel debugger disables PatchGuard).
Note: Because we made the change to rely on VBS for DTrace on Windows, the installer from 19H1 will only work on 19H1. For Windows 10 Insider Preview (post 19H1) builds, please use the updated installer linked in this post. This installer will NOT install on previous Windows 10 releases.
Lets get into how to setup and use DTrace on Windows.
Prerequisites for using the feature:
- Windows 10 insider build 19041.21 or higher
Detailed instructions to install DTrace is available in our documentation. At a high-level, these are:
- Enable boot option to turn on DTrace
- Download and install the DTrace MSI.
- Ensure VBS is turned on
- Optional: Update the PATH environment variableto include C:\Program Files\DTrace
- set PATH=%PATH%;"C:\Program Files\DTrace"
- Setup symbol path
- Create a new directory for caching symbols locally. Example: mkdir c:\symbols
- Set _NT_SYMBOL_PATH=srv*C:\symbols*https://msdl.microsoft.com/download/symbols
- DTrace automatically downloads the symbols necessary from the symbol server and caches to the local path.
- Reboot machine
To check if VBS is enabled or not, look at system summary tab on the Microsoft System Information tool (msinfo32.exe).
ARM64 preview
Yes, that’s right! DTrace now supports ARM64 in preview mode. The ARM64 MSI is available in the download link listed above.
You can use it on your Surface Pro X running the latest Windows 10 Insider Preview (20H1) build, starting with 19041.21.
User mode Stackwalk
In the preview, the stackwalk facility in DTrace was limited to Kernel mode (stack). This update adds support for usermode stackwalk facility (ustack). Like stack, ustack facility is fully compatible with open source DTrace specification. It can be invoked in three ways by specifying frames (depth) & size (ignored for now) or void.
- Ustack(nframes, size)
- Ustack(nframes)
- Ustack()
While ustack () can determine the address of the calling frame when probe fires, the stack frames will not be translated into symbols until the ustack () action is processed at user-mode by DTrace consumer. Symbol download can slow down the output. Hence, it’s better to use this facility with locally cached symbols like below.
dtrace -n "profile-1ms /arg1/ {ustack(50, 0); exit(0);} " -y C:\symbols
dtrace: description 'profile-1ms ' matched 1 probe
CPU ID FUNCTION:NAME
0 3802 :profile-1ms
ntdll`ZwAllocateVirtualMemory+0x14
ntdll`RtlAllocateHeap+0x3ded
ntdll`RtlAllocateHeap+0x763
ucrtbase`malloc_base+0x44
Live dump support
Windows commonly uses something called Live dump to help quickly diagnose issues. Live dumps help with troubleshooting issues involving multiple processes or system wide issues without downtime. In 20H1, DTrace on Windows can be used to capture a live dump from inside a D-script using the lkd() DTrace facility. A common use case of this facility is to instrument error path (like return code indicates a failure) and capture a live dump right at the failure point for advanced diagnostics. For more information on live dump support, see DTrace Live Dump.
dtrace -wn "syscall:::return { if (arg0 != 0xc0000001UL) { lkd(0); printf(\" Triggering Live dump \n \");exit(0); }}"
dtrace: description 'syscall:::return ' matched 1411 probes
dtrace: allowing destructive actions
CPU ID FUNCTION:NAME
0 181 NtDeviceIoControlFile:return Triggering Live dump
dir c:\Windows\LiveKernelReports
Volume in drive C has no label.
Volume Serial Number is 70F4-B9F6
Directory of c:\Windows\LiveKernelReports
11/05/2019 05:20 PM <DIR> .
11/05/2019 05:20 PM <DIR> ..
11/05/2019 05:19 PM <DIR> DTRACE
11/05/2019 05:20 PM 53,395,456 DTRACE-20191105-1720.dmp
ETW Tracing
ETW tracing is the most frequently used tool for debugging on Windows. In DTrace on Windows 19H1 preview, we added support for instrumenting tracelogged and manifested events using the ETW provider.
In 20H1, we further enhanced this facility to create new ETW events on the fly from inside a D-script using the ETW_Trace() facility. This helps in situations where existing ETW events are insufficient and you would like to add additional ETW trace points without modifying production code.
For more information about ETW_Trace facility and ETW provider, see DTrace ETW.
/*
Running the GitHub ETW provider sample (link below) to print node memory info event.
https://github.com/microsoft/DTrace-on-Windows/blob/master/samples/windows/etw/numamemstats.d
*/
dtrace -qs numamemstats.d
Partition ID: 0
Count: 1
Node number: 1
m_nodeinfo {
uint64_t TotalPageCount = 0x1fb558
uint64_t SmallFreePageCount = 0x41
uint64_t SmallZeroPageCount = 0
uint64_t MediumFreePageCount = 0
uint64_t MediumZeroPageCount = 0
uint64_t LargeFreePageCount = 0
uint64_t LargeZeroPageCount = 0
uint64_t HugeFreePageCount = 0
uint64_t HugeZeroPageCount = 0
}
This concludes a tour of some of our key updates to DTrace on Windows for 20H1.
You can get started by downloading & installing the DTrace MSI package on the latest 20H1 client/server insider build - 19041.21+.
You can also visit our GitHub page for contributing code and samples. We have several advanced scripts in GitHub to help users learn and use DTrace on Windows.
How to file feedback?
As always, we rely on feedback from our users to help improve the product. If you hit any problems or bugs, please use Feedback hub to let us know:
- Launch feedback hub by clicking this link
- Select Add new feedback.
- Please provide a detailed description of the issue.
- Currently, we do not automatically collect any debug traces, so your verbatim feedback is crucial for understanding and reproducing the issue. Pass on any verbose logs.
- You can also set DTRACE_DEBUG environment variable to 1 to collect verbose DTrace logs.
- Submit
We are excited to rollout these changes and look forward to working with the community to continue improving DTrace experience.
DTrace team (Andrey Shedel, Gopikrishna Kannan, Max Renke, Hari Pulapaka)