Runtime Flow
Quick Start
Introduction
Inherited a very complex .NET codebase and want to understand the flow in detail? The code contains a lot of delegates making debugging a nightmare? Runtime Flow can help you get started pinpointing specific code areas that are responsible for the selected use case.Have .NET controls with numerous events? Want to know which of these events are being fired and when? Runtime Flow shows you the sequence of all method calls.
Using a 3rd party .NET library? Having a problem making it work correctly? Runtime Flow can show what happens inside the library without the source code.Tired to verify lines of code being executed by setting break points and adding trace statements? Runtime Flow can show you all function calls without additional instrumentation.
A program crashes and suddenly exits without any errors? Runtime Flow can show the last function calls before the crash.Want to log with what parameters a function was called? Runtime Flow shows and logs simple function parameters and return values without additional instrumentation.
Running monitoring
Runtime Flow installer requires admin rights and installs for all users. Open a solution in Visual Studio and click Run on the Runtime Flow toolbar. Runtime Flow launches the StartUp Project using the Debug settings for the current configuration and begins monitoring function calls:
Visual Studio 2013/2015 use IIS Express to run Web Apllications. You can set the Customized Run command to something like
C:\Program Files (x86)\IIS Express\iisexpress.exe
and Command arguments like
/config:"C:\Users\[USER_NAME]\Documents\IISExpress\config\applicationhost.config" /site:"WebApplication1" /apppool:"Clr4IntegratedAppPool"
In the Options - Monitoring filter you can limit monitoring to your site dlls like
Module == WebApplication1.dll
Make sure that the iisexpress.exe process in not running before starting the monitoring.
After you have started the monitoring, open your site in a web browser and Runtime Flow should show executed statements:
To monitor an ASP.NET Core web application running in IIS see Monitoring a .NET Core web application in IIS 10.
To monitor an ASP.NET application running in IIS see Monitoring a web application in IIS 10.
To monitor a Blazor Server application see Monitoring a Blazor Server application.
To monitor a Windows service see Monitoring a Windows service.
To monitor a .NET Core application, use C:\Program Files\dotnet\dotnet.exe as a runner for your application dll:
Running portable edition
The portable edition can work without Visual Studio and almost without installation. You only need to register a profiler COM class before running RuntimeFlowPortable.exe. If you don't have admin rights and you only need to monitor applications under the current account, run Register profiler for the current user.cmd. If you have admin rights, it is recommended to run Register profiler for the local machine.cmd. When no longer needed, you can unregister the profiler with the appropriate
Unregister
script.
The portable edition includes the RFShortcuts extension that registers two global Windows shortcuts Win+F11 and Win+F12 to resume and pause monitoring. It allows you quickly pause and resume monitoring without switching from the monitored application.
Exploring control flow
Function calls are displayed in the tree with threads as roots (including thread names if present, assigned for example using the System.Threading.Thread.CurrentThread.Name property). Repeated function calls are shown as dup with repetition count. Repeated calls of a group of functions are shown as mdup. For duplicate function calls the first and the last call's parameters and return values are displayed.
Function parameters and return values of complex types are displayed as dots. Strings longer than 260 characters are trimmed to not overrun the screen. When number of elements in an array is more than 10, the first nine elements are displayed + number of skipped element + the last element. When an exception occurs the function return value is displayed as Ex with thrown object information.The Clear command on the Runtime Flow toolbar removes all functions except currently executing ones and removes finished threads.
The Expand command expands the whole tree one level further, the Expand below command expands nodes for the selected function further and the Collapse command collapses the whole tree one level up.
The search field allows you to search for classes, functions, parameters and return values.Runtime Summary
The Runtime Summary window lists all classes and functions that were used during a program run organized by modules and namespaces. All elements are alphabetically sorted. New functions are added in real time and removed by the Clear command the same way as in the Runtime Flow window.
The search field allows you to search for namespaces, classes and functions. Each new search continues from the selected node. The Locate in flow toolbar button finds the selected class or function in the Runtime Flow window. Press the Locate in flow button again to find the next occurrence.Monitoring level
Full monitoring monitors each function call. Summary only detects only the first function usage - the Runtime Flow window is empty in this mode and the Runtime Summary window shows almost the same content as in the full monitoring mode except for the Clear command usage. In the Full monitoring mode, after clearing the events, each function call adds a function to the summary window. In the Summary only mode, only functions that were never used before will be added to the summary window when called.
Summary only monitoring is very fast and well suited for an application reconnaissance with the empty monitoring filter.Timeline
You can open the Timeline window with the corresponding main toolbar button:
It additionally shows local time when a function call started with 0.1 ms accuracy and a [thread id].
When a function call is overlapped in time with a function call in another thread, you will see an entry for function start with parameters and without return value "9:30:43.9741 Program.Example()" and an entry for function end without parameters and with return value "9:30:44.0625 [10284] void Program.Example".
To enable recording of timing information, please open the Timeline window before starting monitoring.
In the Presentation options dialog you can enable timestamps in the Flow window and customize timestamp format with standard and custom date and time format strings:
Monitoring filter
Filtering out unneeded functions improves monitoring performance and simplifies monitoring log. It's possible to filter by module, class and function creating very specific boolean expressions.
All common filtering tasks can be executed by using the Include and Exclude buttons in the toolbars. The buttons in the Runtime Flow toolbar allow filtering by function and the buttons in the Runtime Sumary toolbar allow filtering by function, class, namespace and module:
The monitoring filter is applied at the beginning of a monitoring session. You can use == and != between Module, Class, Function and a filter string. If the filter string contains spaces or special characters it should be quoted: Module == "C:\Program Files\SurF.exe". The empty filter sets monitoring for all modules, classes and functions.
You can use the ! unary operator to negate expression and ||, && for OR and AND operations.
A filter string allows tail matching after delimiter. Thus Module == SurF.exe matches "C:\Program Files\SurF.exe", but not "C:\Program Files\OverSurF.exe". During matching, class name contains its namespace: Class == FileSystemWatcher matches System.IO.FileSystemWatcher due to the tail matching.
A filter string allows prefix matching by using * at the end: Module == C:\*. It also allows filtering by namespace: Class == System.IO.*.
When monitoring a C++/CLR application, "native" functions are represented as the class <Module> and "native" class included in function name. Thus to exclude classes and functions in the std namespace use Function != std.*.
true and false constants can be used to quickly enable or disable part of a filter. For example, adding || true at the end of a filter enables monitoring of all functions without deleting the whole filter expression.
Pause and resume monitoring
After you've started monitoring (with Run or Customized Run) and have executed a use case, you can press the Pause button on the Runtime Flow toolbar.
Pause stops all updates to the Runtime Flow and Runtime Summary windows and eliminates most of monitoring overhead (speeding up the monitored application and limiting memory consumption). In this mode you can browse collected events and execute tasks in your application not required monitoring.
When you are ready to run a next use case, press the Resume button. Resume clears the Runtime Flow and Runtime Summary windows and resumes normal monitoring events processing.
The most common case to not collect monitoring data is to skip application startup. With Monitor application startup unchecked, no flow data is collected until you click the Resume button. This is useful when monitoring complex apps with very big initialization routines that you are not interested in:
Saving monitoring results
You can save monitoring results (content of the Runtime Flow and Runtime Summary windows) to a .rdf file with the Save button on the toolbar. This file can be later reopened with the corresponding Open button.
Copyright 2008 - 2023 Vlasov Studio (Best in class Visual Studio extensions and tools)