Merged main into live

Author: mijacobs

docs/profiling/cpu-usage.md

@@ -160,6 +160,8 @@ You can click the **Expand Hot Path** and **Show Hot Path** buttons to see the f
 |![Step 3](../profiling/media/procguid_3.png "ProcGuid_3")|The children of the second-level node are the user-code methods and asynchronous routines that are called or created by the second-level system and framework code.|
 |![Step 4](../profiling/media/procguid_4.png "ProcGuid_4")|Child nodes of a method have data only for the calls of the parent method. When **Show External Code** is disabled, app methods can also contain an **[External Code]** node.|
 
+For help understanding unexpected data in the call tree, see [Understanding the call tree](../profiling/understand-call-tree-data.md).
+
 #### <a name="BKMK_External_Code"></a> External code
 
 ::: moniker range=">=vs-2022"

docs/profiling/instrumentation.md

@@ -111,6 +111,8 @@ Here's more information on the column values:
 
 - **Module** The name of the module containing the function.
 
+For help understanding unexpected data in the call tree, see [Understanding the call tree](../profiling/understand-call-tree-data.md).
+
 ### Async calls in the Instrumentation call tree (.NET)
 
 Starting in Visual Studio 2022 version 17.13 Preview 2, views representing a visual call tree nest .NET asynchronous calls under the functions where the asynchronous call was made, making it easier to trace the execution flow within a single, unified stack trace. This can help you quickly identify performance bottlenecks.

docs/profiling/media/vs-2022/call-tree-dynamic-code-expression-tree-example.png

@@ -36,6 +36,8 @@
       href: cpu-usage.md
     - name: Flame Graph 
       href: flame-graph.md
+    - name: Understanding the call tree
+      href: understand-call-tree-data.md
     - name: CPU Insights
       items:
       - name: CPU Insights  

docs/profiling/media/vs-2022/call-tree-dynamic-code-expression-tree-visual.png

@@ -0,0 +1,57 @@
+---
+title: Understanding the call tree
+description: Learn how to interpret call tree data in the CPU Usage and Instrumentation.
+ms.date: 02/19/2025
+ms.topic: how-to
+author: mikejo5000
+ms.author: mikejo
+manager: mijacobs
+ms.subservice: debug-diagnostics
+---
+
+# Understanding the call tree
+
+The profiling tools for CPU Usage and Instrumentation in Visual Studio include a call tree view that provides a visualization of the call paths in your application, along with performance data.
+
+Sometimes, the call paths that appear in the **Call Tree** view may look different than you expect. To interpret the data you see in the call tree, it helps to understand the common reasons for these differences when they occur.
+
+Here are the most common reasons:
+
+- Release build optimizations. Release builds perform many optimizations such as inline function calls. Inline functions don't appear in the call tree. In some cases, release build optimizations may also generate unexpected code that appears in the call tree.
+
+- Asynchronous functions. Asynchronous functions execute on their own thread independent of the call path, and they normally appear in a separate node.
+
+  ::: moniker range=">=vs-2022"
+  For Instrumentation, you can [configure options to view .NET async calls](../profiling/instrumentation.md#async-calls-in-the-instrumentation-call-tree-net) in a more intuitive way, within the call path where the async call was made.
+  ::: moniker-end
+
+- Sampling of fast functions. For sampling (CPU Usage only), functions that execute very quickly may not get sampled, in which case these functions don't appear in the call tree.
+
+- Compiler generated code. Some operations generate code that isn’t intuitive. For example, async/await patterns generate state machines. Other examples include getters/setters, pattern matching, event handlers, query syntax for LINQ, source generators (for example, creation of source generators for json serialization), and other code features.  In these scenarios, some generated code may appear in the call tree.
+
+- Dynamically generated code. Unlike compiler-generated code, dynamically generated code is compiled on the fly. This isn't as common as compiler-generated code. The following code uses an expression tree and results in dynamically generated code.
+
+  ![Screenshot that shows expression tree code.](media/vs-2022/call-tree-dynamic-code-expression-tree-example.png)
+
+  The **Call Tree** view shows that this work is happening in a generated method with a generated name, which might be unexpected.
+
+  :::image type="content" source="./media/vs-2022/call-tree-dynamic-code-expression-tree-visual.png" alt-text="Screenshot that shows expression tree in the Call Tree view." lightbox="media/vs-2022/call-tree-dynamic-code-expression-tree-visual.png":::
+
+- Code that defers execution. For code that defers execution, such as LINQ, the call path can appear in unexpected ways if you're unfamiliar with how LINQ works. For example, if you use the following code:
+
+  ```csharp
+  // LINQ query to get all items less than 1,000,000
+  var query = list.Where(number => number < 1_000_000);
+  var count = query.Count();
+  ```
+  
+  You may expect the call tree to show too much time spent in the `Where` statement, but the enumeration actually happens in `Count`, so `Count` may show up as a slower function in the call tree. The following example is the opposite:
+
+  ```csharp
+  // LINQ query to get all items less than 1,000,000
+  var query = list.Where(number => number < 1_000_000).ToList();
+  var count = query.Count();
+  ```
+
+  In this example, `ToList` forces the enumeration before `Count`, so the `Count` call is optimized and runs very fast. Instead, the `Where` statement takes the most time.
+