PresentMon

PresentMon is a tool to capture and analyze ETW events related to swap chain presentation on Windows. It can be used to trace key performance metrics for graphics applications (e.g., CPU and Display frame durations and latencies) and works across different graphics APIs, different hardware configurations, and for both desktop and UWP applications.

While PresentMon itself is focused on lightweight collection and analysis, there are several other programs that build on its functionality and/or helps visualize the resulting data. For example, see

• CapFrameX
• FrameView
• OCAT
• PIX (used as part of its system monitor UI)
• presentmon-graph

License

Copyright 2017-2020 Intel Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Releases

Binaries for main release versions of PresentMon are provided on GitHub:

• Latest release
• List of all releases

See CONTRIBUTING for information on how to request features, report issues, or contribute code changes.

Command line options

Capture target options:
  -captureall              Record all processes (default).
  -process_name name       Record only processes with the provided exe name.
                           This argument can be repeated to capture multiple
                           processes.
  -exclude name            Don't record processes with the provided exe name.
                           This argument can be repeated to exclude multiple
                           processes.
  -process_id id           Record only the process specified by ID.
  -etl_file path           Consume events from an ETW log file instead of
                           running processes.

Output options (see README for file naming defaults):
  -output_file path        Write CSV output to the provided path.
  -output_stdout           Write CSV output to STDOUT.
  -multi_csv               Create a separate CSV file for each captured process.
  -no_csv                  Do not create any output file.
  -no_top                  Don't display active swap chains in the console
                           window.
  -qpc_time                Output present time as a performance counter value.

Recording options:
  -hotkey key              Use provided key to start and stop recording, writing
                           to a unique CSV file each time. 'key' is of the form
                           MODIFIER+KEY, e.g., alt+shift+f11. (See README for
                           subsequent file naming).
  -delay seconds           Wait for provided time before starting to record. If
                           using -hotkey, the delay occurs each time recording
                           is started.
  -timed seconds           Stop recording after the provided amount of time.
  -exclude_dropped         Exclude dropped presents from the csv output.
  -scroll_indicator        Enable scroll lock while recording.
  -simple                  Disable GPU/display tracking.
  -verbose                 Adds additional data to output not relevant to normal
                           usage.

Execution options:
  -session_name name       Use the provided name to start a new realtime ETW
                           session, instead of the default "PresentMon". This
                           can be used to start multiple realtime capture
                           process at the same time (using distinct names). A
                           realtime PresentMon capture cannot start if there are
                           any existing sessions with the same name.  name is
                           not sensitive to case.
  -stop_existing_session   If a trace session with the same name is already
                           running, stop the existing session (to allow this one
                           to proceed).
  -dont_restart_as_admin   Don't try to elevate privilege.  Elevated privilege
                           isn't required to trace a process you started, but
                           PresentMon requires elevated privilege in order to
                           query processes started on another account. Without
                           it, these processes cannot be targeted by name and
                           will be listed as '<error>'.
  -terminate_on_proc_exit  Terminate PresentMon when all the target processes
                           have exited.
  -terminate_after_timed   When using -timed, terminate PresentMon after the
                           timed capture completes.

Beta options:
  -qpc_time_s              Output present time as a performance counter value
                           converted to seconds.
  -terminate_existing      Terminate any existing PresentMon realtime trace
                           sessions, then exit. Use with -session_name to target
                           particular sessions.
  -include_mixed_reality   Capture Windows Mixed Reality data to a CSV file with
                           "_WMR" suffix.

Comma-separated value (CSV) file output

CSV file names

By default, PresentMon creates a CSV file named PresentMon-TIME.csv, where TIME is the creation time in ISO 8601 format. To specify your own output location, use the -output_file PATH command line argument.

If -multi_csv is used, then one CSV is created for each process captured and -PROCESSNAME appended to the file name.

If -hotkey is used, then one CSV is created for each time recording is started and -INDEX appended to the file name.

CSV columns

The following values are used in the PresentMode column:

For more information on the performance implications of these, see:

• https://www.youtube.com/watch?v=E3wTajGZOsA
• https://software.intel.com/content/www/us/en/develop/articles/sample-application-for-direct3d-12-flip-model-swap-chains.html

Windows Mixed Reality

Note: Windows Mixed Reality support is in beta, with limited OS support and maintenance.

If -include_mixed_reality is used, a second CSV file will be generated with _WMR appended to the filename with the following columns:

Known issues

See GitHub Issues for a current list of reported issues.

Analyzing OpenGL and Vulkan applications

Applications that do not use D3D9 or DXGI APIs for presenting frames (e.g., as is typical with OpenGL or Vulkan applications) will report the following:

• Runtime = Other.
• SwapChainAddress = 0
• SyncInterval = -1
• PresentFlags = 0
• MsInPresentAPI = 0

In this case, TimeInSeconds will represent the first time the present is observed in the kernel, as opposed to the runtime, and therefore will be sometime after the application presented the frame (typically ~0.5ms). Since MsUntilRenderComplete and MsUntilDisplayed are deltas from TimeInSeconds, they will be correspondingly smaller then they would have been if measured from application present. MsBetweenDisplayChange will still be correct, and MsBetweenPresents should be correct on average.

Measuring application latency

PresentMon doesn't directly measure the latency from a user's input to the display of that frame because it doesn't have insight into when the application collects and applies user input. A potential approximation is to assume that the application collects user input immediately after presenting the previous frame. To compute this, search for the previous row that uses the same swap chain and then:

LatencyMs =~ MsBetweenPresents + MsUntilDisplayed - previous(MsInPresentAPI)

Shutting down PresentMon on Windows 7

Some users have observed system stability issues when forcibly shutting down PresentMon on Windows 7. If you are having similar issues, they can be avoided by using Ctrl+C in the PresentMon window to shut it down.