--- name: "Performance Profiling" type: topic source: https://community.bistudio.com/wiki/Performance_Profiling revid: 370411 updated: 2024-12-05T17:53:05Z --- # Performance Profiling ### 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](../topics/Steam_Branches.md). The download and changelog can be found in the [BI Forums](https://forums.bistudio.com/forums/topic/160288-arma-3-stable-server-170-performance-binary-feedback/) as well as in the `#perf_prof_branch` channel in the [official Arma 3 Discord server](https://discordapp.com/invite/arma). > [!IMPORTANT] > - Through the nature of a Profiling build (due to additional "measuring"/profiling code), they are not as performant as the normal release builds! > - Performance Profiling works also with the [Diagnostics Exe](../topics/Diagnostics_Exe.md). ### Setup > [!IMPORTANT] > - To use the profiling build, you must launch the game with the **arma3profiling_x64.exe** (arma3serverprofiling_x64.exe for the server). > - One way is to delete the **arma3.exe**, and rename the profiling exe to it. This way you can continue to use the [Arma 3 launcher](../topics/Launcher.md) to launch the game with your [startup parameters](../topics/Startup_Parameters.md) by selecting **Platform: 32-bit** under **All Parameters** (or other third party launcher applications). > - The alternative is to use [batch files](https://www.windowscentral.com/how-create-and-run-batch-file-windows-10) (and copy your [startup parameters](../topics/Startup_Parameters.md) from the top of a rpt log file from a regular session). Sample batch file to auto rename the exe: **replaceArma3exeWithProfiling.bat** ```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](../topics/Steam_Branches.md). 1. Open Steam 1. Right click on **Arma 3** in your Steam Library, then **Properties** 1. Select the tab **betas** 1. Finally, use the dropdown list to select the branch **profiling - Performance Profiling Build** 1. 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) 1. Download and install [7z](https://www.7-zip.org/download.html) (usually the 64-bit Windows x64 variant) 1. Open [BI forum thread](https://forums.bistudio.com/forums/topic/160288-arma-3-stable-server-170-performance-binary-feedback/) 1. Got to latest post with a link to google drive 1. Browse to the latest game version and profiling build version folder 1. Download the desired exe from the google drive folder (usually the arma3client_x64_profiling_XXX.7z) 1. Extract the 7z file and copy the exe to your game folder (usually `C:\Program Files (x86)\Steam\steamapps\common\Arma 3`) **FPS conversion table** | FPS | seconds | milliseconds | |---|---|---| | 1000 | 0.001 | 1 | | 500 | 0.002 | 2 | | 333 | 0.003 | 3 | | 250 | 0.004 | 4 | | 200 | 0.005 | 5 | | 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 | ### 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. > [!NOTE] > - One second consists of one thousand [milliseconds](https://en.wikipedia.org/wiki/Millisecond) (1 s = 1000 ms). > - The shorter a cycle/frame, the higher the FPS. > [!IMPORTANT] > **total** only works for a client (a machine with [interface](../commands/hasInterface.md)). Basically the equivalent for the dedicated server is **sLoop** and for a headless client it is **cLoop**. Example: | | | |---|---| | ```sqf
diag_captureSlowFrame ["total", "50fps"];
diag_captureSlowFrame ["total", "0.02s"];
diag_captureSlowFrame ["total", "20ms"];
``` | ```sqf
diag_captureSlowFrame ["total", "30fps"];
diag_captureSlowFrame ["total", "0.033s"];
diag_captureSlowFrame ["total", "33ms"];
``` | ### 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 > [!IMPORTANT] > The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). - **total** is name for the scope of the duration for the whole frame (**sLoop** on a [dedicated server](../topics/Dedicated_Server.md), **cLoop** on a [headless client](../topics/Headless_Client.md)). - 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](../topics/Cheats.md) 1. Press ⇧ Shift + NUM - 1. Type `frame` 1. As result the **diag capture dialog** opens > [!IMPORTANT] > - This is a very rough way to capture the game is running while you are typing. > - Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when you do a capture in that menu, you only get a capture for the menu simulation. > - You can use the *frame* cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc. 2. Via [Debug Console](../topics/Debug_Console.md) 1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the) 1. Execute `diag_captureFrame 1;` 1. As result the **diag capture dialog** opens > [!IMPORTANT] > - This is a very rough way to capture the game is running while you are typing. > - Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when you do a capture in that menu, you only get a capture for the menu simulation. > - To avoid that, you need to delay the execution until the pause menu is closed again. For example by: `(findDisplay 49) closeDisplay 0; diag_captureFrame 3;` > - To have the console available in a mission (outside the), you need to enable it via the [Description.ext - enableDebugConsole](../topics/Description.ext.md#enabledebugconsole) parameter. > - Alternatively you can enable the console in any missions via mods (see below). Mods to enable console in any mission: - [Enable Debug Console = 1 (Access - ADMIN)](https://steamcommunity.com/sharedfiles/filedetails/2000114984) by Mr. Uplay - [Enable Debug Console = 2 (Access - ALL)](https://steamcommunity.com/sharedfiles/filedetails/2000131738) by Mr. Uplay - [enableDebugConsole](https://steamcommunity.com/sharedfiles/filedetails/1939811222) by Sams - [Debug Console](https://steamcommunity.com/sharedfiles/filedetails/1231625987) by R3vo > [!IMPORTANT] > For dedicated server use, you need to allow the given mod by uploading the respective bikey to the server's keys folder - or disable `verifySignatures = 0;` via [server.cfg](../topics/Server_Config_File.md). **Strongly recommended**: Use an enhanced debug console like [CBA_A3](https://steamcommunity.com/sharedfiles/filedetails/450814997) or [DevCon](https://steamcommunity.com/sharedfiles/filedetails/281032552) mod 3. Via custom action You need to execute in the console the following code first to add the action: ```sqf if (!(isNil "temp_diag_captureFrame_action")) then { player removeAction temp_diag_captureFrame_action; temp_diag_captureFrame_action = nil; }; temp_diag_captureFrame_action = player addAction ["captureFrame", { diag_captureFrame 1; }]; ``` To remove the action again: ```sqf if (!(isNil "temp_diag_captureFrame_action")) then { player removeAction temp_diag_captureFrame_action; temp_diag_captureFrame_action = nil; }; ``` 4. Via mission specific code 1. [Functions](../topics/Function.md) 1. [On Activation](../topics/Eden_Editor~3A_Trigger.md#on-activation) by [Triggers](../topics/Eden_Editor~3A_Trigger.md) 1. [Object init field](../topics/Eden_Editor~3A_Object.md#attributes) ##### Slow Frame > [!IMPORTANT] > The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). If you want to capture a snapshot of a slow frame, there are a few options: 1. Via [Arma 3 Cheats](../topics/Cheats.md) 1. Press ⇧ Shift + NUM - 1. Type `sframe` 1. Once the game falls below 30 fps (30 ms / 0.030 (s) duration for for **total** scope) the diag capture dialog opens > [!IMPORTANT] > - This is a very basic way to capture slow frames as the limit is not customizable and only works on the **total** scope. For customizable scope and duration use the options below. > - Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when you do a capture in that menu, you only get a capture for the menu simulation. > - You can use the *sframe* cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc. 2. Via [Debug Console](../topics/Debug_Console.md) 1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the) 1. Execute `diag_captureSlowFrame ["total", 0.03];// [scope, duration]` 1. As result the **diag capture dialog** opens > [!IMPORTANT] > - There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive. > - Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when capture triggers while you are still in that menu, you only get a capture for the menu simulation. > - To avoid that, you need to delay the execution until the pause menu is closed again. For example by: `(findDisplay 49) closeDisplay 0; diag_captureSlowFrame ["total", 0.03, 3];` > - To have the console available in a mission (outside the), you need to enable it via the [description.ext enableDebugConsole parameter](../topics/Description.ext.md#enabledebugconsole). > - Alternatively you can enable the console in any missions via mods (see above). 3. Via custom action You need to execute in the console the following code first to add the action: ```sqf if (!(isNil "temp_diag_captureSlowFrame_action")) then { player removeAction temp_diag_captureSlowFrame_action; temp_diag_captureSlowFrame_action = nil; }; temp_diag_captureSlowFrame_action = player addAction ["captureSlowFrame", { diag_captureSlowFrame ["total", 0.03]; }]; ``` Customize the scope and duration as desired. To remove the action again: ```sqf if (!(isNil "temp_diag_captureSlowFrame_action")) then { player removeAction temp_diag_captureSlowFrame_action; temp_diag_captureSlowFrame_action = nil; }; ``` 4. Via mission specific code 1. [Functions](../topics/Function.md) 1. [On Activation](../topics/Eden_Editor~3A_Trigger.md#on-activation) by [Triggers](../topics/Eden_Editor~3A_Trigger.md) 1. [Object init field](../topics/Eden_Editor~3A_Object.md#attributes) #### 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](../topics/Multiplayer_Server_Commands.md#performance-profiling) 1. Open the chat window **by pressing the chat key** (default /). 1. Type `#captureFrame` 1. The current frame **on the server** is captured and written to a log file in the same directory as the [.rpt file](../topics/Crash_Files.md). > [!IMPORTANT] > - You must be [logged in as admin](../topics/Server_Config_File.md#logged-in-admin)! > - This is a very rough way to capture the current frame on the server. > - See [diag_captureFrameToFile](../commands/diag_captureFrameToFile.md) for more info. 2. Via [Debug Console](../topics/Debug_Console.md) 1. Open the console (ESC key to open pause menu) 1. Execute `[1] remoteExec ["diag_captureFrame", 2];` 1. As result the **diag capture dialog** opens > [!IMPORTANT] > - This is a very rough way to capture the current frame on the server. > - To have the console available in a mission, you need to enable it via the [description.ext enableDebugConsole parameter](../topics/Description.ext.md#enabledebugconsole). > - Alternatively you can enable the console in any missions via mods (see below). Mods to enable console in any mission: - [Enable Debug Console = 1 (Access - ADMIN)](https://steamcommunity.com/sharedfiles/filedetails/2000114984) by Mr. Uplay - [Enable Debug Console = 2 (Access - ALL)](https://steamcommunity.com/sharedfiles/filedetails/2000131738) by Mr. Uplay - [enableDebugConsole](https://steamcommunity.com/sharedfiles/filedetails/1939811222) by Sams - [Debug Console](https://steamcommunity.com/sharedfiles/filedetails/1231625987) by R3vo > [!IMPORTANT] > For dedicated server use, you need to allow the given mod by uploading the respective bikey to the server's keys folder - or disable `verifySignatures = 0;` via [server.cfg](../topics/Server_Config_File.md). **Strongly recommended**: Use an enhanced debug console like [CBA_A3](https://steamcommunity.com/sharedfiles/filedetails/?id=450814997) or [DevCon](https://steamcommunity.com/sharedfiles/filedetails/?id=281032552) mod 3. Via custom action You need to execute in the console the following code first to add the action: ```sqf if (!(isNil "temp_diag_captureFrame_server_action")) then { player removeAction temp_diag_captureFrame_server_action; temp_diag_captureFrame_server_action = nil; }; temp_diag_captureFrame_server_action = player addAction ["captureFrame (server)", { [1] remoteExec ["diag_captureFrame", 2]; }]; ``` To remove the action again: ```sqf if (!(isNil "temp_diag_captureFrame_server_action")) then { player removeAction temp_diag_captureFrame_server_action; temp_diag_captureFrame_server_action = nil; }; ``` 4. Via mission specific code 1. [Functions](../topics/Function.md) 1. [On Activation](../topics/Eden_Editor~3A_Trigger.md#on-activation) by [Triggers](../topics/Eden_Editor~3A_Trigger.md) 1. [Object init field](../topics/Eden_Editor~3A_Object.md#attributes) ##### Slow Server Frame > [!IMPORTANT] > The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). If you want to capture a snapshot of a slow frame on the server, there are a few options: 1. Via [Admin chat commands](../topics/Multiplayer_Server_Commands.md#performance-profiling) 1. Open the chat window **by pressing the chat key** (default /). 1. Type `#captureSlowFrame sLoop 0.03 0 1` - parameters *scope, threshold, frameOffset, numberOfSlowFrames to capture* 1. 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) 1. The frame information get written to a log file in the same directory as the [.rpt file](../topics/Crash_Files.md) > [!IMPORTANT] > - You must be [logged in as admin](../topics/Server_Config_File.md#logged-in-admin)! > - Customize the numberOfSlowFrames as you see fit. > - There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive. > - See [diag_captureSlowFrame](../commands/diag_captureSlowFrame.md) for more info. 2. Via [Debug Console](../topics/Debug_Console.md) 1. Open the console (ESC key to open pause menu) 1. Execute `[["sLoop", 0.03]] remoteExec ["diag_captureSlowFrame", 2]; // [scope, duration]` 1. As result the **diag capture dialog** opens > [!IMPORTANT] > - To have the console available in a mission, you need to enable it via the [description.ext enableDebugConsole parameter](../topics/Description.ext.md#enabledebugconsole). > - Alternatively you can enable the console in any missions via mods (see above). 3. Via custom action You need to execute in the console the following code first to add the action: ```sqf if (!(isNil "temp_diag_captureSlowFrame_server_action")) then { player removeAction temp_diag_captureSlowFrame_server_action; temp_diag_captureSlowFrame_server_action = nil; }; temp_diag_captureSlowFrame_server_action = player addAction ["captureSlowFrame (server)", { [["sLoop", 0.03]] remoteExec ["diag_captureSlowFrame", 2]; }]; ``` Customize the scope and duration as desired. To remove the action again: ```sqf if (!(isNil "temp_diag_captureSlowFrame_server_action")) then { player removeAction temp_diag_captureSlowFrame_server_action; temp_diag_captureSlowFrame_server_action = nil; }; ``` 4. Via mission specific code 1. [Functions](../topics/Function.md) 1. [On Activation](../topics/Eden_Editor~3A_Trigger.md#on-activation) by [Triggers](../topics/Eden_Editor~3A_Trigger.md) 1. [Object init field](../topics/Eden_Editor~3A_Object.md#attributes) ### 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 1. Press the **Copy All** button 1. Open an external text editor 1. Paste the text into a new text/log file 1. Save the file (as .txt or .log) > [!NOTE] > Standard naming is: **captureFrame-DATE_TIME.log** - like `captureFrame-17452-2024-11-21_18-12-37.211027.log` > [!IMPORTANT] > As alternative if you hold ⇧ Shift while pressing the **Copy All** button, it will instead use the **.trace** format used by third-party viewers like https://ui.perfetto.dev/#!/info #### diag_captureSlowFrame The sqf command `diag_captureSlowFrame` has the [boolean](../topics/Boolean.md) **toFile** as forth parameter. In addition with the [Number](../topics/Number.md) **continuousCounter** as fifth parameter you can make it log multiple captures in one go. ```cpp [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](../topics/Multiplayer_Server_Commands.md#performance-profiling) `#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 1. 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 > [!IMPORTANT] > Only supports `.trace` format frame captures! ##### Tracy Live Viewer Works only with the custom tracy version provided by Dedmen as part of the [Arma Script Profiler](https://steamcommunity.com/sharedfiles/filedetails/1652506957) mod. > [!NOTE] > Capturing live data needs a lot of RAM - up to 2 GB per minute (depends on detail level captured). 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: 1. CBA_A3: https://steamcommunity.com/workshop/filedetails/?id=450814997 1. Arma Script Profiler: https://steamcommunity.com/sharedfiles/filedetails/?id=1652506957 1. 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: - https://tracy.nereid.pl - https://github.com/wolfpld/tracy ### Scripting Commands - [diag_captureFrame](../commands/diag_captureFrame.md) - [diag_captureSlowFrame](../commands/diag_captureSlowFrame.md) - diag_logSlowFrame - not available in Arma 3. Since Arma 3 v2.20 [diag_captureSlowFrame](../commands/diag_captureSlowFrame.md) with **toFile** parameter can log to file as alternative. - [diag_captureFrameToFile](../commands/diag_captureFrameToFile.md) ### Creating Your Own Subtree When Profiling Per-Frame Eventhandlers (PFH), [diag_captureFrame](../commands/diag_captureFrame.md) 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](../commands/isNil.md) CODE statement like this:\ Turn your old call which may look like this: ```sqf addMissionEventHandler ["EachFrame", { call myPFHFunction }]; ``` Into something like this: ```sqf addMissionEventHandler ["EachFrame", { isNil { call myPFHFunction } // isNil creates the subtree }]; ``` Now when you run [diag_captureFrame](../commands/diag_captureFrame.md) 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](../commands/isNil.md) statement.\ You can use the same to create a subtree for any function you like. This will also work inside [Scheduled](../topics/Scheduler.md#scheduled-environment) ([spawned](../commands/spawn.md)) scripts. \ But using this method to "subtree" a function with return values requires a little bit of trickery to get the return value out. ### See Also - [Code Optimisation](../topics/Code_Optimisation.md) - [Mission Optimisation](../topics/Mission_Optimisation.md) Source: [BI Community Wiki — Performance Profiling](https://community.bistudio.com/wiki/Performance_Profiling) (revision 370411).