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와 조합함으로써, 언제 발행된 트랜잭션이 언제 어떻게 실행되었는지를 추적할 수 있습니다. 이 정보는 리플레이 공격이나 부정한 다중 실행, 서비스 간 정합성 문제의 감지에 활용할 수 있습니다.

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 등을 저장하면 분석 시 도움이 됩니다.

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

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의 비율과 추세