10. Debugging Helpers

10.1. Introduction

DebugClient provides features to assist with debugging when using NEX during application development.

  • Features to record and retrieve the API function calls that are issued during communication with the game server. (See Section 10.2.)
  • A feature for totaling the number of function calls recorded in a call log and checking whether that value exceeds the guideline function call frequency. (See Section 10.3.)
  • Features to change the functionality of the game server. (See Section 10.5.)

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.

10.2. Recording API Calls Issued During Communication With the Game Server

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.

  • The PrincipalID of the client that called the API.
  • The name of the called API.
  • The time called (in UTC format).

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.)

10.2.1. Service Client Initializing and Finalizing

The DebugClient initialization and finalization processes are the same as the processes performed for service clients when matchmaking.

10.2.2. Enabling or Disabling the Feature to Record API Calls

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.

10.2.3. Retrieving the API Call Log

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.

10.3. Totaling API Calls in the Call Log

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.

10.3.1. The API Call Frequency Limit

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.

10.3.2. Getting an API Call Summary

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.

10.3.3. Checking an API Call Summary

The API call summary (the ApiCallSummary class) includes the following information.

  • Function names that indicate which APIs the call summary results are for
  • Whether the function call frequency exceeded the standard guideline value
  • The recommended call frequency (time period, number of calls)
  • The start time of the time period, and total number of function calls for functions that were called in excess of the recommended value over that time period
  • The total number of all function calls for the entire time period
_images/Fig_Debug_ApiCallSummary.png

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.

10.4. API Name Correspondence Tables

10.4.1. Facade

Table 10.1. Correspondence Table for Facade APIs
Recorded API Name API Name in Library
SecureConnectionInternalProtocol::TestConnectivity NgsFacade::TestConnectivity

10.4.2. Matchmaking

Table 10.2. Correspondence Table for Matchmaking APIs
Recorded API Name API Name in Library
MatchmakeExtensionProtocol::GetFriendNotificationData MatchmakeExtensionClient::GetFriendNotificationData
MatchmakeExtensionProtocol::GetlstFriendNotificationData MatchmakeExtensionClient::GetFriendNotificationData
MatchmakeExtensionProtocol::UpdateNotificationData MatchmakeExtensionClient::UpdateNotificationData
MatchmakeExtensionProtocol::AutoMatchmake_Postpone MatchmakeExtensionClient::AutoMatchmake
MatchmakeExtensionProtocol::AutoMatchmakeWithSearchCriteria_Postpone MatchmakeExtensionClient::AutoMatchmake
MatchmakeExtensionProtocol::AutoMatchmakeWithGatheringId_Postpone MatchmakeExtensionClient::AutoMatchmake
MatchmakeExtensionProtocol::AutoMatchmakeWithParam_Postpone MatchmakeExtensionClient::AutoMatchmake (specify AutoMatchmakeParam)
MatchmakeExtensionProtocol::BrowseMatchmakeSession MatchmakeExtensionClient::BrowseMatchmakeSession (retrieved as a GatheringHolder)
MatchmakeExtensionProtocol::BrowseMatchmakeSessionWithHostUrls MatchmakeExtensionClient::BrowseMatchmakeSession (retrieved as a GatheringHolder, host URL also retrieved)
MatchmakeExtensionProtocol::BrowseMatchmakeSessionNoHolder MatchmakeExtensionClient::BrowseMatchmakeSession (retrieved as a MatchmakeSession)
MatchmakeExtensionProtocol::BrowseMatchmakeSessionWithHostUrlsNoHolder MatchmakeExtensionClient::BrowseMatchmakeSession (retrieved as a MatchmakeSession, host URL also retrieved)
MatchmakeExtensionProtocol::CreateMatchmakeSession MatchmakeExtensionClient::CreateMatchmakeSession
MatchmakeExtensionProtocol::CreateMatchmakeSessionWithParam MatchmakeExtensionClient::CreateMatchmakeSession (specify CreateMatchmakeSessionParam)
MatchmakeExtensionProtocol::JoinMatchmakeSessionEx MatchmakeExtensionClient::JoinMatchmakeSession
MatchmakeExtensionProtocol::JoinMatchmakeSessionWithParam MatchmakeExtensionClient::JoinMatchmakeSession (specify JoinMatchmakeSessionParam)
MatchmakeExtensionProtocol::UpdateMatchmakeSession MatchmakeExtensionClient::UpdateMatchmakeSession
MatchmakeExtensionProtocol::UpdateMatchmakeSessionPart MatchmakeExtensionClient::UpdateMatchmakeSession (partial update)
MatchmakeExtensionProtocol::UpdateMatchmakeSessionAttribute MatchmakeExtensionClient::UpdateMatchmakeSessionAttribute
MatchmakeExtensionProtocol::ModifyMatchmakeSessionAttribute MatchmakeExtensionClient::ModifyMatchmakeSessionAttribute
MatchmakeExtensionProtocol::ModifyCurrentGameAttribute MatchmakeExtensionClient::ModifyMatchmakeSessionAttribute
MatchmakeExtensionProtocol::UpdateApplicationBuffer MatchmakeExtensionClient::UpdateApplicationBuffer
MatchmakeExtensionProtocol::OpenParticipation MatchmakeExtensionClient::OpenParticipation
MatchmakeExtensionProtocol::CloseParticipation MatchmakeExtensionClient::CloseParticipation
MatchmakeExtensionProtocol::GetPlayingSession MatchmakeExtensionClient::GetPlayingSession
MatchmakeExtensionProtocol::UpdateProgressScore MatchmakeExtensionClient::UpdateProgressScore
MatchmakeExtensionProtocol::DebugNotifyEvent MatchmakeExtensionClient::DebugNotifyEvent
MatchmakeExtensionProtocol::GenerateMatchmakeSessionSystemPassword MatchmakeExtensionClient::GenerateMatchmakeSessionSystemPassword
MatchmakeExtensionProtocol::ClearMatchmakeSessionSystemPassword MatchmakeExtensionClient::ClearMatchmakeSessionSystemPassword
MatchmakeExtensionProtocol::FindMatchmakeSessionByGatheringIdDetail MatchmakeExtensionClient::FindMatchmakeSessionByGatheringIdDetail
MatchMakingProtocolServer::FindByID MatchMakingClient::FindByID (batch-get)
MatchMakingProtocolServer::FindBySingleID MatchMakingClient::FindByID (id specified)
MatchMakingProtocolServer::FindByOwner MatchMakingClient::FindByOwner
MatchMakingProtocolServer::GetSessionURLs MatchMakingClient::GetSessionURLs
MatchMakingProtocolServer::GetDetailedParticipants MatchMakingClient::GetDetailedParticipants
MatchMakingProtocolServer::UpdateSessionHost MatchMakingClient::UpdateSessionHost
MatchMakingExtProtocolServer::EndParticipation MatchMakingClient::EndParticipation
MatchMakingClient::UnregisterGathering MatchMakingClient::UnregisterGathering
MatchMakingClient::MigrateGatheringOwnership MatchMakingClient::MigrateGatheringOwnership
MatchmakeExtensionProtocol::CreateCommunity MatchmakeExtensionClient::CreatePersistentGathering
MatchmakeExtensionProtocol::UpdateCommunity MatchmakeExtensionClient::UpdatePersistentGathering
MatchmakeExtensionProtocol::JoinCommunity MatchmakeExtensionClient::JoinPersistentGathering
MatchmakeExtensionProtocol::FindCommunityByGatheringId MatchmakeExtensionClient::FindPersistentGatheringByGatheringId
MatchmakeExtensionProtocol::FindOfficialCommunity MatchmakeExtensionClient::FindOfficialPersistentGathering
MatchmakeExtensionProtocol::FindCommunityByParticipant MatchmakeExtensionClient::FindPersistentGatheringByParticipant
MatchmakeExtensionProtocol::CreateCommunity MatchmakeExtensionClient::CreateCommunity
MatchmakeExtensionProtocol::UpdateCommunity MatchmakeExtensionClient::UpdateCommunity
MatchmakeExtensionProtocol::JoinCommunity MatchmakeExtensionClient::JoinCommunity
MatchmakeExtensionProtocol::FindCommunityByGatheringId MatchmakeExtensionClient::FindCommunityByGatheringId
MatchmakeExtensionProtocol::FindOfficialCommunity MatchmakeExtensionClient::FindOfficialCommunity
MatchmakeExtensionProtocol::FindCommunityByParticipant MatchmakeExtensionClient::FindCommunityByParticipant
MatchmakeExtensionProtocol::UpdatePrivacySetting MatchmakeExtensionClient::UpdatePrivacySetting
MatchmakeExtensionProtocol::GetMyBlackList MatchmakeExtensionClient::GetMyBlackList
MatchmakeExtensionProtocol::AddToBlackList MatchmakeExtensionClient::AddToBlackList
MatchmakeExtensionProtocol::RemoveFromBlackList MatchmakeExtensionClient::RemoveFromBlackList
MatchmakeExtensionProtocol::ClearMyBlackList MatchmakeExtensionClient::ClearBlackList

10.4.3. Messaging

Table 10.3. Correspondence Table for Messaging APIs
Recorded API Name API Name in Library
MessagingProtocolServer::DeliverMessage MessagingClient::SendInstant or MessagingClient::SendChat

10.4.4. Utilities

Table 10.4. Correspondence Table for Utility APIs
Recorded API Name API Name in Library
UtilityProtocol::AcquireNexUniqueId UtilityClient::AcquireNexUniqueId

10.4.5. Ranking

Table 10.5. Correspondence Table for Ranking APIs
Recorded API Name API Name in Library
RankingProtocol::UploadScore RankingClient::UploadScore
RankingProtocol::DeleteScore RankingClient::DeleteScore
RankingProtocol::DeleteAllScores RankingClient::DeleteScore
RankingProtocol::UploadCommonData RankingClient::UploadCommonData
RankingProtocol::DeleteCommonData RankingClient::DeleteCommonData
RankingProtocol::GetCommonData RankingClient::GetCommonData
RankingProtocol::ChangeAttributes RankingClient::ChangeAttributes
RankingProtocol::ChangeAllAttributes RankingClient::ChangeAttributes
RankingProtocol::GetRanking RankingClient::GetRanking
RankingProtocol::GetRankingByPIDList RankingClient::GetRankingByPIDList
RankingProtocol::GetRankingByUniqueIdList RankingClient::GetRankingByUniqueIdList
RankingProtocol::GetApproxOrder RankingClient::GetApproxOrder
RankingProtocol::GetStats RankingClient::GetStats
RankingProtocol::GetCachedTopXRanking RankingClient::GetCachedTopXRanking
RankingProtocol::GetCachedTopXRankings RankingClient::GetCachedTopXRankings

10.4.6. Data Stores

Table 10.6. Correspondence Table for Data Store APIs
Recorded API Name API Name in Library
DataStoreProtocol::PrepareGetObject DataStoreClient::GetObject
DataStoreProtocol::PostMetaBinary DataStoreClient::PostObject (when uploading only metadata)
DataStoreProtocol::PreparePostObject DataStoreClient::PostObject (see note 1)
DataStoreProtocol::CompletePostObject DataStoreClient::PostObject (see note 1)
DataStoreProtocol::PrepareUpdateObject DataStoreClient::UpdateObject (see note 2)
DataStoreProtocol::CompleteUpdateObject DataStoreClient::UpdateObject (see note 2)
DataStoreProtocol::DeleteObject DataStoreClient::DeleteObject
DataStoreProtocol::DeleteObjects DataStoreClient::DeleteObject (batch process)
DataStoreProtocol::ChangeMeta DataStoreClient::ChangeMeta
DataStoreProtocol::ChangeMetas DataStoreClient::ChangeMeta (batch process)
DataStoreProtocol::GetMeta DataStoreClient::GetMeta
DataStoreProtocol::GetMetas or DataStoreProtocol::GetMetasMultipleParam DataStoreClient::GetMeta (batch process)
DataStoreProtocol::SearchObject DataStoreClient::SearchObject
DataStoreProtocol::RateObject DataStoreClient::RateObject
DataStoreProtocol::GetRating DataStoreClient::GetRating
DataStoreProtocol::GetRatings DataStoreClient::GetRating (batch process)
DataStoreProtocol::ResetRating DataStoreClient::ResetRating
DataStoreProtocol::ResetRatings DataStoreClient::ResetRating (batch process)
DataStoreProtocol::TouchObject DataStoreClient::TouchObject
DataStoreProtocol::GetPersistenceInfo DataStoreClient::GetPersistenceInfo
DataStoreProtocol::GetPersistenceInfos DataStoreClient::GetPersistenceInfo (batch processing)
DataStoreProtocol::PerpetuateObject DataStoreClient::PerpetuateObject
DataStoreProtocol::UnperpetuateObject DataStoreClient::UnperpetuateObject
DataStoreProtocol::GetPasswordInfo DataStoreClient::GetPasswordInfo
DataStoreProtocol::GetPasswordInfos DataStoreClient::GetPasswordInfo (batch process)
DataStoreProtocol::CompletePostObjects DataStoreClient::CompleteSuspendedPostObject

※1 Notes: Called once every time the DataStoreClient::PostObject function is called.
Called once every time the DataStoreClient::UpdateObject function is called.

10.4.7. Subscriber

Table 10.7. Correspondence Table for Subscriber APIs
Recorded API Name API Name in Library
SubscriberProtocol::PostContent SubscriberClient::PostContent
SubscriberProtocol::GetContent SubscriberClient::GetContent
SubscriberProtocol::Follow SubscriberClient::Follow
SubscriberProtocol::UnfollowAllAndFollow SubscriberClient::UnfollowAllAndFollow or SubscriberClient::UnfollowAll
SubscriberProtocol::Unfollow SubscriberClient::Unfollow
SubscriberProtocol::GetFollowing SubscriberClient::GetFollowing
SubscriberProtocol::GetFollower SubscriberClient::GetFollower
SubscriberProtocol::GetNumFollowers SubscriberClient::GetNumFollowers
SubscriberProtocol::GetTimeline SubscriberClient::GetTimeline
SubscriberProtocol::DeleteContent SubscriberClient::DeleteContent

10.4.8. Debugging Assistance

Table 10.8. Correspondence Table for Debug Assistance APIs
Recorded API Name API Name in Library
DebugProtocol::EnableApiRecorder DebugClient::EnableApiRecorder
DebugProtocol::DisableApiRecorder DebugClient::DisableApiRecorder
DebugProtocol::IsApiRecorderEnabled DebugClient::IsApiRecorderEnabled
DebugProtocol::GetApiCalls DebugClient::GetApiCalls
DebugProtocol::GetApiSummary DebugClient::GetApiSummary
DebugProtocol::SetExcludeJoinedMatchmakeSession DebugClient::SetExcludeJoinedMatchmakeSession
DebugProtocol::GetExcludeJoinedMatchmakeSession DebugClient::GetExcludeJoinedMatchmakeSession

10.4.9. APIs Called Automatically by Library

Table 10.9. APIs Called Automatically by the Library
Function Name Called on the Server Call Timing
SecureConnectionInternalProtocol::GetConnectionID While logging in
SecureConnectionInternalProtocol::InsertConnectionProperties While logging in
SecureConnectionInternalProtocol::UpdateConnectionProperties When using NAT traversal
SecureConnectionInternalProtocol::ReplaceConnectionProperties When using NAT traversal
NATTraversalReportInternalProtocol::ReportNATTraversalResult When using NAT traversal
NATTraversalReportInternalProtocol::ReportNATTraversalResultDetail When using NAT traversal
NATTraversalReportInternalProtocol::ReportNATProperties At the first ConnectivityManager::StartNatSession after logging in

10.5. Changing Game Server Functionality

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.

10.5.1. Changing the Setting to Exclude Previously-Joined Matchmaking Sessions

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