Introducing the Editor Iteration Profiler

Editor Iteration Profiler (EIP)
Before diving into the details I will start by defining what an iteration is. An iteration is a process that contains instructions that are repeated until a condition is met. Unity relies on different types of iterations.

The Editor Iteration Profiler monitors iterations that are related to the scripting side of Unity, specifically entering and exiting playmode, assembly compilation, and assembly reload.

The tool is an attempt to empower you, our users, to understand and help you solve the common question “Why does it take so long to compile my scripts/enter playmode?”. EIP accomplishes this by monitoring profiler frames and saving them in a window where you can more easily navigate through the data the profiler produces. Additionally, the data persists for the whole lifetime of the Editor (or until it’s cleared), as opposed to the Profiler, which has a limit to the number of previously stored frames.

Disclaimer: This tool is still under development and anything could change on the API side.

High-level features summary

• Monitor and capture profiling data from assembly reload, assembly compilation, and enter playmode.
  
  
• Export captured data or Profiler data to a number of formats such as HTML, JSON (for chrome://tracing, which is a fast flame-graph style data visualizer), CSV, and Plaintext.
  
  
• Export to a special type of HTML (HTML Performance Report), which attempts to minimize the number of clicks needed to get to the important areas of the profiled data, as well as aggregate possible areas of interest which could be optimized (e.g. OnEnable calls)

How to use
Compatible with 2019.3 and later. It might work with earlier versions but it is not tested.

1. Download the repository from GitHub - https://github.com/Unity-Technologies/com.unity.editoriterationprofiler. Alternatively you can get it through OpenUPM: https://openupm.com/packages/com.unity.editoriterationprofiler/
   
   
2. Place the contents in a folder in your Project’s Packages folder
   
   
3. Open up the project and open the window from Windows -> Analysis -> Editor Iteration Profiler -> Show Window
   
   
4. You should see a window very similar to this

The basics
To enable the tool, you just need to click the Enable button in the window. The window doesn’t need to be open afterward: it will run in the background.


After an iteration happens, it will show up in the window as follows:





UI
Please note that the UI might change/have changed slightly, however, the functionality should be the same.

• Enable - enables the Profiler and sets it to run in Editor mode.
  
  
• Deep Profile - useful to get all information about managed calls. (https://docs.unity3d.com/Manual/ProfilerWindow.html#deep-profiling)
  
  
• Flattening - attempts to reduce the number of clicks needed to get to the place that is of interest. Works by ‘collapsing’ levels which contain multiple parented items with 1 child. Useful for GUI code and Deep Profiling.
  
  
• User Code - is an attempt to filter out engine code and only show code the User might be interested in.
  
  
• Clear - removes recorded events and events which the EIP is looking for.
  
  
• Collapse All - recursively collapses every item.
  
  
• Print to Console - logs the captured data into plaintext into the console/log file.
  
  
• Export… - dropdown to export captured data in various formats.
  
  
• Export Profiler Data… - dropdown to choose between exporting the selected frame in the Profiler Window or exporting multiple frames, frame by frame, between 2 ranges. It will automatically export the data to a selected folder.

• Search Bar - works as you would expect. Selecting an item and either pressing the F key or clearing the search will automatically expand the tree view to that item.

Exporters

After you have captured some data, you might want to export it. You can do this by clicking the Export… dropdown and choosing a format.





Here you can get the samples exported above for you to test out.

The Formats

Opening the HTML you will see something similar to this:



It mostly contains the same data as the EIP Window, with the addition of the percentages. Items in square brackets “[ ]” are leaf items without any children.


The JSON format is meant to be used within Google Chrome's chrome://tracing, which works on chromium-based browsers like Google Chrome, Microsoft Edge Chromium (edge://tracing - chrome://tracing will be replaced by it if typed), Opera, etc.. It is a fast, lightweight and Editor-agnostic way to view the captured data in the flame-graph style. In this gif, we show how to load and use the file into chrome://tracing.


CSV can be used to load the data into other programs, for example. It is pretty difficult for humans to make sense of it. Also please be aware of the ‘header’ which contains environment information in case you plan to do further processing.


Exporting Plaintext is the same as the one it is printed in the console with the “Print to Console” button. Using this you have the option to isolate the data and not have other information which is in the Editor.log file.


The HTML Performance Report is based on the same structure as the regular HTML report, however, functionally it is different. The purpose of it is to distill the information into something humans would more easily understand. It basically does this by reducing the number of levels you have to click through to get to the areas of interest, where code diverges more.




The items in curly brackets “{ }” represent items that have more children which were hidden due to the parents being under the minimum set threshold (currently a hard-coded value of 1%).

The colored items represent ‘buckets’ of similar data, which is grouped in one place for convenience. The total time of these items is not added to the original time, it’s only there to give an estimate for that iteration.


Known Bugs/Limitations (must read this before using it)

• After a Domain reload, items under ScriptCompilation->AssemblyReload get reparented to AssetImport

• Data might overlap on chrome://tracing because timestamp mismatches between the EIP's timestamp and the Profiler timestamp (to be fixed in the future)
  
  
• Sorting data doesn't work in-window
  
  
• In order to get the most accurate data (especially with DeepProfile enabled), close as many Editor Windows as possible, including the EIP Window itself (it will keep working even when closed if it's Enabled). The reason is that rebuilding the Tree Hierarchy view and repainting the GUI takes time and it will "pollute" the data you might be looking for. The more data, the more it will be polluted (Deep Profile will naturally lead to this faster)
  
  
• When clicking the Profiler Window after clicking Enable in the EIP Window, the EIP's state will be overridden to whatever the original setting in the Profiler was
  
  
• May cause unity to crash when closing it while the EIP is Enabled

Feedback
In terms of feedback, we're especially looking for:

• Are there any useful use-cases not covered?
  
  
• Are there any workflows that are unclear or missing?
  
  
• Is there anything that is unclear or that you don’t understand?
  
  
• Are there any issues or unclear parts in the documentation or this post?

Please feel free to post any feedback in this sub-forum.

How to report bugs
Please open bugs/suggestions at https://github.com/Unity-Technologies/com.unity.editoriterationprofiler/issues.
Please describe the steps as well as include any relevant files necessary for reproduction.

Troubleshooting
If you encounter any problems, the simplest fix is usually to use the Clear button for the window. Another option you can try is through Window -> Analysis -> Editor Iteration Profiler -> Purge Caches.D

 

That is not necessary. You can either embed a package in your Package folder or reference it in a local folder

Code (CSharp):

1.  "com.unity.editoriterationprofiler": "file:../path/to/com.unity.editoriterationprofiler-master"

You can of course also do the local reference using the Package Manager UI.

 

If you choose to reference the package as a local reference. It is correct that the manifest needs to change. This is described here: https://docs.unity3d.com/Manual/upm-ui-local.html
However there is also the option of adding the package inside the Packages folder. That is called an embedded package. That is what is described as the suggestion in this guide. The documentation for that is here: https://docs.unity3d.com/Manual/upm-embed.html

 

I am not aware of this, sounds like a bug I don't know of. Mind sharing more info?

There is a bug mentioned under Known Issues where the frame responsible for Assembly Reload gets reparented to AssetImport (see image below, red) when the tree is rebuilt.

 

How often it reproduces? Is it a Script Compilation event? If it's often what are the steps? Do you have Deep Profiling enabled?

Can you try going to Window -> Analysis -> Editor Iteration Profiler -> Purge Caches and then Clear in the EIP Window? What about restarting the Editor?

 

My bad, changed it to 2019.3+

The issue is simply that those API's aren't available in 2019.2.

 

Thanks for the heads up! I replaced them with UnityEngine.Assertions

 

Looks like you are running on OSX? Can you tell me which version of Unity and OSX you are running? There are a few bugs in OSX apparently that I am becoming aware of because I developed this tool on Windows mostly. It might be a bug with IMGUI potentially

 

Hi, thanks for the feedback!

The errors you are seeing are probably because the Editor Iteration Profiler is looking for Domain Reloads (they happen while Building), but then it tries to add it to a root which is not there, as it's created in another code path. I will try to fix this if it's quick but I also have some time planned to also add the ability for the EIP to capture information about building the Players, so awareness EIP might have about Domain Reloads during Building Players might be the right thing to do instead of going around it .

I am aware the sorting is broken and was suggested I should sort before exporting as well. The idea is if I implement sorting for the UI I can also do sorting when exporting. I do have a few days set aside for this quarter for EIP improvements, I think I will focus on this as it is an important feature

Stay tuned!

 

I will try it out on 2019.4, haven't seen this issue otherwise. It's also curious that there is no header for the columns either... and no errors are thrown anywhere? (picture is from Windows)

 

Thanks for this, I've let them know!

 

Indeed, the Burst initialization code you are seeing in the profiling is happening once per domain reload and it is basically gathering the list of assemblies used for Burst. As you have lots of assemblies it seems that it is a direct effect from that. Not sure there is a workaround for that unfortunately. Disabling Burst in the menu won't help, because it is only for disabling compilation, we don't support disabling dynamically Burst entirely from the editor as it would complicate too much the state of kick-starting Burst in the middle of a running editor. But you can disable Burst entirely from the Unity command line by passing

--burst-disable-compilation

 

Yep, we have a type cache for that.

 

Hi, does the AssemblyReload showing as 0 happen only with Deep Profile on? I've had 30GB of RAM easily used up when Deep Profile was on.

As a quick workaround, you could try closing the EIP and Profiler window as the GUI won't have to rebuild the hierarchy trees and draw them (you don't need to have those windows open for EIP to work, you can check what it recorded after the fact).

 

I will look into that, sounds like a bug

 

We are aware of these issues and there are efforts to focus on these issues in the near future. There are some bugs with EIP, it's used more as a concept to help us determine the usefulness of these types of tools for developers. I don't think I can say too many details about it but you should see some interesting features coming to the profiler in the future

 

Yes, it's working as intended. What you need to do is Disable it first, and it will stay disabled.

I can see however that having a way to see if it's enabled or not without the window being open would be useful

 

Interesting, can you tell me which Unity version are you using? Maybe I could look into this, although nowadays our focus is more on general bugfixes so I don't have much time to look into fixing the tool

I will create an issue on GitHub, thanks!

It's not only the tool itself, but potentially any window that is open. If you don't care about UI code polluting the data, I would strongly recommend closing as many windows as possible. It's just the way IMGUI works and a lot of the windows in Unity are still on IMGUI.