> 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와 Godot SDK의 샘플을 제시합니다.
집계 API·내보내기 설정 등은, 관리 콘솔 또는 각 언어용 일반 SDK (C# / Go / Python / TypeScript / PHP / Java)에서 조작해 주십시오.

### 인게임 로그 송신

임의의 페이로드와 태그를 붙여 인게임 로그를 송신합니다.
태그는 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",
            },
        }
    );
```
**Godot**
```gdscript

var async_result = await ez.log.namespace_(
    "namespace-0001"
).me(game_session).send_in_game_log(
    '{"event":"stage_clear","stageId":"stage-0001"}',
    [
        Gs2LogEzInGameLogTag.new()
            .with_key("category")
            .with_value("stage"),
    ]
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

```


Unreal Engine용 SDK에는 게임 클라이언트용 Ez Domain 클래스가 제공되지 않습니다.
Unreal Engine에서 인게임 로그를 송신하려면, GS2-Log의 `SendInGameLog` API를 Source SDK를 통해 직접 호출하십시오.

## 보다 실전적인 정보

### 로그를 이용한 부정 감지

`IssueStampSheetLog`와 `ExecuteStampSheetLog`를 대조함으로써, 발행된 트랜잭션이 예상대로 실행되었는지를 검증할 수 있습니다.
동일한 `transactionId`로 실행 로그가 여러 건 기록된 경우나, 발행 로그가 존재하지 않는데 실행 로그가 있는 경우 등은, 리플레이 공격이나 부정한 클라이언트 구현이 의심됩니다.

### 로그 집계 운영 예시

내보내기 대상인 BigQuery 등에 대해 정기적으로 집계 쿼리를 실행함으로써 다음과 같은 지표를 얻을 수 있습니다.

- 하루당 활성 사용자 수 (`userId`의 중복 제거)
- 특정 마이크로서비스·API의 호출 횟수
- 가챠·구매·경험치 획득 등의 트랜잭션 발행 빈도
- 오류 응답이 반환된 API의 비율과 추세

## 상세 레퍼런스

[GS2-Log API 레퍼런스](../../api_reference/log)