시스템

system 모듈은 런타임, 메모리, 프로세스, 호스트, 슈퍼바이저, 클러스터 상태를 보고하고 일부 런타임 제어를 제공합니다.

이 페이지는 API 레퍼런스입니다. 대부분의 조각은 독립된 작업 하나를 보여 줍니다. 셧다운, 런타임 튜닝, 분산 잠금 같은 제어에는 명시적 정책 권한과 애플리케이션별 오류 처리가 필요합니다.

로딩

local system = require("system")

셧다운

종료 코드와 함께 시스템 셧다운 트리거. 터미널 앱에 유용합니다; 실행 중인 액터에서 호출하면 전체 시스템이 종료됩니다:

local ok, err = system.exit(0)

반환: boolean, error

모듈 목록 조회

메타데이터와 함께 로드된 모든 Lua 모듈 가져오기:

local mods, err = system.modules()

반환: table[], error

각 모듈 테이블에는 다음이 포함됩니다:

배포 소스

system.source 하위 테이블은 정규화된 배포 베이스라인, 즉 레지스트리 히스토리가 적용되기 전에 애플리케이션이 조립된 소스들이 만들어낸 엔트리 집합을 읽습니다.

local loaded, err = system.source.load()

반환: table, error

owners는 애플리케이션 소유자가 먼저 오고 나머지 소유자가 알파벳순으로 정렬됩니다. 애플리케이션 소유자는 문자열 "application"입니다.

local loaded, err = system.source.load()
if err then return nil, err end

for _, owner in ipairs(loaded.owners) do
    print(owner)
end

for _, entry in ipairs(loaded.entries) do
    print(entry.id, entry.kind)
end

로드는 하나의 안정된 소스 세대에서 가져오므로 엔트리와 소유자는 항상 동일한 베이스라인을 기술합니다. 각 소스 뒤의 파일시스템 경로는 런타임 내부용이며 노출되지 않습니다. 로드가 실패하면 백킹 경로를 노출하는 대신 일반적인 내부 에러를 보고합니다.

권한: sources에 대한 system.read

메모리 통계

상세 메모리 통계 가져오기:

local stats, err = system.memory.stats()

반환: table, error

통계 테이블 내용:

현재 할당량

현재 할당된 바이트 가져오기:

local bytes, err = system.memory.allocated()

반환: number, error

힙 객체

할당된 힙 객체 수 가져오기:

local count, err = system.memory.heap_objects()

반환: number, error

메모리 제한

메모리 제한 설정 (이전 값 반환):

local prev, err = system.memory.set_limit(1024 * 1024 * 100)

반환: number, error

현재 메모리 제한 가져오기:

local limit, err = system.memory.get_limit()

반환: number, error

GC 강제 실행

가비지 컬렉션 강제 실행:

local ok, err = system.gc.collect()

반환: boolean, error

GC 대상 비율

GC 대상 비율 설정 (이전 값 반환). 값 100은 힙이 두 배가 될 때 GC가 트리거됨을 의미합니다:

local prev, err = system.gc.set_percent(200)

반환: number, error

현재 GC 대상 비율 가져오기:

local percent, err = system.gc.get_percent()

반환: number, error

고루틴 수

활성 고루틴 수 가져오기:

local count, err = system.runtime.goroutines()

반환: number, error

GOMAXPROCS

GOMAXPROCS 값 가져오기 또는 설정:

-- Get current value
local current, err = system.runtime.max_procs()

-- Set new value
local prev, err = system.runtime.max_procs(4)

반환: number, error

CPU 수

논리 CPU 수 가져오기:

local cpus, err = system.runtime.cpu_count()

반환: number, error

프로세스 ID

현재 프로세스 ID 가져오기:

local pid, err = system.process.pid()

반환: number, error

호스트명

시스템 호스트명 가져오기:

local hostname, err = system.process.hostname()

반환: string, error

작업 디렉토리

런타임의 현재 작업 디렉토리 가져오기:

local dir, err = system.process.cwd()

반환: string, error

프로세스 호스트

워커 및 큐 통계와 함께 모든 프로세스 호스트 목록 조회:

local hosts, err = system.hosts.list()

반환: table[], error

각 호스트 테이블 내용:

특정 호스트에서 실행 중인 프로세스 목록 조회:

local procs, err = system.hosts.processes("app:host")

반환: table[], error

각 프로세스 테이블 내용:

서비스 상태

특정 감독된 서비스의 상태 가져오기:

local state, err = system.supervisor.state("namespace:service")

반환: table, error

상태 테이블 내용:

모든 서비스 상태

모든 감독된 서비스의 상태 가져오기:

local states, err = system.supervisor.states()

반환: table[], error

각 상태 테이블은 system.supervisor.state()와 같은 형식입니다.

클러스터 프리미티브

system.node, system.cluster, system.raft, system.lock 서브 테이블은 클러스터링 레이어를 노출합니다. 클러스터링이 활성화된 경우에 가장 유용합니다; 독립 노드에서는 예측 가능하게 저하됩니다 — system.raft.*는 "raft not available"을 보고하고, system.cluster는 로컬 노드만 보고하며, system.lock은 클러스터링이 제공하는 Raft 기반 KV 스토어가 필요합니다.

모든 읽기 호출은 로컬이고 저렴합니다: 커밋된 상태에 대한 이 노드의 뷰를 보고하며, 네트워크를 차단하지 않습니다.

노드 정체성

system.node는 클러스터에서 이 노드 자체의 정체성을 보고합니다.

local id, err = system.node.id()      -- this node's ID
local addr, err = system.node.addr()  -- advertised network address
local role, err = system.node.role()  -- "leader" | "voter" | "standby" | "non-member"

권한: node에 대한 system.read.

클러스터 멤버십

system.cluster는 클러스터 전체 뷰를 보고합니다: 멤버가 누구이고 누가 리더인지.

local members, err = system.cluster.members()  -- array of node tables
local leader, err = system.cluster.leader()    -- leader node ID, or "" if unknown
local n, err = system.cluster.size()           -- count of visible members

system.cluster.members()는 노드 테이블 배열을 반환합니다. 로컬 노드가 한 번 포함되고 먼저 정렬됩니다.

권한: cluster에 대한 system.read.

Raft 상태

system.raft는 Raft 합의 코어에 대한 이 노드의 로컬 뷰를 읽습니다. 이 노드에서 Raft가 실행 중이 아니면 모든 함수가 nil, error("raft not available")를 반환합니다.

local leader, err = system.raft.is_leader()      -- boolean
local member, err = system.raft.is_member()      -- boolean: voter or standby
local role, err = system.raft.role()             -- same values as system.node.role()
local term, err = system.raft.term()             -- current Raft term
local idx, err = system.raft.commit_index()      -- highest committed log index
local stats, err = system.raft.stats()           -- raw stats map (string -> string)

권한: raft에 대한 system.read, system.raft.stats()는 raft_stats에 대한 system.read 필요.

분산 잠금

system.lock은 클러스터 전체 상호 배제를 제공합니다. 잠금은 호출 프로세스가 소유한 전역 고유 이름입니다. Raft로 복제되는 시스템 KV 스토어 위에 구축되어 클러스터 전체에 최대 하나의 보유자만 존재할 수 있으며, 보유자 프로세스가 종료되거나 해당 노드가 떠나면 잠금이 자동으로 해제됩니다 — 정리할 고착된 잠금이 없습니다.

local ok, err = system.lock.acquire("orders.migration")
if not ok then
  -- err has kind errors.ALREADY_EXISTS when another process holds the lock.
  -- Apply the caller's retry and backoff policy for that case if needed.
  return nil, err
end

-- critical section: only one holder cluster-wide
local released, release_err = system.lock.release("orders.migration")
if release_err then
  return nil, release_err
end
return released

획득은 실패-즉시 방식입니다: 잠금이 이미 보유 중이면 차단하는 대신 즉시 false를 반환하므로 호출자가 자체 재시도와 백오프를 구현합니다. 현재 보유자만 해제할 수 있습니다; 보유하지 않은 잠금을 해제하는 것은 안전한 no-op입니다.

권한: 잠금 name에 대한 system.lock (따라서 정책이 호출자가 잠글 수 있는 이름을 제한할 수 있음).

권한

시스템 작업은 보안 정책 평가 대상입니다.

에러

에러 처리는 에러 처리를 참조하세요.