Performance Profiling: Difference between revisions
(→Scope parameter: important note about scope case sensitivity) |
(→How to capture: added note about scope being case sensitive) |
||
| Line 203: | Line 203: | ||
==== Slow Frame ==== | ==== Slow Frame ==== | ||
{{Feature|important| | |||
The '''scope''' parameter is [https://en.wikipedia.org/wiki/Case_sensitivity case sensitive] | |||
}} | |||
If you want to capture a snapshot of a slow frame, there are a few options: | If you want to capture a snapshot of a slow frame, there are a few options: | ||
| Line 337: | Line 341: | ||
==== Slow Server Frame ==== | ==== Slow Server Frame ==== | ||
{{Feature|important| | |||
The '''scope''' parameter is [https://en.wikipedia.org/wiki/Case_sensitivity case sensitive] | |||
}} | |||
If you want to capture a snapshot of a slow frame on the server, there are a few options: | If you want to capture a snapshot of a slow frame on the server, there are a few options: | ||
Latest revision as of 10:50, 4 December 2024
Versions with performance profiling
The Profiling build is provided in semi regular intervals between major game version updates by Dedmen in tandem with Arma 3 Performance build.
The download and changelog can be found in the BI Forums as well as in the #perf_prof_branch channel in the official Arma 3 Discord server.
How to set up
Sample batch file to auto rename the exe: replaceArma3exeWithProfiling.bat
cd /D "C:\Program Files (x86)\Steam\steamapps\common\Arma 3"
del arma3.exe
copy /Y /B arma3profiling_x64.exe arma3.exe
Steam branch
AUTOMATIC (Recommended) - see also Steam Branches.
- Open Steam
- Right click on Arma 3 in your Steam Library, then Properties
- Select the tab betas
- Finally, use the dropdown list to select the branch profiling - Performance Profiling Build
- Wait for the download to finish
This will automatically download newest performance and profiling exes once they are available.
Google Drive
MANUAL (only when needed)
- Download and install 7z (usually the 64-bit Windows x64 variant)
- Open BI forum thread
- Got to latest post with a link to google drive
- Browse to the latest game version and profiling build version folder
- Download the desired exe from the google drive folder (usually the arma3client_x64_profiling_XXX.7z)
- Extract the 7z file and copy the exe to your game folder (usually C:
\Program Files (x86) \Steam \steamapps \common \Arma 3)
FPS basics
The duration the engine needs to compute all calculations in one cycle is called a frame. The frame-rate, or frames-per-second (fps), in return states how many cycles the engine could compute for a given second.
| FPS | seconds | milliseconds |
|---|---|---|
| 100 | 0.010 | 10 |
| 60 | 0.017 | 17 |
| 50 | 0.020 | 20 |
| 40 | 0.025 | 25 |
| 30 | 0.033 | 33 |
| 20 | 0.050 | 50 |
| 10 | 0.100 | 100 |
| 5 | 0.200 | 200 |
| 4 | 0.250 | 250 |
| 3 | 0.333 | 333 |
| 2 | 0.500 | 500 |
| 1 | 1.0 | 1000 |
Duration parameter
- The duration parameter is a time measured in seconds. 0.3 (seconds) is the same as 300 ms / milliseconds.
- It is used to determine what duration of a frame you consider abnormal or that you are interested in for other reasons.
- The first time such frame happens, the frame information will be captured - or put differently: when a situation occurs with a frame lasting longer than said duration.
- 0.3 (<3 fps for the whole frame) is definitely something you should not see in a normal game.
- If you do not capture any frames with 0.3, try lowering it to 0.2 (200 ms / <5 fps) or 0.1 (100 ms / <10 fps).
- If it triggers "too early" before the main slowdown happens that you want to analyze, increase it to a higher value, e.g. 1.0 for long freeze (<1 fps).
Scope parameter
- total is name for the scope of the duration for the whole frame (sLoop on a dedicated server, cLoop on a headless client).
- With the total scope you capture more or less your frames per second (fps) - if your current frame-rate is essentially stable. In other words if all frames for that second have roughly similar duration.
- In some situations you may encounter single/few frame lasting mini-freezes - aka one/few frames take rather long to complete (ie 100 ms), yet the rest remains in your normal fps range (20 ms for 50 fps for example).
- Whereas a longer freeze means usually a frame last very long, like a second or longer. Thus the game stalls altogether for the given timeframe.
- The scope parameter now allows you to capture subparts of a frame, of different parts of the engine computation - in general terms like networking, world and unit simulation, AI behavior, sound, rendering and visibility checks.
- The total scope is also from the main thread and could be called main frame - all things the engine has to complete in a cycle. In addition there are other threads, where the engine moves other tasks to be computed alongside. Essentially this is what multi-threading is about, allowing the CPU with multiple cores to compute more things at the same time, and thus to reduce the duration of the main frame.
- With the scope parameter you can capture said subparts from the "main frame", yet also from the so called "worker" threads.
- The names for scopes/subscopes you can get from the diag capture dialog or in the frame capture logging files (.log/.trace).
How to capture
Client
Current Frame
If you want to capture a snapshot of a current moment, there are a few options:
1. Via Arma 3 Cheats
- Press ⇧ Shift + NUM -
- Type frame
- As result the diag capture dialog opens
2. Via Debug Console
- Open the console (ESC key to open pause menu or ⇧ Shift + D in the)
- Execute diag_captureFrame 1;
- As result the diag capture dialog opens
Mods to enable console in any mission:
- Enable Debug Console = 1 (Access - ADMIN) by Mr. Uplay
- Enable Debug Console = 2 (Access - ALL) by Mr. Uplay
- enableDebugConsole by Sams
- Debug Console by R3vo
Strongly recommended: Use an enhanced debug console like CBA_A3 or DevCon mod
3. Via custom action
You need to execute in the console the following code first to add the action:
To remove the action again:
4. Via mission specific code
Slow Frame
If you want to capture a snapshot of a slow frame, there are a few options:
1. Via Arma 3 Cheats
- Press ⇧ Shift + NUM -
- Type sframe
- Once the game falls below 30 fps (30 ms / 0.030 (s) duration for for total scope) the diag capture dialog opens
2. Via Debug Console
- Open the console (ESC key to open pause menu or ⇧ Shift + D in the)
- Execute diag_captureSlowFrame ["total", 0.03];// [scope, duration]
- As result the diag capture dialog opens
3. Via custom action
You need to execute in the console the following code first to add the action:
Customize the scope and duration as desired.
To remove the action again:
4. Via mission specific code
Server
Current Server Frame
If you want to capture a snapshot of a current moment on the server, there are a few options:
1. Via Admin chat commands
- Open the chat window by pressing the chat key (default /).
- Type #captureFrame
- The current frame on the server is captured and written to a log file in the same directory as the .rpt file.
2. Via Debug Console
- Open the console (ESC key to open pause menu)
- Execute [1] remoteExec ["diag_captureFrame", 2];
- As result the diag capture dialog opens
Mods to enable console in any mission:
- Enable Debug Console = 1 (Access - ADMIN) by Mr. Uplay
- Enable Debug Console = 2 (Access - ALL) by Mr. Uplay
- enableDebugConsole by Sams
- Debug Console by R3vo
Strongly recommended: Use an enhanced debug console like CBA_A3 or DevCon mod
3. Via custom action
You need to execute in the console the following code first to add the action:
To remove the action again:
4. Via mission specific code
Slow Server Frame
If you want to capture a snapshot of a slow frame on the server, there are a few options:
1. Via Admin chat commands
- Open the chat window by pressing the chat key (default /).
- Type #captureSlowFrame sLoop 0.03 0 1 - parameters scope, threshold, frameOffset, numberOfSlowFrames to capture
- Captures one frame on the server if it exceeds the set threshold in seconds for the given scope (30 ms / 0.030 (s) duration for for sLoop scope)
- The frame information get written to a log file in the same directory as the .rpt file
2. Via Debug Console
- Open the console (ESC key to open pause menu)
- Execute [["sLoop", 0.03]] remoteExec ["diag_captureSlowFrame", 2]; // [scope, duration]
- As result the diag capture dialog opens
3. Via custom action
You need to execute in the console the following code first to add the action:
Customize the scope and duration as desired.
To remove the action again:
4. Via mission specific code
Storing a capture to file
To export the gathered information of a capture for later analysis/review or to share it with others, you have the following options:
Diag capture dialog
- Press the Copy All button
- Open an external text editor
- Paste the text into a new text/log file
- Save the file (as .txt or .log)
diag_captureSlowFrame
The sqf command diag_captureSlowFrame has the boolean toFile as forth parameter. In addition with the Number continuousCounter as fifth parameter you can make it log multiple captures in one go.
[section, threshold, frameSkip, toFile, continuousCounter]
- Client: diag_captureSlowFrame ["total", 0.03, 0, true, 1];
- Server: [["total", 0.03, 0, true, 1]] remoteExec ["diag_captureSlowFrame", 2];
Dedicated server
The Admin chat commands #captureFrame / #captureSlowFrame sLoop 0 will automatically create both .log and .trace format files on the server in the rpt log folder. See above server section for more information.
For customized server side logging use the remoteExec approach or console with remote/target execution.
How to view a capture
TODO
Ingame
- In the window you will be able to browse a lot of performance-related data, which can be interesting
TODO
Externally
Perfetto UI Web Viewer
Pros:
- Can view a frame capture without Arma 3 running
- Nice visualization
- Sub scopes easier to identify
Cons:
- Fairly slow to load/display a frame capture
- Navigation via mouse and keyboard not super intuitive - see Support - Keyboard shortcuts in the left side menu
- Does not support viewing multiple frame captures (only via multiple tabs)
- .trace JSON export from Arma 3 doesnt support more advanced features of Perfetto UI nor contains information on CPU-RAM use
Website: https://ui.perfetto.dev
Tracy Live Viewer
Works only with the custom tracy version provided by Dedmen as part of the Arma Script Profiler mod.
Pros:
- Live frame capture
- Multiple frame captures - see frame by frame
- Statistics like number of executions, average and mean time execution
- Selection of zones for specific analysis of any time frame
- Profiling of unscheduled code. See: ArmaScriptProfiler
Cons:
- Fairly advanced
- Tracy UI more functional than visually nice
Required mods:
- CBA_A3: https://steamcommunity.com/workshop/filedetails/?id=450814997
- Arma Script Profiler: https://steamcommunity.com/sharedfiles/filedetails/?id=1652506957
- Intercept Minimal Dev: https://steamcommunity.com/workshop/filedetails/?id=1645973522
Extra startup parameters: -profilerEnableEngine -profilerEngineThreads "-mod=!Workshop\@CBA_A3;!Workshop\@Arma Script Profiler;!Workshop\@Intercept Minimal Dev"
- How to use: https://github.com/dedmen/ArmaScriptProfiler/wiki
- Additional command line parameters: https://github.com/dedmen/ArmaScriptProfiler/wiki/Command-line-parameters
- Some more info at: https://forums.bohemia.net/forums/topic/211626-arma-script-profiler/
- Source: https://github.com/dedmen/ArmaScriptProfiler
- Discord for tech support and such: https://discord.gg/vbFje5B
Advanced info:
Scripting Commands
- diag_captureFrame
- diag_captureSlowFrame
- diag_logSlowFrame - not available in Arma 3. Since
2.20 diag_captureSlowFrame with toFile parameter can log to file as alternative. - diag_captureFrameToFile
Creating Your Own Subtree
When Profiling Per-Frame Eventhandlers (PFH), diag_captureFrame only shows one blob called siFEH that contains all PFH's so you can't see what part of that is caused by your PFH.
You can create your own subtree inside siFEH by wrapping your function call inside a isNil CODE statement like this:
Turn your old call which may look like this:
Into something like this:
Now when you run diag_captureFrame inside of siPFH you will have a subtree called gsEva and behind that you can see the first line of code inside the isNil statement.
It will only show a part of the first line of that code so you should put something descriptive into the isNil statement.
You can use the same to create a subtree for any function you like. This will also work inside Scheduled (spawned) scripts.
But using this method to "subtree" a function with return values requires a little bit of trickery to get the return value out.