Application Performance Monitoring-PerfSight(APM)

Access guide (Unity)

Access WeTest APM

Unzip the compressed package and copy the Plugins and WeTestAPMScripts folders under WeTestAPMPlugin to the Assets directory of the game.

Initialization (Required)

Select the first or the main scene and call the following code in any script file (recommended to select an earlier loaded script) for initialization. It is usually called in the Awake function.

void Awake()
{
…
CubeApmAgent.EnableDebugMode();//Optional, open the log during debugging.
CubeApmAgent.InitContext("apm appid");//Required. Apply for AppId in WeTest.
…
}

User Mark (Required)

APM can not only reflect the performance status of the external network, but also provide an interface for single-user performance backtracking. After setting the player ID through CubeApmAgent.SetUserId, the performance data can be viewed through the player ID on the web side, and the game performance of the player can be accurately restored. The interface can be called anywhere in the program.

Scene Start Mark (Required)

WeTest APM provides on-demand collection capabilities. By default, APM will not collect data and will only start collecting data when scene marking beings. The scene in APM is a logical representation and is not directly related to the actual physical scene. Therefore, the interface of the scene marker can be called from any position, and SetQuality is generally called before the Application.LoadLevel function in Unity.

void Awake()
{
…
CubeApmAgent.MarkLoadLevel("LevelName");
...
Application.LoadLevel("Level Name");
…
}

Scene Loading Completed (Optional)

After the scene is loaded, call the CubeAgent.MarkLoadlevelCompleted() to mark the end of the scene. Call this interface to calculate the loading time of the scene. In general, MarkLoadlevelCompleted needs to be called in the GameObject script after the scene has been loaded. Calling this interface multiple times in the same APM logic scene is invalid and will only be executed once.

End of Scene Mark (Optional)

Mark the end of the scene (not necessary) by calling the CubeApmAgent.MarkLevelFin () function. If the scene is not ended by calling the CubeApmAgent.MarkLevelFin() function, the entire scene will use the time when CubeApmAgent.MarkLoadlevel (“LevelName “) is called for the next end time, but this may have an impact on the FPS calculation of the marked interval. In order to improve the accuracy of the calculation, it is best to manually mark the end. By default, APM only collects data after the MarkLoadlevel starts, and ends the collection of data after MarkLevelFin, then transmits the data to the APM server.

Network Delay (Required)

APM itself does not provide an interface for calculating network delay. It only provides report analysis of network delay. Therefore, the specific network delay is calculated by the game client end and uploaded through the CubeApmAgent. UpdateNetLatency () interface, which can be independent of the main thread, and can be called in a coroutine.

IEnumerator updateNTL()
    {
        while (true)
        {
            //Client end calculate network delay ntl
            CubeApmAgent.UpdateNetLatency(ntl);
            yield return new WaitForSeconds(1f);
        }
 }

APM’s background analyzes the uploaded delay data in multiple dimensions such as geography, scene, and operator.

Tag (Optional)

In a logical scene of APM, because the resources or effects that need to be rendered in different stages of the scene are inconsistent, it is necessary to highlight a certain segment or multiple segments in the logical scene, which is the purpose of the BeginTag mark. The BeginTag interface is used to mark the beginning of a tag. The tag and the scene are dependent. If there is no MarkLevelLoad for marking, the BeginTag is invalid. The BeginTag inherits the image quality in MarkLevelLoad. The current tag is terminated by EndTag. If EndTag is not called, an EndTag is automatically inserted by default in the SDK. The relationship between the two is as follows.

Note: The tag is only used to mark a certain area of the logical scene. BeginLevel cannot be regarded as a simple alternative to MarkLevelLoad. The statistical analysis of the Tag will be adjusted according to actual needs.

Model Position Determination Interface (Optional)

The cloud control device level is divided into the synchronous interface and asynchronous callback interface. The network request does not occur in the synchronous interface, and the interface judges and returns the current device level according to the relevant definition in the cached cloud configuration file. If you need to use this interface, you need to place the default model position configuration in the StreamingAssets directory. When you use this interface for the first time, it uses the local configuration file, and the background thread pulls the configuration file from the cloud. When this interface is subsequently called, it returns the model file defined in the cloud configuration.
The asynchronous interface guarantees that it will turn to the server end every time when pulling the latest configuration file. After successfully pulling a file, the registered callback interface is called. If other errors occur while pulling the file, the returned model position value will be a negative number. In this case, the business side needs to do some special processes.

Global Picture Quality Setting Interface (Optional)

In order to avoid to pass in image quality parameters each time when MarkLevelLoad is called (the second parameter of the interface, the default is 0), SetQuality is provided for global image quality management. This interface can be called from any position, if the player in the game sets the image quality by this interface.

Target Frame Rate Setting Interface (Optional)

In order to distinguish various high frame rate modes and improve the accuracy of APM background classification statistics, the SetTargetFrameRate interface is provided to set the target frame rate, such as 30, 40, 50 or 60. The background of APM will perform corresponding classification statistics according to the target frame rate.

Regional Setting Interface (Optional)

In order to distinguish and gather statistics on the performance of games in different regions, the SetLocale interface is provided for marking regions, and the APM background will perform corresponding classification statistics according to regions.

Custom Event Report (Optional)

In order to standardize the uploading of custom data and the analysis of the background, the interfaces for custom data upload in this version are all discarded. Please use PostEvent instead.

Custom Setting Version Number (Optional)

In order to solve the problem of the version number of a hot update, the version number can be set autonomously through the SetVersionIden interface, and the APM background will use this version number and the version number obtained from the Android layer to form a new version number.

Reporting of Custom Data (Optional)

void PostValueF(string catgory, string key, float a);
void PostValueF(string catgory, string key, float a, float b);
void PostValueF(string catgory, string key, float a, float b, float c);
void PostValueI(string catgory, string key, int a);
void PostValueI(string catgory, string key, int a, int b);
void PostValueI(string catgory, string key, int a, int b, int c);
void PostValueS(string catgory, string key, string value);
void BeginTupleWrap(string key);
void EndTupleWrap();

The PostValue series is used to report custom data. The APM background deals with data that belongs to the same Category, and the Key will be aggregated and analyzed. For the timeout function PostValueF (“FuntionTime”, “Update”, 0.33f), “FuntionTime” indicates the category. “Update” indicates a specific Key value, and 0.33 indicates a specific function time-consuming value.
BeginTupleWrap and EndTupleWrap are used for the definition of structured data, which provides powerful extensions for custom data, providing a composite key-value and multi-dimensional data analysis capabilities. The data uploaded by BeginTupleWrap is abstracted into a two-dimensional table in the background. The table name is TupleName, and the BeginValue and EndTupleWrap need to specify the corresponding key value and data value through the PostValue series function. The category is the primary key of the TupleKeyIden key. The key for TupleValueIden is defined as a normal column, such as:

//Start uploading a structure, the name of the structure is FuntionCostAnalyse
BeginTupleWrap("FuntionCostAnalyse") 
//Indicate this is a key value through TUPLE_KEY; the key name is "TupleKeyIden", and the corresponding value is "ModuleA".
PostValueS(TUPLE_KEY, "ModuleName", "ModuleA");
//It is indicated by TUPLE_KEY that this is a key value; the key name is "FunctionName", and the corresponding value is "Update".
PostValueS(TUPLE_KEY, "FunctionName", "Update");
//Ordinary column
PostValueF(TUPLE_VALUE, "SelfCost", 0.33f);
PostValueF(TUPLE_VALUE, "childrenCost", 0.16f);
EndTupleWrap()

It abstracts a model of a two-dimensional table in the APM background:
The primary key is defined as PrimaryKey(ModuleName, FunctionName).

Note: The PostValue series functions in BeginTupleWrap and EndTupleWrap, its category must be UPLE_KEY or a constant value defined by TUPLE_VALUE, otherwise the background will not do the parse.

Area Exclusion

In MMO games, it may be necessary to exclude the data of hang-up behavior, which can be marked with BeginExclude and EndExclude.

Customize Model Tiers

By default, the APM background will perform statistical analysis on the data based on the TDR model level, but the TDR model level may be very different from the project team’s own model level. Therefore, the project team can use SetDeviceLevel to report Its own model gear, APM backend uses this gear as an aggregation.

Rights Profile

Since the Android SDK will access the state of the system, the following permissions need to be added to the AndroidManifest in the Android system.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Report domain name configuration
For Android and iOS, the reported domain names need to be configured separately. Andorid is configured in the top-level AndroidManifest of the project, and iOS needs to be configured in the plist. Regarding the configuration of AppID, you need to apply to WeTest separately.

//Android：<application>The following configuration is added to the node
<meta-data android:name="GCloud.GCloud.GameId" android:value="\ XX" />
<meta-data android:name="GCloud.GCloud.GameKey" android:value="XX" />
<meta-data android:name="GCloud.TDM.Test" android:value="false" />
<meta-data android:name="GCloud.TDM.Abroad" android:value="true" />
<meta-data android:name="GCloud.TDM.TGEMIT_ROUTER_ADDRESS_FORMAL" android:value="https://sg.tdatamaster.com:8013/tdm/v1/route" />
//iOS plist Add the following configuration
<key>TDM</key>
      <dict>
          <key>AppId</key>
          <string>XX</string>
          <key>TGEMIT_ROUTER_ADDRESS_FORMAL</key>
          <string>https://sg.tdatamaster.com:8013/tdm/v1/route</string>
      </dict>

Debug

In the Dev version, open the debugging information through the CubeApmAgent.EnableDebugMode() interface, run the game, check whether the access is successful through Android logcat, enter the shell environment through adb shell, enter “logcat | grep xclient” to view the debug information, if you see “ The word “init context seccessed” means that the initialization was successful, as shown below.

Enter the scene, operate the game, end the scene, and view the debug information. If there is “file send successfully”, it means that the data was uploaded successfully, as shown in the figure below.

IOS platform can view the keyword “TApm_ios” through NSlog to obtain log information.