Use the AsyncReadManagerMetrics class to monitor runtime asset loading and file reading performance. This class records data for all file read operations managed by the AsyncReadManager.
Unity uses the AsyncReadManager to read most files at runtime, including AssetBundles, Addressables, and Resources. You can also load files from scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary using AsyncReadManager.Read.
You can use the AsyncReadManagerMetrics to do the following:
This information can help you identify problems with asset loading and measure the impact of your changes have on performance.
The AsyncReadManagerMetrics class is only available in development buildsA development build includes debug symbols and enables the Profiler. More info
See in Glossary. To ensure compatibility, wrap calls to AsyncReadManagerMetrics APIs in an #if preprocessor directive using the ENABLE_PROFILER symbol. For older Unity versions, use the UNITY_2020_2_OR_NEWER symbol to remove the metric code. For example:
#if ENABLE_PROFILER && UNITY_2020_2_OR_NEWER
AsyncReadManagerMetrics.StartCollectingMetrics();
#endif
Enable metrics collection before any data is recorded. You can do this in one of the following ways:
AsyncReadManagerMetrics.StartCollectingMetrics in your script.-enable-file-read-metrics command-line argument when launching your application.To collect metrics in Play mode, pass the -enable-file-read-metrics argument when launching the Unity Editor. However, the Editor loads some categories of assets, such as textures, and doesn’t reload them when you enter Play mode. For complete file I/O metrics, you must collect data from a development build of your application.
Use GetMetrics to retrieve collected metrics from AsyncReadManagerMetrics. Specify AsyncReadManagerMetrics.Flags to determine whether to clear metrics after retrieval. Clearing metrics removes completed (including canceled and failed) reads but retains queued or in-progress operations. To access the metrics for unfinished operations, call GetMetrics again after they complete. By clearing the metrics regularly, you can avoid rereading the same data and also reduce the data overhead of the system.
#if ENABLE_PROFILER && UNITY_2020_2_OR_NEWER
AsyncReadManagerRequestMetric[] metrics
= AsyncReadManagerMetrics.GetMetrics(AsyncReadManagerMetrics.Flags.ClearOnRead);
#endif
Metrics data includes the following context data:
AssetLoadingSubsystem that initiated the read. If unavailable, defaults to Other.AssetName. If unavailable, defaults to empty.AssetTypeID. If unavailable, defaults to zero.The following is a list of supported asset TypeIDs:
| TypeID | Type name |
|---|---|
| 28 | Texture2D |
| 117 | Texture3D |
| 89 | CubeMapA collection of six square textures that can represent the reflections in an environment or the skybox drawn behind your geometry. The six squares form the faces of an imaginary cube that surrounds an object; each face represents the view along the directions of the world axes (up, down, left, right, forward and back). More info See in Glossary |
| 43 | Mesh |
For other TypeIDs that might appear, refer to YAML class ID reference.
Get a summary of the AsyncReadManager metrics with the following methods:
GetCurrentSummaryMetrics: Returns a summary of all the metrics collected after the last time you cleared the metric store.GetSummaryOfMetrics: Returns a summary of the metrics in an array of AsyncReadManagerRequestMetric, which you can get by calling GetMetrics.For example:
#if ENABLE_PROFILER && UNITY_2020_2_OR_NEWER
AsyncReadManagerSummaryMetrics summaryOfMetrics
= AsyncReadManagerMetrics.GetCurrentSummaryMetrics(AsyncReadManagerMetrics.Flags.ClearOnRead);
#endif
Or:
#if ENABLE_PROFILER && UNITY_2020_2_OR_NEWER
AsyncReadManagerRequestMetric[] metrics
= AsyncReadManagerMetrics.GetMetrics(AsyncReadManagerMetrics.Flags.ClearOnRead);
AsyncReadManagerSummaryMetrics summaryOfMetrics
= AsyncReadManagerMetrics.GetSummaryOfMetrics(metrics);
#endif
Summary statistics include:
For a full list of summary metrics, refer to AsyncReadManagerSummaryMetrics.
By default, the summarized statistics include all read operations, including those that are queued or in-progress. You can use a filter to limit the summary to those operations you’re interested in. For example, you can use a filter to limit the summarized statistics to completed read operations for texture assets.
Note: Calculating summaries requires processing resources. To avoid affecting your measurements, collect metrics first and summarize them after operations are complete.
Use AsyncReadManagerMetricsFilters to filter summarized data. You can filter by the following:
AssetLoadingSubsystem.You can set multiple categories for the same filter. A read operation must match all categories for the metrics of that operation to be included in the summary. For example, you can specify values for both the ProcessingState and the Subsystem of a filter to summarize only operations in the designated processing states initiated by the designated subsytems.
You can also specify multiple values for a category. In this case, a read operation can match any value you specify for a category for its metrics to be included in the summary. For example, filtering by both meshThe main graphics primitive of Unity. Meshes make up a large part of your 3D worlds. Unity supports triangulated or Quadrangulated polygon meshes. Nurbs, Nurms, Subdiv surfaces must be converted to polygons. More info
See in Glossary and textureAn image used when rendering a GameObject, Sprite, or UI element. Textures are often applied to the surface of a mesh to give it visual detail. More info
See in Glossary includes operations for both asset types.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.