> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Log

APIアクセスログ・分析機能




GS2-Log はゲームに組み込まれた全ての Game Server Services マイクロサービスのAPIアクセスログを集約・保存する機能を提供します。

ゲームの運営において「いつ・誰が・どのAPIを・どのような引数で呼び出し・どのような結果を返したか」を後から追跡できることは非常に重要です。
不正なプレイヤーの調査、ゲームバランスの確認、お問い合わせ対応、KPI 集計などのあらゆる運用業務の基盤として GS2-Log のデータを活用できます。

GS2-Log の機能はゲームクライアントから直接利用するものではなく、運営側のツールやデータ分析基盤と連携して活用するためのものです。

## ログの種類

GS2-Log は以下の4種類のログを記録します。

### AccessLog

各マイクロサービスのAPIが呼び出されるたびに記録されるログです。

- `timestamp`: API呼び出し時刻
- `requestId`: リクエストを一意に識別するID
- `service`: 呼び出されたマイクロサービス名
- `method`: 呼び出されたAPIメソッド名
- `userId`: 呼び出し元のユーザーID
- `request`: リクエストパラメーター (JSON文字列)
- `result`: 応答内容 (JSON文字列)

API単位の細かい挙動追跡が可能で、不具合の調査や行動ログの分析に利用できます。

### IssueStampSheetLog

トランザクションが発行された際に記録されるログです。
トランザクションは Game Server Services における入手・消費アクションのまとめ実行単位であり、発行時の消費アクション一覧と、何をきっかけに発行されたのかを記録します。

- `timestamp`: 発行時刻
- `transactionId`: トランザクションID(トランザクション発行単位の識別子)
- `service`: 発行元マイクロサービス
- `method`: 発行元API
- `userId`: ユーザーID
- `action`: 入手アクション
- `args`: アクションの引数
- `tasks`: トランザクションに含まれる消費アクション一覧

### ExecuteStampSheetLog / ExecuteStampTaskLog

トランザクション全体・消費アクションが実行された際に記録されるログです。

`IssueStampSheetLog` と組み合わせることで、いつ発行されたトランザクションが、いつどのように実行されたかをトレースできます。
この情報は、リプレイ攻撃や不正な多重実行、サービス間の整合性問題の検知に活用できます。

```mermaid
sequenceDiagram
  participant Client
  participant ServiceA as マイクロサービスA
  participant Sheet as トランザクション
  participant ServiceB as マイクロサービスB
  participant Log as GS2-Log

  Client->>ServiceA: 報酬リクエスト
  ServiceA->>Log: AccessLog
  ServiceA->>Sheet: トランザクション発行
  ServiceA->>Log: IssueStampSheetLog
  Sheet->>ServiceB: 消費アクション実行
  ServiceB->>Log: ExecuteStampTaskLog
  Sheet->>Log: ExecuteStampSheetLog
```

## ログのエクスポート先

GS2-Log で記録したログは、ネームスペースの設定で指定したエクスポート先に転送できます。

| `type` | 連携先 | 説明 |
| --- | --- | --- |
| `gs2` | GS2 内部のログストレージ | エクスポートせず GS2-Log 内に保管 |
| `bigquery` | Google Cloud BigQuery | `gcpCredentialJson` と `bigQueryDatasetName` を指定 |
| `firehose` | Amazon Kinesis Data Firehose | `awsRegion` / `awsAccessKeyId` / `awsSecretAccessKey` / `firehoseStreamName` を指定 |

エクスポート先で集計クエリを書くことで、DAU・課金額・特定のアイテム入手数などのカスタム KPI を継続的に計測できます。

## ログの保持期間

`logExpireDays` を指定することで、GS2-Log 内のログ保持日数を制御できます。
長期保存が必要なログは、上記エクスポート機能を用いて自前のデータウェアハウスに転送する運用が推奨されます。

## インゲームログ

クライアントが任意のペイロードを GS2-Log に送信できる「インゲームログ」の機能もあります。

ゲーム内で発生した任意のイベント (ステージクリア、ガチャの結果、UI操作など) を `payload` と `tags` の組として送信し、AccessLog と同じ集計基盤で扱うことができます。

## トランザクションアクション

GS2-Log ではトランザクションアクションを提供していません。

## マスターデータ管理

GS2-Log はマスターデータを持ちません。
ログの集約先などはネームスペースの設定で構成します。

## 実装例

GS2-Log は集約・分析が中心で、参照系のAPIは運営側のツール・ダッシュボードから呼び出すことを想定しています。
インゲームログの送信のみゲームクライアントから利用するため、Unity SDK 経由でのサンプルを示します。
集計API・エクスポート設定などは、マネジメントコンソールまたは各種言語向け一般SDK (C# / Go / Python / TypeScript / PHP / Java) から操作してください。

### インゲームログを送信 (Unity)

任意のペイロードとタグを付けてゲーム内ログを送信します。
タグは BigQuery 等での絞り込みに使用できるため、イベント種別やステージIDなどを格納すると分析時に役立ちます。



**Unity**
```csharp

    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",
            },
        }
    );
```


Unreal Engine 用 SDK にはゲームクライアント向けの Ez Domain クラスが提供されていません。
Unreal Engine からインゲームログを送信する場合は、GS2-Log の `SendInGameLog` API を Source SDK 経由で直接呼び出してください。

## より実践的な情報

### ログを用いた不正検知

`IssueStampSheetLog` と `ExecuteStampSheetLog` を突き合わせることで、発行されたトランザクションが期待通りに実行されたかを検証できます。
同一の `transactionId` で実行ログが複数記録されている場合や、発行ログが存在しないのに実行ログがある場合などは、リプレイ攻撃や不正なクライアント実装が疑われます。

### ログ集計の運用例

エクスポート先の BigQuery 等に対し、定期的に集計クエリを実行することで以下の指標を取得できます。

- 1日あたりのアクティブユーザー数 (`userId` の重複排除)
- 特定のマイクロサービス・APIの呼び出し回数
- ガチャ・購入・経験値獲得などのトランザクション発行頻度
- エラー応答が返ったAPIの割合とトレンド

## 詳細なリファレンス

[GS2-Log API リファレンス](../../api_reference/log)