DebugClient
provides features to assist with debugging when using NEX during application development.
If you only want to check on the frequency of access, build and use the Debug
sample.
Warning
The package does not contain the release build version of the DebugClient
library. For this reason, we recommend that you do not incorporate DebugClient
in the target application. Rather, we recommend using the Debug
sample or creating a dedicated application based on the sample.
Note
In the future, the management of changes to overall game server settings will be provided in the form of a Web system. At that time, the API for changing settings will be deleted from DebugClient
.
The calls to API functions that are issued during communication with the game server can be recorded, and later that log can be retrieved and confirmed to check the behavior of the application. This information can also be used to confirm that the application follows the guidelines Restrict Access to Game Server and Prohibition Against Periodic Access to Game Server.
The following information about each API call is recorded.
PrincipalID
of the client that called the API.The recorded API name is the name as it is used inside the library, and this differs from the API name that gets called from the application. To see the correspondence between recorded API names and the API names as called from the application, see Section 10.4 API Name Correspondence Tables. Note that APIs that are called automatically inside the library at login and at NAT traversals are also recorded to the log. (These APIs are exempt from the guideline about access restrictions.)
The DebugClient
initialization and finalization processes are the same as the processes performed for service clients when matchmaking.
The feature to record API calls is normally turned off. To enable it you need to use the DebugClient::EnableApiRecorder
function.
Code 10.1. Enabling or Disabling the Feature to Record API Calls
// Enable recording.
qBool EnableApiRecorder(ProtocolCallContext* pContext);
// Disable recording.
qBool DisableApiRecorder(ProtocolCallContext* pContext);
When asynchronous processing of the DebugClient::EnableApiRecorder
function succeeds, the feature to record API calls becomes enabled. After the feature has been enabled, a log of as many as 1000 API calls will be stored in the game server, using the first-in first-out method. Each log is retained for a maximum of one hour.
The recording feature is disabled when the DebugClient::DisableApiRecorder
function is called, or if more than one hour has passed with no API calls to the server. When the feature is disabled, the log maintained up to that time is also invalidated.
Note that enabling and disabling this feature configures the overall setting for the game server, so the situation changes depending on the operations of other clients.
To retrieve the log of recorded API calls, use the DebugClient::GetApiCalls
function.
Code 10.2. Retrieving the API Call Log
// Get the recording.
qBool GetApiCalls(ProtocolCallContext *pContext,
qList<ApiCallData>* pApiCallDatas,
qList<PrincipalID>& principalIds,
DateTime sinceTime = DateTime::Never,
DateTime untilTime = DateTime::Never
);
You can get the API call log for all clients by passing an empty list to principalIds. To get the log for only a certain client, specify the PrincipalID
you want to get.
To get the log for a specific period of time, specify sinceTime
and untilTime
. Note that exact seconds for sinceTime
and untilTime
are not included in the log to get. For example, if you specified 2012/4/27 13:00:30 for sinceTime
, you would get log entries starting from 2012/4/27 13:00:31. If you specify DateTime::Never
for sinceTime
, you get all of the log stored in the game server (up until the limit set by untilTime
). If you specify DateTime::Never
for untilTime
, you get the log of API calls up to the current time (truncating the milliseconds).
When asynchronous processing succeeds, the log gets set in pApiCallDatas. The log is sorted according to the order in which calls were made.
Use the DebugClient::GetApiCallSummary
function to total the function calls in the call log and check whether that value exceeds the guideline function call frequency.
There are guidelines to limit the frequency of function calls to reduce the NEX load on the game server. There is a unique standard call frequency for each API in the guidelines, and calls in excess of the standard call frequency are restricted. For more information, see the NEX topic in CTR Guidelines: Internet Communication.
The guideline call frequencies are described in terms of a "standard period" and "standard number of calls." For example, "function A can be called up to Y times (standard number of calls) over X seconds (standard period)."
Note
There are also services, such as the ranking service, for which function calls are restricted not on the basis of the call frequencies of individual functions but rather on the basis of the total number of function calls for the whole service.
By specifying a PrincipalID
for the DebugClient::GetApiCallSummary
function, you can get an API call summary for that PrincipalID
, and the function also determines whether any of those values exceed the guideline function call frequencies.
Code 10.3. Getting an API Call Summary
// Get the recording.
qBool GetApiCallSummary(ProtocolCallContext *pContext,
qList<ApiCallSummary>* pApiCallSummaryList,
PrincipalID principalId,
DateTime sinceTime = DateTime::Never,
DateTime untilTime = DateTime::Never,
qBool isLimitOverOnly = true
);
Specify the PrincipalID
for which to get the API call summary as an argument for the DebugClient::GetApiCallSummary
function. The API call summary retrieved from the server is in a list indicated by the pApiCallSummaryList
pointer.
To limit the time period in the API call summary, specify arguments for the sinceTime
and untilTime
arguments just like when using GetApiCalls
. The sinceTime
argument specifies the start of the time period for the API call summary. If DateTime::Never
is specified for the sinceTime
argument, no specific start time is used. The untilTime
argument specifies the end of the time period for the API call summary. If DateTime::Never
is specified for the untilTime
argument, API calls are totaled to the present time on the server (truncating milliseconds) in the API call summary.
Note that exact seconds for sinceTime
and untilTime
are not included in the API call summary. For example, if you specified 2013-04-27 13:00:30 for sinceTime
, you would get an API call summary starting from 2012-4-27 13:00:31. Similarly, if you specified 2013-4-27 13:00:45 for untilTime
, the API call summary would end at 2013-4-27 13:00:44.
If true
(the default value) is specified for the isLimitOverOnly
argument, and the function only returns results for APIs for which the call frequencies exceeded the standard guideline values. If false
is specified, you can also get summary results for APIs for which the call frequencies did not exceed the standard guideline values.
The API call summary (the ApiCallSummary
class) includes the following information.
Figure 10.1. Information Included in the API Call Summary
The function names are listed in the format in which they are recorded on the server, such as MatchmakeExtensionProtocol::BrowseMatchmakeSession
. For services, such as the ranking service, for which function calls are limited on the basis of the overall number of API calls, the function names are listed with a regular expression such as RankingProtocol::*
.
Use the ApiCallSummary::GetPeriod
and ApiCallSummary::GetLimit
functions to get the standard time period and standard number of function calls, respectively, used for determining the recommended call frequency for a particular API.
The ApiCallSummary
class also stores the times of the first API calls that exceeded the guideline call frequency in chronological order, in addition to the total of number of calls to those functions over the time period as reference information. To get the start time of the period during which APIs were called in excess of the guideline frequency, use the ApiCallSummary::GetCallStartTime
function. To get the number of API calls over a standard time period starting from that time, use the ApiCallSummary::GetCount
function.
Note
If false
is specified for the isLimitOverOnly
argument when getting an API call summary with GetApiCallSummary
, the function also totals the number of function calls of functions that were not called in excess of the guideline call frequency. For functions that were not called in excess of the guideline call frequency, the ApiCallSummary::ApiCallSummaryResult
function returns DebugConstants::ApiCallSummaryResult_Normal
. In this case, the ApiCallSummary::GetCallStartTime
and ApiCallSummary::GetCount
functions return the start time and number of functions calls, respectively, for the period over which the maximum number of function calls were made, rather than a period during which the guideline function call frequency values were exceeded.
Recorded API Name | API Name in Library |
---|---|
SecureConnectionInternalProtocol:: |
NgsFacade:: |
Recorded API Name | API Name in Library |
---|---|
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchMakingProtocolServer:: |
MatchMakingClient:: |
MatchMakingProtocolServer:: |
MatchMakingClient:: |
MatchMakingProtocolServer:: |
MatchMakingClient:: |
MatchMakingProtocolServer:: |
MatchMakingClient:: |
MatchMakingProtocolServer:: |
MatchMakingClient:: |
MatchMakingProtocolServer:: |
MatchMakingClient:: |
MatchMakingExtProtocolServer:: |
MatchMakingClient:: |
MatchMakingClient:: |
MatchMakingClient:: |
MatchMakingClient:: |
MatchMakingClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
MatchmakeExtensionProtocol:: |
MatchmakeExtensionClient:: |
Recorded API Name | API Name in Library |
---|---|
MessagingProtocolServer:: |
MessagingClient:: |
Recorded API Name | API Name in Library |
---|---|
UtilityProtocol:: |
UtilityClient:: |
Recorded API Name | API Name in Library |
---|---|
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
RankingProtocol:: |
RankingClient:: |
Recorded API Name | API Name in Library |
---|---|
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
DataStoreProtocol:: |
DataStoreClient:: |
※1 Notes: Called once every time the DataStoreClient::PostObject
function is called.
Called once every time the DataStoreClient::UpdateObject
function is called.
Recorded API Name | API Name in Library |
---|---|
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
SubscriberProtocol:: |
SubscriberClient:: |
Recorded API Name | API Name in Library |
---|---|
DebugProtocol:: |
DebugClient:: |
DebugProtocol:: |
DebugClient:: |
DebugProtocol:: |
DebugClient:: |
DebugProtocol:: |
DebugClient:: |
DebugProtocol:: |
DebugClient:: |
DebugProtocol:: |
DebugClient:: |
DebugProtocol:: |
DebugClient:: |
Function Name Called on the Server | Call Timing |
---|---|
SecureConnectionInternalProtocol:: |
While logging in |
SecureConnectionInternalProtocol:: |
While logging in |
SecureConnectionInternalProtocol:: |
When using NAT traversal |
SecureConnectionInternalProtocol:: |
When using NAT traversal |
NATTraversalReportInternalProtocol:: |
When using NAT traversal |
NATTraversalReportInternalProtocol:: |
When using NAT traversal |
NATTraversalReportInternalProtocol:: |
At the first ConnectivityManager::StartNatSession after logging in |
The operations of the game server can be changed for debugging purposes. Use the MatchmakeExtensionClient::AutoMatchmake
function to change the setting that determines whether to exclude previously-joined gatherings as possible matchmaking sessions to join.
In the default setting, the game server excludes the past three gatherings that were joined with the MatchmakeExtensionClient::AutoMatchmake
function. When debugging the application, use the DebugClient::SetExcludeJoinedMatchmakeSession
function to change the settings if you want to join the same gatherings as with the MatchmakeExtensionClient::AutoMatchmake
function.
The DebugClient::SetExcludeJoinedMatchmakeSession
function configures the setting for the overall game server. Note that when you change the setting, it can affect other developers connected to the same game server. Also note that the setting cannot be changed on the production server. (The setting is always configured to exclude gatherings joined in the past.) For this reason, do not develop applications that assume that the setting to exclude past-joined gatherings will be off.
CONFIDENTIAL