unity-anr-project

Unity ANR Plugin

The plugin aims to expose Android OS API functions that help you debug your code and profile.

Supported Unity Versions

• Unity 2022
• Unity 2021
• Unity 2023 (not tested)
• Unity 2023 with GameActivity (not tested)

Setup

• Add the Unity ANR Plugin prefab into your first scene.
  • This GameObject does not destroy after scene unloading.
• The UnityANR script attached to this GameObject will initialize the Java Plugin in an Awake method.
• The script will receive messages from the Java Plugin. Therefore, it is crucial not to rename it after the game runs.
• After initializing, you can safely call the PluginBinder methods.

Important

Once the UnityANR script receives the message from the plugin, the data parsing happens on the Thread Pool for optimization purposes. Check the Unity Thread Solutions for more information on running code in the Unity Main Thread.

Application Exit Info

Describes the information of an application process's death.

Use Case Example

• If this call returns an ANR with a trace file, you could submit an issue to your Reporting Tool and attach a log file and other relevant information.
• Or knowing that a previous run had a problem and it will likely repeat, your game code could take actions to enhance logging or prevent the ANR from happening by:
  • Decreasing graphic quality.
  • Enabling more logs in your game to capture more information.
  • Turning on Memory Stats to enhance your system resources comprehension.

Usage

• Call the PluginBinder.CheckAppExitInfo method.
• The plugin runs on a separate Thread to not impact UnityMain or Main thread.
• Once data is fetched, the plugin uses the UnitySendMessage to communicate with the UnityANR script.
• Listen to the PluginEvents.ApplicationExitInfoFetched event to handle the data.
  • Remember that this call does not happen on the Unity Main Thread

Sample response:

{
    "entries": [
        {
            "Description": "user request after error: Input dispatching timed out (21b6f76 App/com.google.unity.plugin.UnityActivity (server) is not responding. Waited 10001ms for MotionEvent)",
            "FilePath": "ANR_Traces/AppExitInfo_88d33aa0-1604-45d4-be24-c1255e583af5.trace",
            "ID": "88d33aa0-1604-45d4-be24-c1255e583af5",
            "Reason": "ANR",
            "ReasonCode": 6
        }
    ]
}

To access the file:

var path = Path.Combine(Application.persistentDataPath, lastExitInfo.FilePath);

Strict Mode

It helps you find accidental I/O operations on the main thread.

Use Case Example

• During development, you can enable it to identify Main Thread blocks and refactor your code to other threads.
• Identify issues with Third Party plugins.

Usage

• Call the PluginBinder.EnableStrictMode method.
• The plugin calls the Android API with the following settings:
  • detectDiskReads, detectDiskWrites, detectNetwork, detectCustomSlowCalls

Memory Stats

Return general information about the memory state of the system

Use Case Example

• This can be used to track memory information and include it in the ANR report by adding logs or breadcrumbs
• Manage your game memory usage, though note that polling is not recommended and [Memory Warning](#Memory Warning) is the preferred way to do this

Usage

• The UnityANR script starts the memory stats retriever in the plugin.
• The plugin uses a ScheduledThreadPoolExecutor to run the memory stats polling every X seconds.
  • The interval can be set in Unity ANR Plugin prefab.
• The UnityANR script also invokes a function to get the last memory stats.
  • You can also call it manually using PluginBinder.GetMemoryInfo.
• Then, the plugin sends a message to the UnityANR script, which parses the data into MemoryData struct.

Sample response:

{
    "AvailableHeap": "248",
    "AvailableMem": "1311",
    "MaxHeap": "256",
    "PercentAvailable": "36.7",
    "Threshold": "141",
    "Timestamp": "15:19:06:196",
    "TotalMem": "3570",
    "UsedHeap": "8"
}

Memory Warning

Returns the result defined in the onTrimMemory. Similar to the Application.memoryUsageChanged.

Use Case Example

• Unload unused content when memory is pressured
• Track how many sessions the user device received a severe memory warning. If significant, you could decrease the game quality since the device may constantly struggle with memory.

Usage

• Override the Custom Main Manifest in the Unity Project Settings
• Change the activity to android:name="com.google.unity.plugin.UnityActivity"
• The UnityANR receives the messages from the plugin.
• Listen to the PluginEvents.LowMemoryReceived event and use the TrimMemoryData struct.

Debug

The plugin also has several functions that force crashes and ANRs for debugging purposes.

Forcing ANR

The Plugin calls the ActivityManager.appNotResponding method to tell the system that the app's wedged and would like to trigger an ANR. From any Unity script, just call the PluginBinder.ForceANR

Forcing Thread Sleep

There are 2 options when calling the PluginBinder.ForceThreadSleep

• If the argument is true the plugin puts the Unity Main thread to sleep
• Else, the plugin accesses the UI Thread/Main Thread and puts it to sleep
• The plugin sets the default wait time to 15000 ms

Unity Thread Solutions

To run Unity-specific operations, you may need to switch from a Thread Pool to Unity Thread. There are a couple of solutions to accomplish this:

• Await Support
• UniTask
• UnityMainThreadDispatcher