Access guide (UE4)

Overview

WeTest APM is a monitoring tool designed for the external network operation performance of games. It can collect FPS, CPU, GPU, PSS and traffic data of players during the game, and support the upload of customized data. The backend of WeTest APM classifies, collects, and analyzes the data, which can display the data according to the four dimensions of time, version, model and scene, and effectively monitor the performance status of the external network version of the game.
WeTest APM adopts the “cloud control” mechanism to support the “Gray scale” and “Filter” policy sets to control the data collection behavior of WeTest APM. The gray scale control supports the four strategies of probability, mobile phone brand, mobile phone manufacturer and IP address. The filter mechanism supports the five strategies of APM version, game version, mobile phone chip architecture, mobile phone manufacturer, and mobile phone brand.

Access Instruction

Initialization (required)
To initialize the TAPM via the InitContext interface, you need to pass in the applied GCloud GameId which is usually an integer obtained through tea.oa.com.

User mark (required)

Set the user ID through the SetUserId interface. After setting, you can use the user ID to view the performance status of a single user on the APM web page.

Frame rate report (required)

The frame rate is reported by calling PostFrame (float deltatime) in TICK. When no scene is marked, the frame reported by PostFrame is automatically discarded.

Scenario (level) loading tag (required)

The scene in TApm is only a logical mark, and has no corresponding relationship with the specific flow level or the loading or unloading of the permanent level. Therefore, MarkLevelLoad can be called multiple times in a physical level to perform logical markup, and the parameter of the image quality can be imported when marking. The default is 0. If the image quality parameter is set, the data statistics of the APM backend will be graded by the uploaded image quality. Otherwise, the APM internal grading standard is adopted by default. The second parameter in MarkLevelLoad has been deprecated in version 3.0, but the interface is still reserved for avoiding compilation problems. It is recommended that you use the SetQuality interface for image quality settings.

TApmHelper::MarkLoadlevel(“LevelName”,)
TApmHelper::LoadStreamLevel(this, LevelToLoad, true, true, LatentInfo);
End of scene loading (required)
After the scene is loaded, the loading time of the scene is calculated by calling TApmHelper::MarkLoadlevelCompleted().

Note: Calling this interface multiple times in the same scene is invalid and will only be executed once.

Scene End Mark (required)

The end of the scene is marked by the TApmHelper::MarkLevelFin() function (not necessary). If the scene is not terminated by calling the TApmHelper::MarkLevelFin() function, when TApmHelper::MarkLoadlevel(“LevelName”) is called for the next time, the time will be adopted as the end time by the entire scene.

Note: TApm will only collect data after the start of MarkLoadlevel and end the collection of data after MarkLevelFin.

Network delay (required)

The network delay is calculated by the TApmHelper::PostNTL (latency) function, which can be called in a thread that calculates the network delay separately.

Labels (optional)

In a large logical scene (from MarkLoadlevel to MarkLevelFin is a logical scene), because the resources or effects that need to be rendered at different stages in the scene are inconsistent, it is necessary to highlight a certain segment or multiple regions in the logical scene. This is the reason for adding the BeginTag marking.
The TApmHelper::BeginTag (“TagName”) function is used to indicate the beginning of a tag. The tag and the scene are dependent, meaning that if there is no MarkLoadlevel for marking, the BeginTag is invalid, and the BeginTag inherits the image quality in the MarkLoadlevel.
End the current tag with TApmHelper::EndTag(). If EndTag is not called, then a EndTag tag will be automatically inserted by default in MarkLevelFin.

Note: The tag is only used to highlight a certain area of the logical scene (level). You cannot use BeginTag to make a simple substitution for MarkLoadlevel.

Cloud control model classification interface (optional)

The SDK provides an interface for cloud control model classification. This interface can dynamically classify the machine according to the relevant configuration of the server. The return value varies with the return value
Android
On the android platform, this interface can set a white list according to the GPU model, SoC model, and manufacturer, and can classify according to model resolution, memory, CPU frequency, CPU core count, and GPU performance. If 0 is returned, it means that an error has occurred. This will only be returned if the file parsing fails.
When packaging the Android platform, please put the configuration file of the default cloud control model classification in the following path: TApm\Source\APMSDKLib\Android\assets; if there isn’t an assets folder, you need to create one and name the default configuration file QCC_gcloudid. For example: QCC_321345678. The return through the GetDeviceByQcc interface (the parameter is a configuration field in the array of configureList configuration fields in the configuration file and GPU Family) will preferentially parse the configuration file during the last game and return. If there is no latest configuration file obtained from the server, the default configuration file is used. And each time the latest configuration file is pulled through the network, the local default configuration file will be refreshed. The process of pulling the configuration file is an asynchronous behavior, which is generated in the call to GetDeviceLevelByQcc and will only occur once each time the game is started. The cloud control model interface also provides multi-version compatibility, as long as the version field is specified in the configuration file.

**Note: For a version earlier than GCloudUE4_2.0.8 (including), you need to manually add the following line to the node in the TApm\Source\TApm\TApm_APL.xml file:
iOS
On the IOS platform, files can be matched according to the model name and processor name. The environment is prepared as follows:

Name the default configuration file tapm_qcc_ios_default and create a new folder under the project directory Content, such as tapmdir
Put the model configuration file into the folder, such as: ProjRootDir/Content/tapmdir/tapm_qcc_ios_default
Search for Additional Non-Asset Directories To Copy in the UE4 Editor settings. Click to add the new folder tapmdir
Note: You can directly reuse the existing folder of the project group. Just put the tapm_qcc_ios_default file in it
int GetDeviceLevelByQcc(const char domainName, const char filePath);
domainName represents a configuration domain, and multiple configuration domains can be defined in one configuration file (through configureList)
filePath indicates the absolute path of tapm_qcc_ios_default
、
E.g:
FString absoluteDirPath = FPaths::ProjectContentDir() + FString(TEXT(“tapmdir”));
int deviceLevel = UTApmHelper::GetDeviceLevelByQcc(“level2”,TCHAR_TO_UTF8(*absoluteDirPath));

Configuration instructions

Configuration example

{
    "version": 2, //Configure version
    "regex":1,    //Enable regex
    "configureList": ["level3", "level2"],     //configuration field list
    "level3": {
        "classLevelNum": 3,             //class number
        "classLevelValues": [2, 4, 8],      //value of each class
        "defLevel": 2,                   //default class value, which is returned when there is no match in the filter-model
        "filter-model": {
            "2": ["iPhone11,4", "iPhone XS Max, "iPhone10,6", "iPhone SE.*",
"iPhone 8 Plus","A12"],                   //model list
            "4": ["iPad6,12"],
            "8": ["iPhone3,2"]
        }
    },
    "level2": {
        "classLevelNum": 3,
         "regex":1,    
        "classLevelValues": [2, 4, 8],
        "defLevel": 4,
        "filter-model": {
            "4": ["iPhone XS Max", "iPhone XS.*", "iPhone 8.*", "iPhone9,4", "iPhone8,4"],
            "8": ["iPhone 7[A10]"],
            "2": ["iPhone3,2"]
        }
    }
}

Description of model list configuration:
The device configuration list is divided into exact matching and pattern matching, both of which are insensitive to upper and lower cases;
 1. The exact matching supports the following:
            A. Internal code such as: iPhone9, 1, iPhone5, 4
            B. Processor code: a12
            C. External code: iPhone XS Max or iPhoneXSMax or iPhone XSmax
  2. Pattern matching
  When regex is used, you can replace the configured device with the regex, eg, to match iPhone XS Max, you can configure: iphone XS.*.

Note:
Please enable regular;

Customized definition (optional)

The game side can report the definition defined by itself, and the TAPM background will perform statistical analysis according to the subdivision definition dimension. This interface can be called only once, and will be effective throughout the game. If it is called multiple times in the scene, it is subject to the most recent time static void SetQuality(int quality);

Game status event report (optional)

//Report the pullback information; distance indicates the distance of the pullback
static void PostLagStatus(float distance);
//The mark that the APP finish starting the initialization is used to count the startup time of the App.
//Start time = Timestamp of the call to MarkAppFinishLaunch - Timestamp of the call to InitContext
static void MarkAppFinishLaunch();
//Report events within the game, such as predefined, get in vehicle, get out of vehicle, weather systems, etc.
//The info parameter can add some additional information, such as vehicle information, weather system information.
//For the information uploaded through the Event interface, the APM backend will perform statistical analysis of each dimension.
static void PostEvent(int key, FString info="NA");
//Manually set the version number, ignoring the automatically obtained version number of the TAPM, which can be used to set the version number during the hot update.
static void SetVersionIden(FString versionName);
//Modify the acquisition of Pss to manual mode. By default, it is automatically collected.
static void SetPssManualMode();
//Request Pss acquisition in manual mode
static void RequestPssSample();
//Upload the player's coordinate information and orientation information, the APM background will check the performance of the uploaded coordinate points, for the low performance point, it will be drawn into the performance heat map 
//for aggregation analysis; the coordinate information is (x, y, z), the orientation information is (pitch, yaw, roll triple)
static void PostTrackState(float x, float y, float z, float pitch, float yaw, float roll);

Custom data reporting (optional)

static void PostValueF(const char* category, const char* key, float a);
//Upload floating point type data
// The same as PostValueF, but you can upload two associated values, which will be used as a double to be statistically analyzed together
static void PostValueF(const char* category, const char* key, float a, float b);
//Upload floating point type data
// The same as PostValueF, but can upload three associated values, which will be used as a triple that will be statistically analyzed together
static void PostValueF(const char* category, const char* key, float a, float b, float c);
//Upload integer type data
// Functions the same as PostValueF
static void PostValueI(const char* category, const char* key, int a);
//Upload integer type data
// Functions the same as PostValueF
static void PostValueI(const char* category, const char* key, int a, int b);
//Upload integer type data
// Functions the same as PostValueF
static void PostValueI(const char* category, const char* key, int a, int b, int c);
//Upload integer type data
// Functions the same as PostValueF
static void PostValueS(const char* category, const char* key, const char* value);
void BeginTupleWrap(FString 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 BeginTupleWrap 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).

The APM background can make aggregation and analysis according to the project requirements according to the version, scene, and model, such as maximum, minimum, sum, average, distribution, and so on.
In the PostValue series, the functions used to report multi-dimensional data can use BeginTupleWrap instead of the data uploaded by the PostValueI series function. In the background, the data will be extracted into a two-dimensional table. The table name is category, the primary key is the key, and there are values of multiple dimensions (one, two, three).

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.

Regional culling (Optional)

In MMO games, you may need to cull the data of the away-from-keyboard behavior, which can be marked with BeginExclude and EndExclude.

Conversion funnel (Optional)

PostStepEvent functions can customize the critical path conversion funnel. The funnel environment is initialized through the InitStepEventContext function, the critical path is reported through PostStepEvent, and the funnel environment is released through ReleaseStepEventContext
The TAPM background will default to single startup for the funnel aggregation. If events are to be linked in different startups, use LinkLastStepEventSession interface to set it, then TAPM background will aggregate them as multiple startups in the same session

Custom device level (Optional)

In its default setting, the TAPM background aggregates devices based on the high, middle, and low level of the TDR, but this is largely inconsistent with the model level customized by the project team. You can use SetDeviceLevel to define the model level, and the TAPM backstage will follow this to classify and aggregate the data

6. Debugging

In the Dev version, the debugging information is opened through the TApmHelper::EnableDebugMode() interface, and the game is run. The Android platform can enter the shell environment “logcat | grep xclient” to view the debug information. If you see the word “end init hawk”, it means the initialization succeeded. As shown below.

Enter the scene, operate the game, end the scene, view the debug information. If you see “file send successfully”, it means the data upload is successfully uploaded, as shown below.

The iOS platform can obtain log information by using the NSlog keyword to view the keyword “TApm_ios”.
Check the data after logging in to https://apm.wetest.net