GS2-Log

API access log and analysis feature

GS2-Log provides a feature for aggregating and storing API access logs of all Game Server Services microservices embedded in your game.

In game operation, it is very important to be able to later trace “when, who, which API was called, with what arguments, and what result was returned”. GS2-Log data can be leveraged as the foundation for various operational tasks such as investigating fraudulent players, checking game balance, handling user inquiries, and aggregating KPIs.

GS2-Log features are not intended to be used directly from the game client; they are designed to be used in conjunction with operator-side tools and data analysis platforms.

Log types

GS2-Log records the following four types of logs.

AccessLog

A log recorded every time an API of a microservice is called.

timestamp: API call time
requestId: A unique ID identifying the request
service: The microservice name that was called
method: The API method name that was called
userId: The user ID of the caller
request: Request parameters (JSON string)
result: Response content (JSON string)

This enables fine-grained behavioral tracking at the API level and can be used for defect investigation or behavior log analysis.

IssueStampSheetLog

A log recorded when a transaction is issued. A transaction is the batch execution unit of acquire and consume actions in Game Server Services. The log records the list of consume actions at the time of issuance and what triggered the issuance.

timestamp: Time of issuance
transactionId: Transaction ID (identifier per transaction issuance)
service: Issuing microservice
method: Issuing API
userId: User ID
action: Acquire action
args: Arguments of the action
tasks: List of consume actions contained in the transaction

ExecuteStampSheetLog / ExecuteStampTaskLog

Logs recorded when the entire transaction or each consume action is executed.

By combining these with IssueStampSheetLog, you can trace when an issued transaction was executed and how. This information can be leveraged to detect replay attacks, illegal multiple executions, and consistency issues between services.

sequenceDiagram
  participant Client
  participant ServiceA as Microservice A
  participant Sheet as Transaction
  participant ServiceB as Microservice B
  participant Log as GS2-Log

  Client->>ServiceA: Reward request
  ServiceA->>Log: AccessLog
  ServiceA->>Sheet: Issue Transaction
  ServiceA->>Log: IssueStampSheetLog
  Sheet->>ServiceB: Execute consume action
  ServiceB->>Log: ExecuteStampTaskLog
  Sheet->>Log: ExecuteStampSheetLog

Log export destinations

Logs recorded with GS2-Log can be forwarded to the export destination specified in the namespace settings.

`type`	Destination	Description
`gs2`	GS2 internal log storage	Stored within GS2-Log without export
`bigquery`	Google Cloud BigQuery	Specify `gcpCredentialJson` and `bigQueryDatasetName`
`firehose`	Amazon Kinesis Data Firehose	Specify `awsRegion` / `awsAccessKeyId` / `awsSecretAccessKey` / `firehoseStreamName`

By writing aggregation queries at the export destination, you can continuously measure custom KPIs such as DAU, billing amounts, and the count of specific item acquisitions.

Log retention period

By specifying logExpireDays, you can control the retention period of logs within GS2-Log. For logs that require long-term retention, it is recommended to use the export feature above to forward them to your own data warehouse.

In-game logs

There is also an “in-game log” feature where the client can send arbitrary payloads to GS2-Log.

You can send any event that occurs in the game (stage clear, gacha result, UI operations, etc.) as a pair of payload and tags, and handle them on the same aggregation infrastructure as AccessLog.

Transaction Actions

GS2-Log does not provide transaction actions.

Master Data Management

GS2-Log does not have master data. Configuration such as the log aggregation destination is set in the namespace settings.

Example Implementation

GS2-Log is mainly used for aggregation and analysis, and the reference APIs are expected to be called from operator-side tools and dashboards. Only in-game log sending is used from the game client, so a sample via Unity SDK is shown. For aggregation APIs and export settings, operate them via the management console or general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java).

Send an in-game log (Unity)

Send a game-internal log with an arbitrary payload and tags. Tags can be used for filtering on BigQuery, etc., so storing event types or stage IDs helps in analysis.

    var domain = await gs2.Log.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SendInGameLogAsync(
        payload: "{\"event\":\"stage_clear\",\"stageId\":\"stage-0001\"}",
        tags: new [] {
            new Gs2.Unity.Gs2Log.Model.EzInGameLogTag {
                Key = "category",
                Value = "stage",
            },
        }
    );

The Unreal Engine SDK does not provide an Ez Domain class targeted at the game client. When sending in-game logs from Unreal Engine, call the GS2-Log SendInGameLog API directly via the Source SDK.

More practical information

Fraud detection using logs

By cross-checking IssueStampSheetLog and ExecuteStampSheetLog, you can verify whether issued transactions were executed as expected. If multiple execution logs are recorded for the same transactionId, or if execution logs exist without a matching issuance log, this may indicate replay attacks or a fraudulent client implementation.

Log aggregation operations

By periodically running aggregation queries against export destinations such as BigQuery, you can obtain the following metrics.

Number of daily active users (deduplicated by userId)
Number of API calls per specific microservice or API
Frequency of transaction issuance for gacha, purchases, experience gains, etc.
Ratio and trends of APIs that returned an error response