Add real-time tracing documentation

Fixes #795

Signed-off-by: Dave Thaler <dthaler@microsoft.com>

docs/GettingStarted.md

@@ -207,9 +207,47 @@ This application tests various XDP functionalities. It has the following tests:
    3. From a remote host, run xdp_tests.exe and in `--remote-ip` parameter pass an IPv4 or IPv6 address of an Ethernet-like interface on the system under test in string format.
    4. Unload the program from system under test by running `delete program <id>` on the netsh prompt, where <id> is the ID noted above.
 
+### Using tracing
+eBPF for Windows uses ETW for tracing.  A trace can be captured in a file, or viewed in real-time.
+
 ### Capturing traces
-eBPF for Windows uses ETW for tracing. To capture a trace use the following commands:
+To capture a trace use the following commands:
 1) Start tracing: ```wpr.exe -start ebpfforwindows.wprp -filemode```
 2) Run the scenario to be traced.
 3) Stop tracing: ```wpr.exe -stop ebpfforwindows.etl```
 4) Convert the traces to a human readable version: ```netsh trace convert ebpfforwindows.etl ebpfforwindows.csv csv```
+
+### Viewing traces in real-time
+To view traces in real-time, the `tracelog.exe` and `tracefmt.exe` commands from the WDK can be used.
+If you are running eBPF for Windows in a VM, you can either install the full WDK in the VM (see the Prequisites
+section above) or just copy the two executables into the VM.
+
+To view all eBPF trace events that would be captured to a file, use the following commands:
+1) Create a trace session with some name such as MyTrace: ```tracelog -start MyTrace -guid ebpf-all.guid -rt```
+2) View the session in real-time on stdout: ```tracefmt -rt MyTrace -displayonly -jsonMeta 0```.  This will
+   continue until you break out of the executable with Ctrl-C.
+3) Close the trace session: ```tracelog -stop MyTrace```
+
+Often when tracing eBPF programs, it is useful to only view output generated by the [bpf_printk](https://microsoft.github.io/ebpf-for-windows/bpf__helper__defs_8h.html#aae337e68db96b4b9470f8c519386cbec) helper.
+To do so, use `ebpf-printk.guid` instead of `ebpf-all.guid` when creating a trace session.  That is:
+1) Create a trace session with some name such as MyTrace: ```tracelog -start MyTrace -guid ebpf-printk.guid -rt```
+2) View the session in real-time on stdout: ```tracefmt -rt MyTrace -displayonly -jsonMeta 0```.  This will
+   continue until you break out of the executable with Ctrl-C.
+3) Close the trace session: ```tracelog -stop MyTrace```
+
+This will display lines like the following for `bpf_printk("Hello, world");`:
+```
+[3]1760.1910::03/10/2022-13:56:14.226 [EbpfForWindowsProvider]{"Message":"Hello, world"}
+```
+where `[3]` is the CPU ID, `1760` is the Process ID in hex, and `1910` is the Thread ID in hex.
+
+If you want the prefix to look closer to Linux output, set the following [environment variable](https://docs.microsoft.com/en-us/windows-hardware/drivers/devtest/trace-message-prefix):
+```
+set TRACE_FORMAT_PREFIX=%8!u! [%9!03d!] %4!s!:
+```
+
+This will result in lines like:
+```
+5984 [003] 03/10/2022-13:56:14.226:{"Message":"Hello, world"}
+```
+where `5984` is the Process ID in decimal, and `003` is the CPU ID.

include/bpf_helper_defs.h

@@ -221,7 +221,9 @@ EBPF_HELPER(long, bpf_trace_printk5, (const char* fmt, uint32_t fmt_size, uint64
     })
 #else
 /**
- * @brief Print debug output.
+ * @brief Print debug output.  For instructions on viewing the output, see the
+ * <a href="https://github.com/microsoft/ebpf-for-windows/blob/main/docs/GettingStarted.md#using-tracing">Using
+ * tracing</a> section of Getting Started Guide for eBPF for Windows.
  *
  * @param[in] fmt Printf-style format string.
  * @param[in] ... Numeric arguments to be used by the format string.

scripts/deploy-ebpf.ps1

@@ -5,7 +5,7 @@
 ## Initialize parameters
 ##
 $build_directory=".\x64\Debug"
-[System.Collections.ArrayList]$built_files=@( "EbpfCore.sys", "EbpfApi.dll", "ebpfnetsh.dll", "ebpfsvc.exe", "NetEbpfExt.sys", "sample_ebpf_ext.sys", "sample_ext_app.exe", "ucrtbased.dll", "MSVCP140D.dll", "VCRUNTIME140D.dll", "VCRUNTIME140_1D.dll", "bpftool.exe", "bindmonitor.o", "bpf.o", "bpf_call.o", "divide_by_zero.o", "droppacket.o", "droppacket_unsafe.o", "map_in_map.o", "reflect_packet.o", "tail_call.o", "tail_call_bad.o", "tail_call_map.o", "test_sample_ebpf.o", "test_utility_helpers.o", "printk.o", "ebpfforwindows.wprp")
+[System.Collections.ArrayList]$built_files=@( "EbpfCore.sys", "EbpfApi.dll", "ebpfnetsh.dll", "ebpfsvc.exe", "NetEbpfExt.sys", "sample_ebpf_ext.sys", "sample_ext_app.exe", "ucrtbased.dll", "MSVCP140D.dll", "VCRUNTIME140D.dll", "VCRUNTIME140_1D.dll", "bpftool.exe", "bindmonitor.o", "bpf.o", "bpf_call.o", "divide_by_zero.o", "droppacket.o", "droppacket_unsafe.o", "map_in_map.o", "reflect_packet.o", "tail_call.o", "tail_call_bad.o", "tail_call_map.o", "test_sample_ebpf.o", "test_utility_helpers.o", "printk.o", "ebpfforwindows.wprp", "ebpf-all.guid", "ebpf-printk.guid")
 $destination_directory="C:\Temp"
 $error.clear()
 $vm="Windows 10 dev environment"

scripts/ebpf-all.guid

@@ -0,0 +1,5 @@
+; Copyright (c) Microsoft Corporation
+; SPDX-License-Identifier: MIT
+;
+; Include all eBPF for Windows events
+394f321c-5cf4-404c-aa34-4df1428a7f9c

scripts/ebpf-printk.guid

@@ -0,0 +1,5 @@
+; Copyright (c) Microsoft Corporation
+; SPDX-License-Identifier: MIT
+;
+; Filter to only events generated by bpf_printk()
+394f321c-5cf4-404c-aa34-4df1428a7f9c;0x200;4

scripts/setup_build/setup_build.vcxproj

@@ -90,6 +90,14 @@
       <DeploymentContent Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</DeploymentContent>
       <DeploymentContent Condition="'$(Configuration)|$(Platform)'=='Release|x64'">true</DeploymentContent>
     </CopyFileToFolders>
+    <CopyFileToFolders Include="..\ebpf-all.guid">
+      <DeploymentContent Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</DeploymentContent>
+      <DeploymentContent Condition="'$(Configuration)|$(Platform)'=='Release|x64'">true</DeploymentContent>
+    </CopyFileToFolders>
+    <CopyFileToFolders Include="..\ebpf-printk.guid">
+      <DeploymentContent Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</DeploymentContent>
+      <DeploymentContent Condition="'$(Configuration)|$(Platform)'=='Release|x64'">true</DeploymentContent>
+    </CopyFileToFolders>
   </ItemGroup>
   <PropertyGroup Label="Globals">
     <VCProjectVersion>16.0</VCProjectVersion>
@@ -225,4 +233,4 @@ copy "$(VC_CppRuntimeFilesPath_x64)\Microsoft.VC142.CRT" "$(OutDir)"</Command>
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">
   </ImportGroup>
-</Project>
+</Project>

scripts/setup_build/setup_build.vcxproj.filters

@@ -56,10 +56,12 @@
       <Filter>Source Files</Filter>
     </CopyFileToFolders>
     <CopyFileToFolders Include="..\ebpfforwindows.wprp" />
+    <CopyFileToFolders Include="..\ebpf-all.guid" />
+    <CopyFileToFolders Include="..\ebpf-printk.guid" />
   </ItemGroup>
   <ItemGroup>
     <None Include="..\pre-commit">
       <Filter>Source Files</Filter>
     </None>
   </ItemGroup>
-</Project>
+</Project>