Hive가 제공하는 애널리틱스는 게임 별로 사업에 필요한 주요 지표를 모두 표준화 하여 온라인으로 지표 정보를 제공합니다. 지표로 제공하는 정보는 게임 매출, 이용자, 동접, 게임 판수, 재화 지표 등이며, 게임 사업 담당자들은 이 정보를 이용하여 게임의 현재 운영 상태를 쉽게 파악하고 필요에 따라 빠르게 대응할 수 있습니다.

Hive 애널리틱스를 이용하는 방법은 간단합니다. Hive 양식에 맞춘 게임 로그를 게임에서 Hive 서버로 전송하기만 하면 됩니다. 개발자가 지표를 직접 집계해야 했던 번거로움을 Hive 애널리틱스로 해소해보세요.

Hive 애널리틱스 동작 구조

Hive 애널리틱스를 이용하려면 게임 서버에서 Hive 서버로 로그를 보내야 합니다. 로그 전송은 Scribe 방식FTP 방식 두 가지가 있습니다.

Scribe 방식

Scribe 방식은 게임 서버에 로그 에이전트(Scribe데몬)를 설치하여 Hive 서버로 로그를 전송하는 구조를 가지며, 일반적으로 로그를 실시간으로 수집하기 위해 사용합니다. Scribe 방식의 대표적인 이점은 네트워크 장애가 발생해도 로그 재전송이 보장된다는 점입니다. 게임 서버와 Hive 서버간 네트워크에 장애가 발생하더라도 Scribe데몬이 메시지 큐의 역할까지 담당하기 때문에 로그 파일을 자체 파일 버퍼 큐에 쌓았다가 재전송할 수 있습니다.

게임 로그 파일을 Hive 서버로 보내는 작업은 게임 서버 소스 코드 안에 로그 전송 기능을 구현하여 수행합니다. 로그 전송 기능은 서버의 로컬 데몬과 통신하는 방식이라 게임 서버 성능을 저하하지 않습니다. 서버 소스 코드에 로그 전송 기능을 삽입하는 것이 부담스럽다면 게임 서버의 메인 프로세스와 별도로 백그라운드 스케줄러에서 로그를 전송하는 방식으로 구현하면 됩니다.

다음은 Scribe방식으로 게임 서버가 Hive 서버에 로그를 보내는 흐름을 그림으로 표현한 것입니다.

FTP 방식

FTP방식은 로그 에이전트(Scribe 데몬)를 게임 서버에 설치할 수 없을 때 사용하는 방법으로, 주로 Windows 계열 서버에서 FTP 방식을 사용합니다. FTP 방식은 게임 서버에 게임 로그를 쌓고, 쌓인 게임 로그를 게임 서버가 Hive Analytics FTP 서버로 주기적으로 전송하는 방식입니다. 로그를 쌓는 작업과 로그를 주기적으로 전송하는 작업은 개발사가 직접 구현해야 하며 또한 로그 전송 중의 통신 장애 발생을 대비하여 전송 실패 시 로그를 재전송하도록 구현해야 합니다.

다음의 그림은 FTP 방식으로 게임 서버가 Hive 서버로 로그를 보내는 흐름의 예시 화면입니다. 게임 서버 측의 구현은 아래 제시된 그림과 다르게 여러분의 상황에 맞게 구현해야 합니다.

Fluentd 방식

Scribe 방식과 같은 동작방식을 취하지만, 발신/수신 데몬에 fluentd를 이용하는 형태입니다. 다양한 플러그인이 지원되어 게임 서버 사이드에서 좀 더 편리하게 구축할 수 있습니다. 또한 개발자 사이트 운영 > Hive 애널리틱스 > 로그 정의 메뉴를 통해 좀 더 쉽게 모니터링할 수 있습니다.

Http 방식

일반적인 curl로 로그를 전송하는 방식입니다. WAS가 로그를 받은 이후에는 fluentd 방식과 동일하게 동작합니다.

Hive 애널리틱스 사전 작업하기

Hive 애널리틱스를 처음 이용하면 다음의 이메일로 문의해야 합니다. Hive 애널리틱스를 이용하려면 먼저 게임 서버에 사전 작업의 수행이 필요합니다.

 

Hive 애널리틱스용 로그 만들기

Hive 애널리틱스에 전송하는 게임 로그는 Hive가 제공하는 로그 스펙이 제시하는 형태를 갖춰야 합니다. 상세한 로그 스펙을 보려면 로그별 스펙을 참고하세요.

게임빌 게임이나 컴투스 게임을 제작한다면, 어떤 로그를 수집할 지에 대해 BI 기획팀과 협의가 필요합니다.

 

Hive 서버에 로그 전송하기

Hive 서버로 전송하는 로그는 로그별 스펙에 준하는 형식을 갖춰야 하며 로그를 전송하는 게임 서버 식별자와 로그 카테고리가 반드시 명시되어야 합니다. Hive 서버로 로그를 어떤 방식으로 보내는 지에 따라 로그 전송 방법이 다릅니다. 아래에서 각 방식에 대해 자세히 살펴보세요.

Scribe 방식

Scribe 방식으로 Hive 서버에 로그를 보내는 방법은 클라이언트(게임 서버)가 PHP 기반인지, Java 기반인지에 따라 달라집니다.

게임 서버에서 Hive서버로 로그를 보내려면, 게임 서버에 Scribe데몬이 실행되고 있어야 합니다.
게임 서버에 Scribe데몬을 설치하지 않았다면 Hive 애널리틱스 준비하기에 명시된 대로 테크 PM에게 연락하여 안내를 받으세요.

PHP 클라이언트

테크PM에서 사전 작업으로 게임 서버 로컬에 Scribed 데몬을 설치해주고 설정 파일을 작업했다면 그 다음으로 소스 코드를 구현합니다. 게임 서버가 PHP 기반이라면, Hive 애널리틱스 이용에 필요한 PHP 라이브러리를 게임 서버 라이브러리 폴더에 복사하고, 게임 로직 부분에 로그 전송 코드를 구현하세요.

PHP 기반의 게임 서버에서 Hive 애널리틱스 서버로 로그를 전송하기 위해서는 Thriftscribe, 두 개의 PHP 라이브러리가 필요합니다. PHP 라이브러리는 Scribe를 설치할 때 테크PM에서 제공합니다. 가장 간편한 방법은 게임 서버의 라이브러리 폴더에 복사한 후 include 해서 사용합니다. 이 라이브러리는 GitHub에서도 다운로드 받을 수 있습니다.

일반적으로는 GCP 테크PM 에서 지원해주므로 별도로 받을 필요는 없습니다.

  • Hive 서버로 TEST 로그 전송하기
    이하의 샘플 코드로 Scribed로의 로그 전송을 테스트할 수 있습니다.
    주석으로 표기된 부분이 로그 스펙마다 바꿔줘야하는 부분이며 실제 라이브용 코드도 이 부분을 복사해서 붙여넣는 식으로 넣으면 됩니다.
  1. Scribe 라이브러리의 루트 폴더를 정의한다.
  2. 전송을 위한 관련 라이브러리들을 include 한다.
  3. 스펙에 맞는 로그 데이터 항목을 넣어준다.
    1. 스펙에 맞는 카테고리를 입력한다. (로그인 로그의 경우 login_log, 여기서는 test1 )
    2. 로그 생성 일시 정보를 Hive 로그 스펙에 맞게 설정한다.
    3. 클라이언트의 IP를 client_ip에 설정한다.
    4. 각 로그에 맞는 항목들을 넣어준다. ($msg[‘aaa’] = $aaa; 에 대한 부분)
  4. 로그를 전송할 목적지를 설정한다.
    1. 호스트는 ‘localhost’로 설정한다. (게임 서버 로컬에 Scribe 데몬과 통신하기 때문)
    2. 포트 번호는 1463으로 설정한다.
  5. 샘플 php 파일을 커맨드 라인에서 실행한다.
    1. php sample.php
  6. 아무런 에러 메시지가 나오지 않는다면 전송 성공.
  7. 테스트 서버에서 테스트했다면 DW파트에 로그가 잘 도착했는지 확인 요청.

아래는 test1 카테고리의 로그의 aaa 에 ttt 라는 값, bbb 에 fff 라는 값을 담아 Scribe 방식을 통해 PHP 기반의 Hive 서버로 전송하는 예제 코드입니다.

  • sample.php
전송한 로그가 DB에 잘 쌓였는지 확인하시려면 DW파트로 문의하세요.

Java 클라이언트

게임 서버가 Java 기반이라면, Hive 애널리틱스 이용에 필요한 라이브러리를 임포트해서 게임 서버 내에 전송 로직을 구현하세요. Java 기반의 게임 서버에서 Hive Analytics 서버로 로그를 전송하기 위해서는 다음과 같이 세 개의 라이브러리가 필요합니다.

maven 이나 gradle 로 받는다면 맨 아래 flume-scribe-source 저장소 주소만 등록하면 됩니다.

  • Maven Repository
  • Hive 서버로 TEST 로그 전송하기
    test 카테고리로 json 로그를 전송합니다. 예제의 json 변수는 스트링이므로 참고만 하며, 그대로 쓴다면 함수 호출 전에 serialize가 필요합니다.
  1. 예제 소스를 복사한다.
  2. 로그 스펙에 맞게 항목을 수정한다.
    1. 카테고리를 설정한다. (String category_key = “test”;)
    2. String json 안에 로그 json 문자열을 넣을 수 있게 한다. ({“test”:1} 등)
  3. 예제 함수를 실행한다.

다음은 test 카테고리의 로그를 Scribe 방식을 통해 Java 기반의 Hive 서버로 전송하는 예제 코드입니다.

참고 사항
Scribed의 내부 처리가 궁금하다면 이하 github 에서 소스를 확인할 수 있습니다.
또한 디버깅에 참고할 수 있도록 Hive 애널리틱스의 Scribe 서버 주소를 첨부합니다.

  • Scribe GitHub: https://github.com/facebookarchive/scribe
  • Scribe 서버 (사설/공인 IP)
    • 샌드박스: sandbox-analytics-scribe.withhive.com (112.175.143.37)
    • 상용: analytics-scribe.withhive.com (172.19.1.10/112.175.65.135)

FTP 방식

Hive 애널리틱스 FTP 타입은 Scribe 데몬을 게임 서버에 설치할 수 없을 때 사용하는 방법입니다. FTP 방식을 이용하면 개발사의 게임 로그를 Hive 애널리틱스 서버에 주기로 올려야 합니다.

Hive 애널리틱스 FTP 서버를 이용하려면 FTP 서버 계정이 필요합니다. FTP 서버 계정을 요청하려면 테크 PM에 신청하세요.

회사에 따라 Hive 애널리틱스 FTP 서버로 접속하기 위해 방화벽을 열어야 할 수도 있습니다. 게임빌이나 컴투스 각 회사의 테크 PM에게 문의하세요.

  • FTP 서버 정보
    Hive 애널리틱스 FTP 서버 주소는 다음과 같습니다.

    • 샌드박스: sandbox-analytics-ftp.withhive.com (183.111.229.178)
    • 상용: analytics-ftp.withhive.com (112.175.143.96)
게임 로그 준비하기

Hive 애널리틱스 FTP 서버에 올리는 게임 로그는 다음의 규칙대로 구성되어야 합니다.

  • 로그 파일명: <로그 카테고리 약어> <날짜시분>_<서버 또는 스레드 식별자>.json
    (예: new_user_20170316_235247_KR.json)
  • 로그 파일 인코딩: UTF-8 (no BOM)
Hive 애널리틱스 FTP 서버에 게임 로그 올리기

Hive가 제시한 정책에 맞게 게임 로그가 준비되면, Hive 애널리틱스 FTP 서버 내에 logs 디렉토리로 게임 로그 파일을 올립니다.
게임 로그를 올릴 때는 다음의 안내 사항을 따라주세요.

  • 로그 파일 전송 위치: Hive Analytics FTP 서버의 logs 디렉토리 내
  • 로그 파일 전송 주기: 최대 10분
  • 전송 모드: FTP passive 모드

JSON 디코딩 실패 시 errors/ 디렉토리에 기록됩니다.

로그 처리 후 1시간 까지 wait-for-delete/ 디렉토리에 남게됩니다. (디랙토리가 존재할 경우만)

로그 파일을 Hive 애널리틱스 FTP 서버에 주기적으로 전송하려면 파일 전송 스크립트를 작성하여 스케줄러로 스크립트를 수행합니다. 또한, 전송 장애를 대비하여 Hive 애널리틱스 FTP 서버로 전송한 게임 로그 파일은 개발사의 게임 서버에 최소 일주일은 보관하고 삭제하기를 권장합니다.

Fluentd 방식

Fluentd 자체에 대한 설명은 공식 사이트에 자세한 문서를 참조하세요.

fluetnd 방식은 Hive 애널리틱스 웹콘솔 로그 정의 > 템플릿으로 등록 후 사용 가능합니다.

fluentd 에이전트의 설치와 운용은 게임빌이나 컴투스 각 회사의 테크 PM에게 문의하세요.

Windows 서버의 경우 [nxlog](https://nxlog.co/) 로 전송 가능합니다. 자세한 내용은 테크 PM 에 문의하세요.

  • Fluentd 서버 정보
    Hive 애널리틱스 Fluentd 서버 주소는 다음과 같습니다. 2대로 로드밸런싱 가능합니다.

    상용 서버 (외부망) analytics-hivelog-03.withhive.com (183.111.164.136)analytics-hivelog-04.withhive.com (183.111.164.167)
    Sandbox (외부망) sandbox-analytics-log.withhive.com
  • Fluentd Tag Information
    • tag 명 : ha2union.game.[로그카테고리명]
    • 예1: ha2union.game.hivesdk_login_log
    • 예2: ha2union.game.hivesdk_levelup_log
  • 필수 필드 (로그에서 아래 필드 전송 필수)
    appId STRING Hive에서 지정된 AppId
    category STRING 로그 정의에서 지정한 카테고리
    logBody.dateTime STRING YYYY-MM-DD HH:mm:SS 형식으로 표시되는 로그 시간
    한국 시간 기준(KST) 혹은 ISO-8601
    logBody.guid STRING 로그의 키값
    랜덤 문자열 생성 추천

추가적으로 fluentd 전송 구축에 필요한 정보는 다음과 같습니다.

fluentd 를 통한 로그 정의 로그 전송 샘플은 로그 정의 전송을 참고하세요.

Web 방식 (https)

Http 방식은 Hive 애널리틱스 웹콘솔 로그 정의 > 템플릿으로 등록을 이용하여 사용 가능합니다.

  • Server Information
    Hive 애널리틱스 웹서버 주소는 다음과 같습니다.

    • 개발서버: https://test-analytics-log.withhive.com/v1/server-recv
    • 샌드박스: https://sandbox-analytics-log.withhive.com/v1/server-recv
    • 상용서버: https://analytics-log.withhive.com/v1/server-recv
  • Header Information
    • Method: POST
    • Content-Type: application/json; charset=utf8 (필수)
    • Content-Encoding: gzip (body에 압축바이너리를 넣을때 사용하는 옵션)
  • Body Information
    • JSON 형식이며 아래 구조에 맞춰서 전송해야 합니다. 일부 필드는 지정된 키값을 사용해야 입력됩니다.
    • 필수 파라미터 (로그에서 아래 필드 전송 필수)
      appId STRING Hive에서 지정된 AppId
      logBody Array 로그가 한줄씩 들어가는 배열
      logBody.category STRING 로그 정의에서 지정한 카테고리
      logBody.dateTime STRING YYYY-MM-DD HH:mm:SS 형식으로 표시되는 로그 시간
      한국 시간 기준(KST) 혹은 ISO-8601
      logBody.guid STRING 로그의 키값
      랜덤 문자열 생성 추천

      이 외의 값은 각 로그에 맞춰서 logBody의 각 행(row)에 넣습니다.

    • 예시
      • 호출

      • 요청

      • 응답

게임 진입 구간 퍼널 로그 전송하기

게임 실행한 순간부터 로비에 도착하기까지 유저의 이탈 구간을 분석하기 위해 Hive SDK가 구간별로 Hive 애널리틱스에 로그를 전송하는 기능입니다.
Hive SDK v1.17.2 이상 버전을 적용할 때 로그가 자동으로 전송되며, Hive 콘솔 > 애널리틱스 > 분석 > 퍼널 분석 메뉴에서 퍼널 생성 후 확인할 수 있습니다. 콘솔에서 퍼널을 생성하는 방법은 운영 > Hive 애널리틱스 > 퍼널 분석 페이지를 참조하세요.

  • 퍼널 수집 구간
    Hive 연동가이드라인 > 게임 진행 플로우 가이드 기준, 아래에 명시된 구간에서 유저의 잔존 상태를 확인할 수 있습니다.
  • 4-1 권한 고지
  • 4-2 업데이트/공지 팝업
  • 4-3 약관 동의
  • 5 게임 서버 수동 선택
  • 6 서버 점검 팝업
  • 7 추가 다운로드 시작/종료(API)
  • 9 로그인
  • 10 대배너
  • API를 이용한 추가 다운로드 구간 로그 전송
    추가 다운로드 구간은 Hive SDK에서 시점 확인이 불가하여 게임 스튜디오에서만 로그를 전송할 수 있습니다. API를 이용해 추가 다운로드의 시작과 끝을 로그로 전송하세요. Hive SDK Client를 사용할 때 샘플 코드는 Social SendData 파트를 확인하세요.