콘텐츠로 이동

환경 변수

런타임은 설정이 처음 필요한 시점(첫 번째 Ha*·ha_drv_* API 호출, 또는 첫 호스트 메모리 할당)에 환경 변수를 단 한 번 읽습니다. 따라서 프로세스 실행 이후에 값을 변경해도 반영되지 않으므로, 반드시 실행 전(셸) 또는 첫 Ha* API 호출 전에 설정해야 합니다.

본 문서에 나열된 환경 변수 외에는 설정 대상이 아니며, 잘못 지정해도 경고하지 않습니다.

⚠️ 주의: 잘못된 환경 변수 값 처리

  • 환경 변수 부분 적용 — 잘못된 값을 만나면 환경 변수 읽기를 중단합니다. 이미 적용된 설정은 유지되고, 나머지는 기본값으로 남습니다. 프로세스 실행은 계속됩니다.
  • 읽기 순서 — 환경 변수를 읽는 순서는 정해져 있지 않습니다. 잘못된 값이 있을 때 어떤 설정이 반영될지 알 수 없습니다.
  • 오류 확인 — 환경 변수에서 설정을 읽는 중 오류가 발생하면 Error 레벨 로그를 남깁니다. 설정이 반영되지 않는다면 먼저 이 로그를 확인하십시오.
  • 로거 설정 — 런타임은 환경 변수를 전부 읽은 뒤 로거 설정 적용을 시작합니다. 잘못된 값으로 환경 변수 읽기가 중단되면 HA_LOG_LEVEL, HA_LOG_PATH, HA_LOG_OUTPUT_MODE는 로거에 적용되지 않습니다.

1. 설정 방법

환경 변수는 실행 환경(CLI)에서 지정하거나, 프로그램 초기화 코드에서 setenv()로 설정할 수 있습니다. 둘 다 반드시 첫 Ha* 호출보다 먼저 적용되어 있어야 합니다.

별도의 코드 수정 없이 터미널에서 지정합니다. 실행 전 주입이 보장되므로 가장 안전합니다.

1
HA_LOG_LEVEL=1 HA_HUGE_POOL_THRESHOLD_SIZE_MB=128 ./my_app

코드 내에서 설정하려면 반드시 첫 Ha* 호출 이전에 수행해야 런타임이 정상적으로 읽어들입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#include <cstdlib>

int main() {
  // 반드시 첫 Ha* API 호출 전에 설정해야 함
  setenv("HA_LOG_LEVEL", "1", 1);
  setenv("HA_HUGE_POOL_THRESHOLD_SIZE_MB", "64", 1);

  // 첫 런타임 API 호출 (이 시점에 런타임이 생성되며 환경 변수를 읽음)
  HaSetDevice(0);
  // ...
}

C++과 마찬가지로, 반드시 hart의 첫 API 호출 이전에 설정해야 합니다. import hart 자체는 아직 런타임을 생성하지 않으므로, import 직후에 설정해도 됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import os

# 반드시 첫 hart API 호출 전에 설정해야 함
os.environ["HA_LOG_LEVEL"] = "1"
os.environ["HA_HUGE_POOL_THRESHOLD_SIZE_MB"] = "64"

import hart

# 첫 런타임 API 호출 (이 시점에 런타임이 생성되며 환경 변수를 읽음)
hart.set_device(0)
# ...

2. 환경 변수 상세 항목

메모리

변수 값 기본값 효과
HA_HUGE_POOL_THRESHOLD_SIZE_MB 정수(MB) 0 (꺼짐) 0보다 크면 Large 풀에 Huge 단계를 활성화하고 이 크기를 임계값으로 사용합니다. (Small 풀에는 미적용)
HA_MAX_PAGE_WASTE_RATIO 실수(0.0 ~ 1.0) 0.0 페이지 선택 시 허용할 꼬리 낭비 비율
HA_SMALL_POOL_MIN_SPLIT_REMAINDER_KB 정수(KiB, 0 이상) 512 Small 풀에서 블록을 나눌 때 남는 크기의 최소값. 남는 크기가 이보다 작으면 블록을 나누지 않고 통째로 할당합니다. 32보다 작은 값은 32로 올려 적용되며, 음수는 잘못된 값으로 거부됩니다
HA_DEVICE_MEM_STATS_PRINT 0 또는 1 HA_MEM_STATS_PRINT의 값 1이면 디바이스 메모리 통계를 조회할 때(HaDeviceMemGetStats(), ha_drv_device_mem_get_stats(), Python device_mem_get_stats()) 같은 시점의 통계를 표준 에러에도 출력합니다

메모리 복사

변수 값 기본값 효과
HA_MEMCPYND_PARALLEL_MIN_PER_THREAD 정수(바이트) 2 MiB HaMemCpyNd()의 호스트↔호스트 구간에서 워커 하나가 최소한 처리해야 할 양. 총량이 이보다 작으면 순차 처리합니다
HA_MEMCPYND_PARALLEL_MAX_THREADS 정수 0 (자동) 동일 경로의 워커 수 상한. 0이면 물리 코어 수 기준으로 자동 결정하며 최대 8개까지만 허용합니다
HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES 정수(바이트), 음수는 꺼짐 8 GiB 동기화되지 않은 비동기 N-D 복사 스테이징 버퍼의 합계가 이 값을 넘으면, 새 스테이징 복사가 자기 스트림을 먼저 동기화한 뒤 진행합니다. 거부하지 않으므로 잘못 설정해도 처리량만 달라집니다
HA_MEMCPYND_STAGING_MAX_BYTES 정수(바이트), 음수는 꺼짐 꺼짐 비동기 N-D 복사의 스테이징 버퍼 합계 상한. 넘는 복사는 HaHostMemLimitExceeded로 거부됩니다. HA_HOST_MEM_MAX_BYTES와 함께 설정하면 더 낮은 쪽이 적용되며, HA_HOST_MEM_MAX_BYTES 이상이면 효과가 없다는 경고를 남깁니다. 켜져 있는 HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES보다 작으면 설정 오류로 처리됩니다

기본값은 일반적인 서버를 가정합니다. cgroup으로 CPU가 제한된 컨테이너나 비대칭 토폴로지에서는 HA_MEMCPYND_PARALLEL_MAX_THREADS를 직접 지정하는 편이 낫습니다.

호스트 메모리

프로세스 단위 호스트 메모리 관리자에 적용됩니다. 이 관리자는 런타임 API의 HaHostMemAlloc()과 드라이버 API 호스트 메모리가 함께 쓰며, N-D 복사의 호스트 스테이징 버퍼도 이 관리자에서 할당되므로 함께 영향을 받습니다.

변수 값 기본값 효과
HA_HOST_MEM_MAX_BYTES 정수(바이트), 음수는 꺼짐 꺼짐 프로세스가 OS에서 확보하는 호스트 메모리의 상한. 풀 세그먼트(캐시된 빈 블록 포함)와 풀을 거치지 않는 할당이 모두 포함되며, 넘는 할당은 빈 세그먼트를 반환한 뒤에도 부족하면 HaHostMemLimitExceeded로 거부됩니다
HA_HOST_MEM_STATS_PRINT 0 또는 1 HA_MEM_STATS_PRINT의 값 1이면 호스트 메모리 통계를 조회할 때(HaHostMemGetStats(), ha_drv_host_mem_get_stats(), Python host_mem_get_stats()) 같은 시점의 통계를 표준 에러에도 출력합니다
HA_MEM_STATS_PRINT 0 또는 1 0 (꺼짐) 1이면 호스트와 디바이스 메모리 통계 출력을 함께 켭니다. HA_HOST_MEM_STATS_PRINT나 HA_DEVICE_MEM_STATS_PRINT를 따로 설정하면 그 종류는 개별 설정을 따릅니다

로깅

변수 값 기본값 효과
HA_LOG_LEVEL 정수(0~6) 2(Info); 릴리스 빌드는 3(Warn) 로그 레벨 지정 (0: Trace, 1: Debug, 2: Info, 3: Warn, 4: Error, 5: Critical, 6: Off)
HA_LOG_OUTPUT_MODE 정수(0 또는 1) 0(콘솔) 로그 출력 방식 (0: 콘솔, 1: 파일)
HA_LOG_PATH 경로 ha_runtime.log 로그 파일 저장 경로 (HA_LOG_OUTPUT_MODE=1일 때만 유효)

릴리스 빌드의 최소 로그 레벨 안내

릴리스 빌드에서는 Trace·Debug·Info(0~2) 로그 레벨이 지원되지 않습니다. HA_LOG_LEVEL이 해당 값들로 지정될 시, Warn(3)으로 올려 적용됩니다.

HA_LOG_PATH는 HA_LOG_OUTPUT_MODE=1일 때만 로그 파일의 경로로 사용됩니다. 지정한 로그 파일이 존재하지 않으면 경고가 출력되며, 파일 출력 시 필요한 상위 디렉터리와 로그 파일이 생성됩니다.

프로그램에서 로그 설정을 변경하는 방법은 에러 처리를 참고하십시오. 환경 변수로 설정한 이후 프로그램에서 로그 설정을 변경하면 새 설정이 적용됩니다.

3. 환경 변수로 지정할 수 없는 설정

아래는 환경 변수로 지정할 수 없습니다. API를 쓰십시오.

  • 현재 디바이스: HaSetDevice() / hart.set_device(). 스레드마다 따로 지정되므로 모든 스레드에서 설정합니다.
  • 샘플링 파라미터: HaSetSamplingParams() / hart.set_sampling_params()
  • TLB 초기화: HaInitTlb() / hart.init_tlb()

함께 보기