Merge pull request #12811 from Mikejo5000/mikejo-br24

Add user marks to profiling timeline

Author: v-dirichards

docs/profiling/add-timeline-graph-user-marks.md

@@ -0,0 +1,129 @@
+---
+title: Add user marks to the profiling timeline
+description: Learn how to include your own user marks in the profiling timeline to track custom events
+ms.date: 07/18/2024
+ms.topic: how-to
+author: mikejo5000
+ms.author: mikejo
+manager: mijacobs
+ms.subservice: debug-diagnostics
+monikerRange: '>= vs-2022'
+---
+
+# Add user marks to the profiling timeline (C#, C++)
+
+User Marks enable you to track custom events against Visual Studio's profiling tools by adding user mark functions into your code. The user marks appear as visual marks on the timeline graphs. You can do this to track a single event, or track a range. For example, you could track a "stop" and "start" event range.
+
+:::image type="content" source="../profiling/media/vs-2022/profiling-user-marks.png" alt-text="Screenshot showing profiling user marks.":::
+
+> [!NOTE]
+> This feature requires Visual Studio 2022 version 17.11 Preview 3. The feature is available in the Performance Profiler and not while debugging in the Diagnostics Hub.
+
+## Installation and setup
+
+You can install support for the feature using either the NuGet package or by adding the correct source files.
+
+- Install using the NuGet Package (C#)
+
+  Download the package, [Microsoft.VisualStudio.DiagnosticsHub.UserMarks](https://www.nuget.org/packages/Microsoft.VisualStudio.DiagnosticsHub.UserMarks).
+
+- Install by adding source files (C#, C++)
+
+  After installing Visual Studio, open the following folder: *[VS installation path]\Common7\IDE\CommonExtensions\Platform\DiagnosticsHub*.
+
+  For C# code, add *UserMarks.cs* and *UserMarksRange.cs* to your project.
+
+  For native C++ code, add *UserMarks.h* to your project.
+
+## Add user marks (C#)
+
+Add the following preprocessor definition to the project build configuration: `DIAGHUB_ENABLE_TRACE_SYSTEM`.
+
+To add the definition in Visual Studio:
+
+1. Right-click the project in Solution Explorer and then select **Properties**.
+
+1. Select **Build > General > Conditional compilation symbols**. 
+
+1. In the custom symbol fields for Debug and Release builds, add `DIAGHUB_ENABLE_TRACE_SYSTEM` as the preprocessor definition.
+
+Add the user marks object and emit. The following code shows an example of adding user marks.
+
+```csharp
+using Microsoft.DiagnosticsHub;
+
+// Create a user mark
+var myUserMark = new UserMarks("MyMark");
+
+// Emit the usermark
+myUserMark.Emit("Event happened!");
+
+// Emit statically
+UserMarks.EmitMessage("Emitting just a message");
+
+// Emitting a range
+using (var myRange = new UserMarkRange("MyMethodRange"))
+{
+   // Your code here
+}
+```
+
+## Add user marks (C++)
+
+To use the native user marks API, add *UserMarks.h* to the project and add the following code in your app:
+
+```cpp
+#define DIAGHUB_ENABLE_TRACE_SYSTEM
+#include "UserMarks.h"
+DIAGHUB_DECLARE_TRACE;
+
+// Start the trace system
+DIAGHUB_START_TRACE_SYSTEM();
+
+// Initialize user marks
+USERMARKS_INITIALIZE(L"User mark name");
+
+// Initialize user mark range
+USERMARKRANGE_INITIALIZE(L"Range name");
+
+// Emit events
+USERMARKS_EMIT(L"Message to emit with user mark");
+USERMARKRANGE_START(L"Message to emit with range");
+USERMARKRANGE_END();
+
+// Stop the trace system
+DIAGHUB_STOP_TRACE_SYSTEM();
+```
+
+## View user marks
+
+1. With your project open in Visual Studio, open the Performance Profiler (**Alt + F2**), then select a tool and select the **Start** button.
+
+1. Make sure that the user mark code you added to your app runs.
+
+   The user marks show on the ruler above the timeline graph and in a table with details about the timestamps, related process, and any messages you emitted.
+
+   In the timeline, the user mark appears as an inverted triangle.
+
+1. In the **Summary** pane, select **Show user marks** to see details about the user marks.
+
+   :::image type="content" source="../profiling/media/vs-2022/profiling-user-marks-timeline-initial-view.png" alt-text="Screenshot showing timeline.":::
+
+   Details appear in the User Marks tab.
+
+   :::image type="content" source="../profiling/media/vs-2022/profiling-user-marks-view-user-marks.png" alt-text="Screenshot showing user marks.":::
+
+1. To see the user mark details in the timeline, hover over the marks in the ruler.
+
+   :::image type="content" source="../profiling/media/vs-2022/profiling-user-marks-hover-2.png" alt-text="Screenshot showing hovering over a user mark.":::
+
+1. To filter the details view, select a time range in the timeline graph, or right-click a row and select start and end times to filter the timeline graph.
+
+   You can also filter the view by setting intervals on ranges or by selecting multiple user marks.
+
+   :::image type="content" source="../profiling/media/vs-2022/profiling-user-marks-set-interval.png" alt-text="Screenshot showing setting a user mark interval.":::
+
+## Related content
+
+- [Analyze performance by using CPU profiling](../profiling/cpu-usage.md)
+- [Analyze memory usage](../profiling/memory-usage-without-debugging2.md)

docs/profiling/media/vs-2022/profiling-user-marks-hover-2.png

@@ -18,7 +18,7 @@ ms.subservice: debug-diagnostics
 
 Application performance measuring tools are essential for developers who want to optimize their code and improve application performance. Visual Studio offers a range of profiling and diagnostics tools that can help you diagnose memory and CPU usage and other application-level issues. With these tools, you can accumulate performance data while you run your application. A profiler can help you make informed decisions quickly by providing a visual depiction of execution times and CPU usage for your application. In this article, we give a quick look at the most common profiling tools.
 
-For help choosing the correct tool, or to see profiling tool support for different app types, see [Which tool should I use?](../profiling/choose-performance-tool.md) For a tutorial that shows a general approach to optimizing code using the profiling tools, see [Beginner's guide to optimizing code](../profiling/optimize-code-using-profiling-tools.md).
+For help with choosing the correct tool, or to see profiling tool support for different app types, see [Which tool should I use?](../profiling/choose-performance-tool.md) For a tutorial that shows a general approach to optimizing code using the profiling tools, see [Beginner's guide to optimizing code](../profiling/optimize-code-using-profiling-tools.md).
 
 ## <a name="post_mortem"></a> Measure performance in release builds
 
@@ -230,14 +230,6 @@ The tool shows each async operation in a list view. You can see information such
 ![.NET Async Tool Stopped](../profiling/media/async-tool-opened.png ".NET Async Tool Stopped")
 ::: moniker-end
 
-## Examine application events
-
-The generic [events viewer](../profiling/events-viewer.md) allows you to view the activity of your application through a list of events, such as module load, thread start, and system configurations, to help better diagnose how your application is performing right within the Visual Studio profiler. This tool is available in the Performance Profiler. Open the Performance Profiler by choosing **Debug** > **Performance Profiler** (or **Alt + F2**).
-
-The tool shows each event in a list view. Columns provide information about each event, such as the event name, timestamp, and process ID.
-
-![Event Viewer Trace](../profiling/media/prof-tour-events-viewer.png "Event Viewer Trace")
-
 ## Analyze database performance (.NET Core)
 
 For .NET Core apps that use ADO.NET or Entity Framework Core, the [Database tool](../profiling/analyze-database.md) allows you to record the database queries that your application makes during a diagnostic session. You can then analyze information about individual queries in order to find places where your app's performance can be improved. This tool is available in the Performance Profiler. Open the Performance Profiler by choosing **Debug** > **Performance Profiler** (or **Alt + F2**).
@@ -254,6 +246,20 @@ The tool shows live values for each counter in a list view.
 
 :::image type="content" source="../profiling/media/dotnet-counters-tool-collecting.png" alt-text=".NET Counter tool collecting.":::
 
+## Examine application events
+
+The generic [events viewer](../profiling/events-viewer.md) allows you to view the activity of your application through a list of events, such as module load, thread start, and system configurations, to help better diagnose how your application is performing right within the Visual Studio profiler. This tool is available in the Performance Profiler. Open the Performance Profiler by choosing **Debug** > **Performance Profiler** (or **Alt + F2**).
+
+The tool shows each event in a list view. Columns provide information about each event, such as the event name, timestamp, and process ID.
+
+![Event Viewer Trace](../profiling/media/prof-tour-events-viewer.png "Event Viewer Trace")
+
+::: moniker range=">=vs-2022"
+## View custom events in the timeline graphs
+
+You can programatically create custom events that appear as icons in the timeline graphs such as the CPU utilization and memory usage timeline graphs. For more information, see [Add user marks to timeline](../profiling/add-timeline-graph-user-marks.md).
+::: moniker-end
+
 ## Analyze resource consumption (XAML)
 
 In XAML apps, such as Windows desktop WPF apps and UWP apps, you can analyze resource consumption using the Application Timeline tool. For example, you can analyze the time spent by your application preparing UI frames (layout and render), servicing network and disk requests, and in scenarios like application startup, page load, and Window resize. To use the tool, choose **Application Timeline** in the Performance Profiler, and then choose **Start**. In your app, go through the scenario with a suspected resource consumption issue, and then choose **Stop collection** to generate the report.

docs/profiling/media/vs-2022/profiling-user-marks-hover.png

@@ -110,6 +110,8 @@
     href: events-viewer.md
   - name: Analyze Resource Consumption
     href: application-timeline.md
+  - name: Add user marks to timeline
+    href: add-timeline-graph-user-marks.md
   - name: BenchmarkDotNet
     href: profiling-with-benchmark-dotnet.md
   - name: Analyze GPU usage