36. 서버 관리 Part 5: 실행 중 설정 변경

아이펀엔진은 서버의 일부 기능을 실행중에 조정할 수 있는 기능을 제공합니다.

36.1. Run-time 에 설정 가능한 플래그들

조정 가능한 기능은 아래에 언급된 아이펀 엔진 플래그들과 서버 프로그래머가 직접 정의한 플래그들입니다. (플래그를 추가하는 자세한 내용은 프로그래밍 Part 3: 프로그램 실행 인자 를 참고해주세요.)

Important

본 기능은 MANIFEST.json 파일의 값을 변경하지 않습니다. flag 값을 변경하면 서버가 실행중인 동안에만 변경된 값으로 유지되고 서버가 재시작되면 모두 원래 값으로 되돌아갑니다.

36.1.1. 아이펀 엔진 플래그

로그 관련된 기능들:

  • minloglevel: 출력되는 최소 로그 레벨을 변경할 수 있습니다.
  • v: verbose 로그를 출력시킬 수 있습니다.
  • alsologtostderr: log file 뿐만 아니라 console 에도 로그를 출력시킬 수 있습니다.
  • session_message_logging_level: 클라이언트-서버간 session 메시지 로그 레벨을 수정합니다. 0 은 로그를 남기지 않음을, 1은 메시지 타입과 길이만을, 2는 전체 메시지를 덤프하는 것을 의미합니다. 자세한 내용은 네트워킹 기능 설정 파라미터 을 참고하세요.
  • rpc_message_logging_level: 서버간 RPC 통신의 메시지 로그 레벨을 변경합니다. 0 은 로그를 남기지 않음을, 1은 메시지 타입과 길이만을, 2는 전체 메시지를 덤프하는 것을 의미합니다. 자세한 내용은 분산처리 기능의 설정 파라미터 을 참고하세요.

서버 성능 관련된 기능들:

  • enable_event_profiler: 아이펀 엔진의 이벤트 프로파일링 기능을 활성화시킵니다. 자세한 내용은 이벤트 프로파일링: 상세 정보 을 참고하세요.
  • event_threads_size: 이벤트 스레드 개수를 설정합니다. 이벤트 스레드는 아이펀 엔진의 메인 스레드에 해당합니다. 자세한 내용은 이벤트 기능 설정 파라미터 을 참고하세요.

클라이언트 제어 관련된 기능들:

  • client_current_version: 서버에 대응하는 client 의 최신 버전을 수정합니다. 이 버전에 해당되지 않는 클라이언트들의 접근이 제한됩니다. 자세한 내용은 클라이언트 지원 Part 3: 클라 버전 을 참고하세요.

36.1.2. 서버프로그래머가 추가한 플래그

프로그래밍 Part 3: 프로그램 실행 인자 에 설명된대로 서버에 플래그를 추가한 뒤에, 해당 플래그가 run-time 에 수정 가능한 플래그라는 것을 MANIFEST.json 상에서 지정해줘야됩니다.

...
"RuntimeConfiguration": {
  "enable_runtime_configuration": true,
  "additional_configurations": ["flag1", "flag2", ... ]
}
...

예를 들어 로그인하면 골드를 지급하는 이벤트가 진행중인지 여부를 다음과 같이 google flag 로 지정했다고 하겠습니다.

DEFINE_bool(enable_gold_event,   // flag 의 이름을 입력합니다.
            false,               // flag 의 기본값을 입력합니다.
            "gold event flag");  // flag 의 설명을 입력합니다.

이렇게 정의한 flag 를 MANIFEST.json 에 다음처럼 run-time 에 수정 가능한 플래그로 지정합니다.

...
"RuntimeConfiguration": {
  "enable_runtime_configuration": true,
  "additional_configurations": ["enable_gold_event"]
}
...

36.2. Run-time 설정 변경 기능 활성화 하기

MANIFEST.json 의 RuntimeConfiguration 섹션에서 enable_runtime_configuration 를 true 로 변경해줍니다.

...
"RuntimeConfiguration": {
  "enable_runtime_configuration": true,
  "additional_configurations": []
}
...

Important

RuntimeConfigurationApiService 를 기반으로 동작하므로 ApiService 기능 설정 파라미터 에 설명된대로 ApiService 가 활성화되어야 합니다.

36.3. Run-time 설정 변경을 위한 RESTful APIs

36.3.1. 설정 가능한 모든 flag 조회하기

GET /v1/configurations/

요청 예제:

GET /v1/configurations/ HTTP/1.1

응답 예제:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "minloglevel": {
    "type": "int32",
    "desc": "Messages logged at a lower level than this don't actually get logged anywhere",
    "value": "0"
  },
  ...
}

36.3.2. 특정 flag 값 조회하기

GET /v1/configurations/<flag_name>
Parameters:
  • flag_name – 조회할 flag 이름입니다.

예제 1: flag 가 존재하는 경우:

요청:

GET /v1/configurations/minloglevel HTTP/1.1

응답:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "minloglevel": {
    "type": "int32",
    "desc": "Messages logged at a lower level than this don't actually get logged anywhere",
    "value": "0"
  }
}

예제 2: flag 가 존재하지 않는 경우:

요청:

GET /v1/configurations/no_flag HTTP/1.1

응답:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "no_flag": {
        "message": "This is not available",
        "available_configurations": {
            "minloglevel": {
                "type": "int32",
                "desc": "Messages logged at a lower level than this don't actually get logged anywhere"
            },
            ...
        }
    }
}

36.3.3. 특정 flag 값 변경하기

PUT /v1/configurations/<flag_name>/<value>
Parameters:
  • flag_name – 변경할 flag 이름입니다.
  • value – 변경할 값입니다.

예제 1: value 가 valid 한 경우:

요청:

PUT /v1/configurations/minloglevel/1 HTTP/1.1

응답:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "minloglevel": {
    "result": "minloglevel set to 1\n"
  }
}

예제 2: value 가 valid 하지 않은 경우:

요청:

PUT /v1/configurations/minloglevel/one HTTP/1.1

응답:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "minloglevel": {
    "result": "The 'one' is not a valid value"
  }
}

36.3.4. 클라이언트 버전 통제하기

36.3.4.1. 호환 가능 클라이언트 버전 정보 조회하기

다음과 같은 API 를 호출하면 MANIFEST.jsonAppInfo 컴포넌트에 설정한 client_compatible_versions 을 가져올 수 있습니다.

GET /v1/configurations/compatible_client_versions

예제:

요청:

GET /v1/configurations/compatible_client_versions HTTP/1.1

응답:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "current_compatible_versions": ["0.0.1","0.0.2"]
}

36.3.4.2. 호환 가능 클라이언트 버전 정보 변경하기

다음과 같이 API 를 호출하면 compatible client version 을 변경할 수 있습니다.

POST /v1/configurations/compatible_client_versions

예제:

요청:

POST /v1/configurations/compatible_client_versions HTTP/1.1

["0.0.3", "0.0.4"]

응답:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "current_compatible_versions": ["0.0.3", "0.0.4"]
}

Important

MANIFEST.json 파일의 AppInfo 내용을 수정하진 않습니다. 서버가 재시작되면 변경한 내용이 모두 되돌아갑니다.

36.4. Run-time 설정 가능 플래그 사용시 주의점

아이펀 엔진의 run-time 설정 변경 기능은 Gflag 의 값을 변경하는 방식으로 동작합니다. 따라서 설정이 변경될 수 있는 플래그의 경우, 해당 플래그가 사용되는 코드에서 직접 gflag 를 호출해야됩니다.

아래의 예는 서버프로그래머가 추가한 플래그 에 설명된 대로 enable_glod_event 를 run-time 설정 가능 플래그로 지정했음에도, 해당 값을 직접 읽는 것이 아니라 전역 변수에 값을 저장해두고 사용함으로써 버그가 발생하는 경우입니다.

잘못된 사용 예:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
DEFINE_bool(enable_gold_event, false, "gold event flag");

bool the_is_gold_event_enabled = false;

void EventManager::Initialize() {
  the_is_gold_event_enabled = FLAGS_enable_gold_event;
}

bool EventManager::IsGoldEventEnabled() {
  return the_is_gold_event_enabled;
}


void OnLogin() {
  Ptr<User> user = User::Fetch(...);

  if (EventManager::IsGoldEventEnabled()) {
    user->SetGold(user->GetGold() + 100);
  }
}

위의 예제는 아래처럼 수정되어야 합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
DEFINE_bool(enable_gold_event, false, "gold event flag");

bool EventManager::IsGoldEventEnabled() {
  return FLAGS_enable_gold_event;
}

void OnLogin() {
  Ptr<User> user = User::Fetch(...);

  if (EventManager::IsGoldEventEnabled()) {
    user->SetGold(user->GetGold() + 100);
  }
}