CSV Profiler

A lightweight, scoped, timestamp-based profiler that outputs per-frame timings with separate timelines for the renderthread and gamethread.

Windows
MacOS
Linux

This page is published in a draft state in order to make the information available as early as possible. Check back for updates.

The CSV profiler lightweight, scoped, timestamp-based profiler that outputs per-frame timings with separate timelines for the renderthread and gamethread which works on all consoles and also PC and in all builds except shipping.

Capturing Stats to a CSV

On the commandline

Run the executable for your project with the -csvCaptureFrames=N argument to capture N frames from startup:

UE4.exe [Project] -csvCaptureFrames=N

On the console

You can use the csvprofile [start/stop] console command to start or stop capture during runtime. csvprofile frames=N can capture a fixed number of frames

Output

CSV files generated by the CSV Profiler are written out to the [ProjectDirectory]/Saved/Profiling/CSV directory.

Stat Categories

You can define a stat category with CSV_DEFINE_CATEGORY(CategoryName, bEnableByDefault). You can use an existing category externally with CSV_DECLARE_CATEGORY_EXTERN(CategoryName). There are _MODULE variants of this for cross-module usage.

Categories via the commandline, with -csvcategories, e.g. -csvcategories="First,Second".

Ideally only key stats should be enabled by default. Plan carefully before making new categories enabled by default, and avoid adding stats to existing categories which are enabled by default unless they're really needed.

Adding Stats

Unit stats and free memory have built-in instrumentation, but you can add your own additonal stats to capture using the CSV_ macros. The CSV_ macros are defined at the top of CsvProfiler.h. You can add the following types of stats:

  • Scoped timing stats - CSV_SCOPED_TIMING_STAT(Category, StatName)

  • Custom (value) stats - CSV_CUSTOM_STAT(Category, StatName,Value, Op) or its variants

    Op is a stat operation enum (ECsvCustomStatOp), which can be one of: Set, Min, Max, Accumulate

See CSVTest() in CSVProfiler.cpp for examples.

Stats can be added inline and do not need to be defined up front. However, you can define them up front if needed. See the CSV_DEFINE_STAT(Category,StatName) and CSV_CUSTOM_STAT_DEFINED macros.

Stats get accumulated on a per-frame basis and written out to a CSV, where each row is a frame, and each column is a stat. They appear as headings in the CSV with CategoryName/StatName, or CategoryName/ThreadName/StatName for timer stats. This convention makes them easy for graphing via the CsvToSvg tool using wilcards. For example:

-stats MyCategory/*

Events

Events can be added with the CSV_EVENT macro which uses the same parameters as printf. Events appear in a special events column in the CSV, separated with semicolons if there are multiple events in a frame. The CSVToSVG graphing tool can be used to annotate graphs with events using the -showevents parameter. See CSVToSVG Tool for more information.

You should try to use events sparingly to capture infrequent occurances. Overuse of events can result in high performance and memory overhead.

GPU Stats

The CSV profiler supports GPU Stats, including in Test builds where STATS is disabled. Recording GPU stats carries some overhead, so it's disabled by default.

To enable recording GPU stats, do one of the following:

  • Set r.GPUCsvStatsEnabled to 1 in the console.

  • Pass -csvGpuStats on the command line.

Performance and Memory considerations

Instrumentation overhead is designed to be as low as possible, enabling you to instrument functions which are called hundreds of times per frame with minimal distortion of the timing data. There is minimal processing of stat data, such as accumulation of timings in thread-local blocks, and these are only processed at the end of the capture.

Raw stat data is processed every 60ms (by default) to reduce memory overhead. The resulting overhead during profiling is 4 bytes per stat per frame and accumulates until the capture ends since nothing is written to disk until that point. This means that memory may become a concern for very long captures with large numbers of stats. Memory usage is summarised to the log at the end of a capture.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback