서버사이드

개요

서버사이드에서 수집하는 유저의 행동로그를 수집하는 파이프라인에 로그를 기록하는 방법과 로그 규약에 대한 가이드 입니다.

연동 기본 규약

로그 규약

로그 시스템은 게임과 관련된 모든 로그를 통합 수집/관리/분석 하는 시스템으로 대량 로그 특성상 반드시 준수해야 하는 규칙이 있습니다.

• 로그는 반드시 건당 단일 JSON Type 이어야 합니다. ( JSON root는 배열이 아니어야 합니다.)

• JSON은 로그 데이터 구별을 위해 반드시 아래 필드가 있어야 합니다. (인사이트랩에서 제공하는 로그 명세서 규칙을 따르니, 보다 자세한 정보는 로그 명세서를 참고 바랍니다.)

  • log_type 로그를 구별하기 위한 로그 이름

    • 로그 이름은 대문자로 한다.

    • 모든 서버 유저 행동 로그는 log_type을 지정하여 다른 로그와 충돌이 발생하지 않도록 합니다.

  • service_id

    • 게임에 부여되는 Service ID가 로그에 포함 되어야 합니다.

  • cre_time

    • 로그 발생 시간을 ISO 8601 표준 시간으로 기록합니다. (예: 2024-02-07T14:00:00.000Z)

환경 변수

연동 인프라는 Endpoint가 변경 될 수 있어 빌드의 배포 시점에 주입이 가능하도록 되도록 환경 변수를 통해 입력 받는 것을 추천합니다.

HUBLOG_KINESIS_STREAM_NAME     # 로그 스트림 이름
SERVICE_ID                     # 서비스ID

개발 환경

온프레미스 환경에서 개발 진행 시 아래 샘플 데이터로 테스트 진행 하실 수 있습니다.

저장 한 로그를 확인 할 수 있는 환경은 기술PM이 접속 환경 조사 후 접근 허용 처리 후 전달 드립니다.

HUBLOG_KINESIS_STREAM_NAME =    # 기술 PM이 정보를 전달 해 드립니다
HUBLOG_KINESIS_REGION =         # 기술 PM이 정보를 전달 해 드립니다.
SERVICE_ID =                    # 기술 PM이 정보를 전달 해 드립니다.

연동 기술

Kinesis

Amazon Kinesis는 스트리밍 데이터를 처리하는 솔루션입니다. Kinesis를 통해 유입되는 로그 스트림을 처리하여 실시간 조회 환경과 분석 시스템으로 이관됩니다.

레퍼런스 참고 자료

레코드를 기록하는 API 가이드

• PutRecord() 를 이용 한 단일 로그 기록: https://docs.aws.amazon.com/ko_kr/kinesis/latest/APIReference/API_PutRecord.html
• PutRecords() 를 이용 한 다수 로그 기록: https://docs.aws.amazon.com/ko_kr/kinesis/latest/APIReference/API_PutRecords.html

Go

Go v2 SDK 가이드

• SDK 가이드: https://aws.github.io/aws-sdk-go-v2/docs/
• AWS Go v2 SDK Kinesis Reference: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/kinesis#Client.PutRecord

샘플 코드

아래 샘플 코드는 표준 입력에서 데이터를 읽어와 AWS Kinesis 스트림에 전송하는 간단한 예제입니다.

소스코드: https://github.com/harlow/kinesis-consumer/blob/master/examples/producer/main.go

JavaScript

Javascript SDK 가이드

• SDK 가이드: https://docs.aws.amazon.com/ko_kr/sdk-for-javascript/v2/developer-guide/getting-started-nodejs.html
• AWSJavaScriptSDK Kinesis Reference: https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Kinesis.html#putRecord-property

샘플 코드

아래 샘플 코드는 발생하는 로그를 모아 1초마다 한번 씩 로그를 전송하는 샘플 코드입니다.

소스코드: https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/kinesis/src/kinesis-example.js

C++

AWS SDK for C++ 가이드

• SDK 가이드 : AWS SDK for C++ Developer Guide - AWS SDK for C++
• Kinesis Refrence: AWS SDK for C++: Class List

AWS SDK for C++ 을 이용해 Kinesis Data Stream에 Payload를 전달 하는 예제 코드 입니다.

• Put Record 공식 샘플: kinesis/put_get_records.cpp
• 3rd Party 애플리케이션 사용 예: aws_kinesis.cpp

AWS SDK for C++ (Async) 가이드

• Asynchronous method 가이드: Asynchronous methods - AWS SDK for C++
• Kinesis PutRecordAsync: AWS SDK for C++: Aws::Kinesis::KinesisClient Class Reference
• Executor가 Asynchronous method 호출 시에 스레드를 생성합니다. 스레드풀을 구성하기 위해서는 해당 공식 블로그 의 내용을 참고하여 PooledThreadExecutor 를 정의하여 사용 할 수 있습니다.

Kinesis Data Stream API는 최대 처리량이 제한이 있습니다.

• PutRecords API는 요청 당 최대 500개의 Record를 처리 할 수 있습니다.

• 각 레코드는 최대 1MiB까지 가능하며, 요청 당 전체 최대 용량은 5MiB입니다.

Kinesis Data Stream은 데이터 생성자(스트림을 전송하는 AWS SDK Client)의 수에 따라 서버 샤드 수가 비례하여 증가 되어야 합니다.

단일 샤드가 처리 할 수 있는 요청 수와 용량이 고정되어 있기 때문에 과도하게 많은 AWS SDK Client를 선언 하거나 소량의 로그를 매우 빈번하게 요청 하는 경우 샤드가 처리할 수 있는 용량이 많이 남아 있음에도 많은 수의 샤드를 구성하여야 합니다.

되도록 풀을 구성하고, 다수의 로그를 모아서 스트리밍 하는 것이 인프라 구성 및 통신 부하 감소 측면에서 도움이 됩니다.

파티션 키

파티션 키는 레코드를 데이터 스트림의 다른 샤드에 격리하는 기준 값입니다. 여러 샤드 균등하게 분리하기 위해 랜덤키나 회원 번호등 해싱 하였을 때 비교적 균등하게 분포되는 값을 활용합니다.

일반적으로 회원 번호(IMID)나 세션 키와 같이 동일 샤드에서 처리 순서 보장의 이점이 있는 값을 사용하는 것을 추천합니다.

유저 행동 로그 조회

실시간 조회 환경

OpenSearch Dashboard를 통해 유저 행동 로그를 실시간으로 조회 할 수 있습니다.

OpenSearch Dashboard 는 기술PM이 접속 환경 조사 후 접근 허용 처리 후 전달 드립니다.