• 1 Instructions for use
  • 2 CrashSight component download
  • 3 CrashSight integration
  • 4 CrashSight reporting data fields
  • 5 Interfaces
    • 5.1 Error Reporting
    • 5.2 Setting callbacks
    • 5.3 Callback functions
    • 5.4 Custom Interface Log
    • 5.5 Custom KV
    • 5.6 Turn off VEH exceptions
    • 5.7 Enabling additional exception catching
    • 5.8 Custom file data
    • 5.9 Proactive reporting of crashes
    • 5.10 Specify the log directory
    • 5.11 Add error code
    • 5.12 Proactive reporting of dump
    • 5.13 Set User Id
    • 5.14 Report the dump file under the specified path
  • 6 Reference Code
  • 7 Functional test verification
  • 8 Testing CrashSight
  • 9 Upload symbol table
  • 10 View dll version
  • 11 Appendix

CrashSight Windows SDK

This article is a detailed document introducing the use of the PC SDK, containing a basic integration process and an advanced introduction to the use of the interface.
If you want to quickly integrate and verify the platform and SDK functionality, it is recommended to check the "Tutorial" in the project menu. The initialization code for this project has been generated by project specific information (platform, engine, domestic/overseas, AppID) in the guide, which can be copied and used directly. The following figure shows:

Project creation: External projects support self-service project creation, but there is a free trial period. For internal projects, contact "CrashSight Assistant" on corporate WeChat to open them.

1 Instructions for use

When integrating to CrashSight SDK PC version, the game client needs to load the exception catching dll by itself and pass in the user id and game version parameters. The following table lists the web addresses and reporting addresses of domestic and overseas services. Users can choose qq login or enterprise WeChat login:

Server TypeWebsite URLUpload URL(used in config file)
Local Serverhttps://crashsight.qq.compc.crashsight.qq.com
International Serverhttps://crashsight.wetest.netpc.crashsight.wetest.net

PS: The international version and the local version are exactly the same, you only need to modify the different reporting address to report to the specified region (note that the corresponding appid and key also need to do the corresponding changes, otherwise the server will reject)

2 CrashSight component download

The new version of CrashSight mainly provides 64-bit version, compared with 32-bit version and 64-bit version, except for different file names, the functions and usage are the same. The 64-bit TQM client version currently available includes three files:

File namePlacementFunction description
CrashSight64.dllis placed in the same directory as the game process exeand is responsible for collecting Crash information
TQM64 folderin the same directory as the game process exeresponsible for uploading Crash information
GameBabyConfig64.datin the same directory as the game process exeresponsible for providing configuration information

Take a PC game as an example, the relative relationship between file locations is as follows (in the path of the packaged file _Data\Plugins\x86_64):

3 CrashSight integration

After successfully creating a project in the platform, you can download the corresponding SDK from the "Tutorial" in the sidebar, as shown in the figure below:

As this SDK adopts the way of loading dll directly from the client, the specific integration is as follows:

  1. Login to the web side and register the project, select PC as the project type, the appid (e.g. 0620edc732) and app-key (e.g. 3edb3c5f-eca4-4033-ba60-5993452dff397, the key needs to be kept secret) will be generated after successful registration

  2. Put the provided files to the specified location according to the instructions, the client will load the CrashSight64.dll in the same level directory after startup

  3. C++ through HINSTANCE dllDemo = LoadLibraryA("CrashSight64.dll"); load the dll, other languages use the language corresponding to the dll loading method can be.

  4. Declare the export function (6. Reference code) typedef void(*CS_InitContext)(const char* id, const char* version, const char* key). and call this function to pass the user account to TQM with the following parameter descriptions:

parameterstypedescription
userIdconst char*The user's id can be qq or railid,recommended to use const char
versionconst char*The current version of the game, e.g. "3.1.0.13"
keyconst char*The string generated when registering the project, used for encryption, such as: "3edb3c5f-eca4-4033-ba60-59947eb3f397"

  1. Configure GameBabyConfig64.dat (similar to xml format)

    After the project is packaged, create a TQM64/dump directory and GameBabyConfig64.dat file in the same level directory as CrashSight64.dll.

    There are three parameters to be updated in the GameBabyConfig64.dat file:

    1)GameName

    2)Reported URL

    3)APPID

<GameBabyConfig __version="1">
	<GameName>Test-Game.exe</GameName>  
	<LobbyName></LobbyName>
	<IgnoreDllCnt>2</IgnoreDllCnt> 
	<IgnoreDlls>TenSLX.dll</IgnoreDlls>
	<IgnoreDlls>Tensafe.dll</IgnoreDlls> 
	<AppId>0620edc732</AppId>    
	<DomainUrl>pc.crashsight.qq.com</DomainUrl> 
</GameBabyConfig>
  1. When the client configuration is finished, start the game normally and find that there is CrashSight64.dll in the game process, which means that CrashSight is loaded and started successfully.

4 CrashSight reporting data fields

After the game client loads the dll and calls the export function:

  1. The dll will read the domain name in the configuration file to report networking data.
  2. It is used to report the minidmp generated by the dll to the server when the dll catches a crash exception.

The current data fields reported by CrashSight are as follows:

FieldDescription
userIduser id
appIdproject's registration id
MacMac address
osNameoperating system name
displayCardDisplay card name
CpuCpu type
phyMemAllMachine memory
osBitmachine bit count
resolutionresolution
pidNameprocess name
bootTimeboot time
IpIp address

5 Interfaces

5.1 Error Reporting

typedef void(*CS_ReportException)(int type, const char* name, const char* message, const char* stackTrace, const char * extras);
CS_ReportException theReportException = (CS_ReportException)GetProcAddress(dllDemo, "CS_ReportException");

The specific location of each of these parameters displayed on the page is shown in the figure. Custom logs are required to be written in CSLog/customLog.txt in the same directory of dll, please clean up the content in the file every time you start, otherwise it can't be uploaded properly. The maximum size of the log upload is 2M, and the exceeding part will be truncated. expName/expMessage is a brief description of the problem, please limit it to 128 bytes or less. (Specially, if you use UE engine and transcode by UTF8, please limit it to 96 characters as much as possible) stackTrace is the main content part of current error, please limit it to 2M only. extras field is reserved field, just fill in "" currently.

5.2 Setting callbacks

	typedef void(*CS_SetCrashCallback)(CrashCallbackFuncPtr callback);
	CS_SetCrashCallback theSetCrashCallback = (CS_SetCrashCallback)GetProcAddress(dllDemo, "CS_SetCrashCallback");

The CrashCallbackFuncPtr callback can be any of the user's own function implementations, as long as the parameters match, the declaration cycle always exists, and it will not become a null pointer.

5.3 Callback functions

	typedef void(*CrashCallbackFuncPtr)(int type, const char* guid);

type is the type of callback, currently there are only crash callbacks, callback type are 1. Further optimization will be done later depending on the specific requirements. guid is a unique identifier string of length 64, each report has a separate string, which can be obtained by splicing https://{website_domain}/crash-reporting/client-report-id/{APP_ID}/{GID}?pid={platform_ID} to get the relevant reported access URL. The CrashCallbackFuncPtr callback can be any user's own function implementation, as long as the parameters match, the declaration cycle always exists, and it will not become a null pointer. Note here that the callback function cannot be a non-static function of a class member, because the default first argument of a non-static function of a class member is 'this'

5.4 Custom Interface Log

enum LogSeverity {
  Log,
  LogDebug,
  LogInfo,
  LogWarning,
  LogAssert,
  LogError,
  LogException
};
typedef void(*CS_PrintLog)(LogSeverity level, const char* tag, const char *format, ...);
CS_PrintLog thePrintLog = (CS_PrintLog)GetProcAddress(dllDemo, "CS_PrintLog");

This function can be called to write a log to the SDK during the program runtime, and this log will be reported together with the error report and crash report. The log content is a 1M circular queue.

5.5 Custom KV

typedef void(*CS_SetUserValue)(const char* key, const char* value);
CS_SetUserValue theSetUserValue = (CS_SetUserValue)GetProcAddress(dllDemo, "CS_SetUserValue");

This function can be called to write custom KV to SDK during program operation to save some key properties, which will be reported together with the error report and crash report. It is recommended that the KV be set according to the specification in the custom data format documentopen in new window.

5.6 Turn off VEH exceptions

typedef void (*CS_SetVehEnable)(bool enable);
CS_SetVehEnable theSetVehEnable = (CS_SetVehEnable)GetProcAddress(dllDemo, "CS_SetVehEnable");

Set VEH exception handling state, default is on, consistent with the old version. When turned off, only unhandled exceptions are reported. This scheme optimizes the catching of some exceptions, e.g. when turned off, crashes caused by THROW are reported (when turned on, they are not), bad memory accesses that have been handled are not reported by mistake, etc. Note that since UE catches all exceptions at the engine level via __try __except (macro PLATFORM_SEH_EXCEPTIONS_DISABLED related area), there are no 'unhandled exceptions'. Therefore, do not modify this option until this catch is turned off by modifying the engine code, as this will result in a large number of exceptions not being reported.

5.7 Enabling additional exception catching

typedef void (*CS_SetExtraHandler)(bool extra_handle_enable);
CS_SetExtraHandler theSetExtraHandler = (CS_SetExtraHandler)GetProcAddress(dllDemo, "CS_SetExtraHandler");

Set additional exception handling mechanism, default is off, in line with the old version. When turned on, it can catch crashes caused by illegal arguments thrown by safety functions like strcpy_s and, crashes caused by false function call purecall errors.

5.8 Custom file data

Crashes/errors carry the contents of a file in the specified directory, usually the file contents are logs, so this feature is also called custom file logging. Unlike the interface log, the file log reads the specified file and does not restrict the content of the written file or the method. This feature does not need to be actively enabled, as long as in the corresponding reporting trigger is, the specified directory has files will be reported.

Specifically:

On crash, it will report . \TQM\CSLog\customLog.txt

In case of error, it will report . \CSLog\customLog.txt. Here, the directory where the dll is located is the base directory.

5.9 Proactive reporting of crashes

This function can be called in some cases where active dump reporting is expected. It is mainly used to report UE Fatal errors.

typedef void (*CS_ReportCrash)();
CS_ReportCrash theReportCrash = (CS_ReportCrash)GetProcAddress(dllDemo, "CS_ReportCrash");

FCoreDelegates::OnShutdownAfterError.AddStatic(cs_report_crash);

5.10 Specify the log directory

Modify the default log file directory to take effect in pure mode only.

typedef int (*CS_SetCustomLogDir)(const char* log_path);
CS_SetCustomLogDir theSetCustomLogDir = (CS_SetCustomLogDir)GetProcAddress(dllDemo, "CS_SetCustomLogDir");

5.11 Add error code

The error code of the specified RaiseException will be considered as a crash and reported (generally, it is not recommended to modify, please make specific inquiries before modifying)

typedef int (*CS_AddValidExpCode)(const char* log_path);
CS_AddValidExpCode theAddValidExpCode = (CS_AddValidExpCode)GetProcAddress(dllDemo, "CS_AddValidExpCode");

5.12 Proactive reporting of dump

This function can be called in some cases where active dump reporting is expected.

typedef int (*CS_ReportDump)(const char* log_path);
CS_ReportDump theReportDump = (CS_ReportDump)GetProcAddress(dllDemo, "CS_ReportDump");

5.13 Set User Id

typedef int (*CS_SetUserId)(const char* log_path);
CS_SetUserId theSetUserId = (CS_SetUserId)GetProcAddress(dllDemo, "CS_SetUserId");

5.14 Report the dump file under the specified path

typedef int (*CS_UploadGivenPathDump)(const char* log_path);
CS_UploadGivenPathDump theUploadGivenPathDump = (CS_UploadGivenPathDump)GetProcAddress(dllDemo, "CS_UploadGivenPathDump");

6 Reference Code

The C++ reference code is as follows:

typedef void(*CS_InitContext)(const char* id, const char* version, const char* key);
typedef void(*CS_ReportException)(int type, const char* name, const char* message, const char* stackTrace, const char * extras);
int main()
{
	// load dll
	HINSTANCE dllDemo = LoadLibraryA("CrashSight64.dll");
	// Perform initialization
	if (dllDemo)
	{
		CS_InitContext theInitContext = NULL;
		theInitContext = (CS_InitContext)GetProcAddress(dllDemo, "CS_InitContext");
		if (theInitContext != NULL)
		{
			theInitContext("userid", "version", "key");
		}
	}
	// Report a custom error
	if (dllDemo)
	{
		CS_ReportException theReportException = NULL;
		theReportException = (CS_ReportException)GetProcAddress(dllDemo, "CS_ReportException");
		if (theReportException != NULL)
		{
			int type = 1;
			theReportException(type, "exp name", "exp message", "stack", "extras");
		}
	}
	return 1;
}

The C# reference code is as follows:

Function Statement:
[DllImport("CrashSight64.dll")] 
static extern void CS_InitContext([MarshalAs(UnmanagedType.LPUTF8Str)]string userId, [MarshalAs(UnmanagedType.LPUTF8Str)]string version, [MarshalAs(UnmanagedType.LPUTF8Str)]string key);

[DllImport("CrashSight64.dll")] 
static extern void CS_ReportException (int type, [MarshalAs(UnmanagedType.LPUTF8Str)]string name, [MarshalAs(UnmanagedType.LPUTF8Str)]string message, [MarshalAs(UnmanagedType.LPUTF8Str)]string stackTrace, [MarshalAs(UnmanagedType.LPUTF8Str)]string extras);

Function calls:
CS_InitContext("userId", "version", "key");
CS_ReportException(1, "name", "message","stackTrace", "extras");

7 Functional test verification

Once integration is complete, be sure to verify that the results of the integration are as expected. This includes the following points.

    1. After initializing CrashSight, verify that the network is reporting properly, as follows:
       1. Initialize CrashSight.
       2. After 5 minutes, you can see the statistic value is greater than or equal to 1 in Exception Overview --> Crash Trend --> Networked Device Count on the admin page.
    2. If the game crashes, whether it can be reported correctly or not, the specific verification method is as follows:
       1. Initialize CrashSight. 2.
       2. Crash is triggered by the code int *a = NULL; a[0] = 1; inside the game. (Other similar bad memory accesses are possible)
       3. Check if a dmp file is generated under the TQM64/dump path. If not, it means the crash cannot be captured successfully, please contact CrashSight development.
       4. Check if the corresponding time point is reported in the crash analysis of the management side page. If 3 is there and 4 is not, it means that it is not successfully reported. Please check the APP ID configuration (both profiles should be correct) and APP KEY configuration, whether they correspond and are the same as in the application settings. If the configuration is correct and still cannot be reported, please contact CrashSight development.
    3. Whether the game error occurs and can be reported correctly (optional), the specific verification method is as follows:
       1. Initialize CrashSight.
       2. Trigger CS_ReportException() in the game
       3. Check whether the error is reported at the corresponding time point in the error analysis on the management page. If not, it means that it is not successfully reported. Please check the APP ID configuration (both configuration files should be correct) and APP KEY configuration, whether they are corresponding and the same as in the application settings. If the configuration is correct and still cannot be reported, please contact CrashSight development.
    4. whether the custom logs can be reported correctly if the game has errors; (optional)
    5. the version number of the crash reported, whether the user name is the same as the setting;
    6. whether the version number, user name reported by the error is consistent with the setting;

8 Testing CrashSight

After successful integration, the game will load the dll and pull up the exe process after normal startup. crashSight will upload the networking information immediately after startup, and the web side can directly view the reported networking data, which means the CrashSight networking data reporting function. If the game process crashes in some way, the dump information of the project can be viewed in the exception list under the project on the CrashSight website, which means that the exception catching function of CrashSight is normal.

The performance of the client before and after integrating CrashSight is tested, and the impact of CrashSight on the performance of the game is no more than 1%.

When loading the dll, we need to judge whether the dll is loaded successfully or not. Remove the TQM dll and folder directly after integrating, it will not have any additional impact on the game.

9 Upload symbol table

The above describes the SDK integration, crash reporting and verification, but to see the readable restore stack on the page, you also need to upload the corresponding symbol table. symbol table for PC, pdb or exe+dll file, can be uploaded directly on the web page (exception configuration -> symbol table management). A separate symbol table upload tool will also be provided later. At least all modules involved in the crash stack inside dump should be included.

10 View dll version

In some cases, developers may need to check the version of CrashSight64.dll. The dll version can be found in Properties->Details, as shown in the picture below:

11 Appendix

1. CrashSight Support Crash List. [Microsoft crash definition].(https://docs.microsoft.com/en-us/windows/win32/debug/getexceptioncode) 

#define STATUS_ACCESS_VIOLATION          ((DWORD   )0xC0000005L)    
#define STATUS_IN_PAGE_ERROR             ((DWORD   )0xC0000006L)    
#define STATUS_INVALID_HANDLE            ((DWORD   )0xC0000008L)    
#define STATUS_INVALID_PARAMETER         ((DWORD   )0xC000000DL)    
#define STATUS_NO_MEMORY                 ((DWORD   )0xC0000017L)    
#define STATUS_ILLEGAL_INSTRUCTION       ((DWORD   )0xC000001DL)    
#define STATUS_NONCONTINUABLE_EXCEPTION  ((DWORD   )0xC0000025L)    
#define STATUS_INVALID_DISPOSITION       ((DWORD   )0xC0000026L)    
#define STATUS_ARRAY_BOUNDS_EXCEEDED     ((DWORD   )0xC000008CL)    
#define STATUS_FLOAT_DENORMAL_OPERAND    ((DWORD   )0xC000008DL)    
#define STATUS_FLOAT_DIVIDE_BY_ZERO      ((DWORD   )0xC000008EL)    
#define STATUS_FLOAT_INEXACT_RESULT      ((DWORD   )0xC000008FL)    
#define STATUS_FLOAT_INVALID_OPERATION   ((DWORD   )0xC0000090L)    
#define STATUS_FLOAT_OVERFLOW            ((DWORD   )0xC0000091L)    
#define STATUS_FLOAT_STACK_CHECK         ((DWORD   )0xC0000092L)    
#define STATUS_FLOAT_UNDERFLOW           ((DWORD   )0xC0000093L)    
#define STATUS_INTEGER_DIVIDE_BY_ZERO    ((DWORD   )0xC0000094L)    
#define STATUS_INTEGER_OVERFLOW          ((DWORD   )0xC0000095L)    
#define STATUS_PRIVILEGED_INSTRUCTION    ((DWORD   )0xC0000096L)    
#define STATUS_STACK_OVERFLOW            ((DWORD   )0xC00000FDL)    
#define STATUS_DLL_NOT_FOUND             ((DWORD   )0xC0000135L)    
#define STATUS_ORDINAL_NOT_FOUND         ((DWORD   )0xC0000138L)    
#define STATUS_ENTRYPOINT_NOT_FOUND      ((DWORD   )0xC0000139L)    
#define STATUS_CONTROL_C_EXIT            ((DWORD   )0xC000013AL)    
#define STATUS_DLL_INIT_FAILED           ((DWORD   )0xC0000142L)    
#define STATUS_FLOAT_MULTIPLE_FAULTS     ((DWORD   )0xC00002B4L)    
#define STATUS_FLOAT_MULTIPLE_TRAPS      ((DWORD   )0xC00002B5L)    
#define STATUS_REG_NAT_CONSUMPTION       ((DWORD   )0xC00002C9L)    
#define STATUS_HEAP_CORRUPTION           ((DWORD   )0xC0000374L)    
#define STATUS_STACK_BUFFER_OVERRUN      ((DWORD   )0xC0000409L)    
#define STATUS_INVALID_CRUNTIME_PARAMETER ((DWORD   )0xC0000417L)    
#define STATUS_ASSERTION_FAILURE         ((DWORD   )0xC0000420L)    
#define STATUS_ENCLAVE_VIOLATION         ((DWORD   )0xC00004A2L)    
#if defined(STATUS_SUCCESS) || (_WIN32_WINNT > 0x0500) || (_WIN32_FUSION >= 0x0100) 
#define STATUS_SXS_EARLY_DEACTIVATION    ((DWORD   )0xC015000FL)    
#define STATUS_SXS_INVALID_DEACTIVATION  ((DWORD   )0xC0150010L)
Last Updated: