コンテンツにスキップ

システム

メモリ使用量、ガベージコレクション統計、CPU詳細、プロセスメタデータを含むランタイムシステム情報のクエリ。

local system = require("system")

終了コード付きでシステムシャットダウンをトリガー。ターミナルアプリに便利。実行中のアクターから呼び出すとシステム全体が終了:

local ok, err = system.exit(0)
パラメータ型説明
codeinteger終了コード(0 = 成功)、デフォルトは0

戻り値: boolean, error

メタデータ付きでロード済みのすべてのLuaモジュールを取得:

local mods, err = system.modules()

戻り値: table[], error

各モジュールテーブルの内容:

フィールド型説明
namestringモジュール名
descriptionstringモジュール説明
classstring[]モジュール分類タグ

詳細なメモリ統計を取得:

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

戻り値: table, error

統計テーブルの内容:

フィールド型説明
allocnumber割り当てられ使用中のバイト数
total_allocnumber累積割り当てバイト数
sysnumberシステムから取得したバイト数
heap_allocnumberヒープに割り当てられたバイト数
heap_sysnumberヒープ用にシステムから取得したバイト数
heap_idlenumberアイドルスパン内のバイト数
heap_in_usenumber非アイドルスパン内のバイト数
heap_releasednumberOSに解放されたバイト数
heap_objectsnumber割り当て済みヒープオブジェクト数
stack_in_usenumberスタックアロケータが使用するバイト数
stack_sysnumberスタック用にシステムから取得したバイト数
mspan_in_usenumber使用中のmspan構造のバイト数
mspan_sysnumbermspan用にシステムから取得したバイト数
num_gcnumber完了したGCサイクル数
next_gcnumber次のGCのターゲットヒープサイズ

現在割り当てられているバイト数を取得:

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)
パラメータ型説明
limitintegerバイト単位のメモリ制限、無制限は-1

戻り値: number, error

現在のメモリ制限を取得:

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

戻り値: number, error

ガベージコレクションを強制実行:

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

戻り値: boolean, error

GCターゲットパーセンテージを設定(以前の値を返す)。100の値はヒープが2倍になるとGCがトリガーされることを意味します:

local prev, err = system.gc.set_percent(200)
パラメータ型説明
percentintegerGCターゲットパーセンテージ

戻り値: number, error

現在のGCターゲットパーセンテージを取得:

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

戻り値: number, error

アクティブなgoroutine数を取得:

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

戻り値: number, error

GOMAXPROCS値を取得または設定:

-- 現在の値を取得
local current, err = system.runtime.max_procs()
-- 新しい値を設定
local prev, err = system.runtime.max_procs(4)
パラメータ型説明
ninteger指定した場合、GOMAXPROCSを設定(0より大きい必要あり)

戻り値: number, error

論理CPU数を取得:

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

戻り値: number, error

現在のプロセス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

各ホストテーブルの内容:

フィールド型説明
idstringホストレジストリID
workersnumberワーカープールサイズ
processesnumberこのホスト上のアクティブなプロセス数
executednumber実行された総ステップ数
stolennumber他のホストから奪取したステップ数
queue_depthnumberホストキュー内の保留アイテム数

特定のホストで実行中のプロセスを一覧:

local procs, err = system.hosts.processes("app:host")
パラメータ型説明
host_idstringホストレジストリID

戻り値: table[], error

各プロセステーブルの内容:

フィールド型説明
pidstringプロセスID
hoststringホストID
sourcestringソースエントリID
statestringプロセス状態
stepsnumber実行されたステップ数
started_atnumber開始タイムスタンプ(ナノ秒)
parentstring親PID(なしの場合は省略)
actor_idstringアクターID(なしの場合は省略)
statstableプロセス固有の統計(オプション)

特定の監視対象サービスの状態を取得:

local state, err = system.supervisor.state("namespace:service")
パラメータ型説明
service_idstringサービスID(例: “namespace:service”)

戻り値: table, error

状態テーブルの内容:

フィールド型説明
idstringサービスID
statusstring現在の状態
desiredstring望ましい状態
retry_countnumberリトライ回数
last_updatenumber最終更新タイムスタンプ(ナノ秒)
started_atnumber開始タイムスタンプ(ナノ秒)
detailsstringオプションの詳細(フォーマット済み)

すべての監視対象サービスの状態を取得:

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 はクラスタリングが提供するグローバルレジストリを必要とします。

すべての読み取り呼び出しはローカルかつ安価です: このノードのコミット済み状態のビューを報告し、ネットワークをブロックしません。

system.node はクラスタ内のこのノード自身のアイデンティティを報告します。

local id, err = system.node.id() -- このノードのID
local addr, err = system.node.addr() -- 通知されたネットワークアドレス
local role, err = system.node.role() -- "leader" | "voter" | "standby" | "non-member"
関数戻り値備考
system.node.id()string, errorリレーコンテキストからのノードID
system.node.addr()string, error通知されたアドレス(例: 10.0.0.1:7946)。メンバーシップが利用不可の場合エラー
system.node.role()string, errorこのノードの Raft ロール。Raft が実行されていない場合は "non-member" を返す(エラーなし)

権限: node に対する system.read。

system.cluster はクラスタ全体のビューを報告します: メンバーと誰がリーダーかを報告します。

local members, err = system.cluster.members() -- ノードテーブルの配列
local leader, err = system.cluster.leader() -- リーダーノードID、不明な場合は ""
local n, err = system.cluster.size() -- 見えているメンバー数

system.cluster.members() はノードテーブルの配列を返します。ローカルノードは一度含まれ先頭にソートされます。

フィールド型説明
idstringノードID
is_localboolean呼び出しノードの場合はtrue
addrstring通知されたアドレス(不明の場合は省略)
metatable文字列から文字列へのゴシップメタデータ(なしの場合は省略)
関数戻り値備考
system.cluster.members()table[], errorメンバーシップ情報に到達できない場合エラー
system.cluster.leader()string, error現在の Raft リーダーのID。リーダーが不明または Raft が存在しない場合は "" (エラーなし)
system.cluster.size()number, error見えているメンバー数。メンバーシップ情報が利用できない場合は 0

権限: cluster に対する system.read。

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: 投票ノードまたはスタンバイ
local role, err = system.raft.role() -- system.node.role() と同じ値
local term, err = system.raft.term() -- 現在の Raft ターム
local idx, err = system.raft.commit_index() -- 最高コミット済みログインデックス
local stats, err = system.raft.stats() -- 生の統計マップ(文字列 -> 文字列)
関数戻り値備考
system.raft.is_leader()boolean, errorこのノードが現在のリーダーの場合はtrue
system.raft.is_member()boolean, errorこのノードがコミット済み設定の投票ノードまたはスタンバイの場合はtrue
system.raft.role()string, error"leader" / "voter" / "standby" / "non-member"
system.raft.term()number, error現在のターム。統計から利用できない場合は 0
system.raft.commit_index()number, errorこのノードの最高コミット済みログインデックス
system.raft.stats()table, error完全な生の統計マップ。キーと値は文字列

権限: raft に対する system.read。ただし system.raft.stats() は raft_stats に対する system.read が必要。

system.lock はクラスタ全体の排他制御を提供します。ロックは呼び出しプロセスが所有するグローバルに一意な名前です。Strong 名前スコープ上に構築されているため、クラスタ全体で最大1つの保持者しか存在できません。保持者プロセスが終了またはそのノードが離脱するとロックは自動解放されます — スタックしたロックのクリーンアップは不要です。

local ok, err = system.lock.acquire("orders.migration")
if ok then
-- クリティカルセクション: クラスタ全体で保持者は1つだけ
system.lock.release("orders.migration")
end

取得はフェイルファスト: ロックが既に保持されている場合はブロックせず即座に false を返します。呼び出し側は独自のリトライとバックオフを実装します。現在の保持者のみが解放できます。保持していないロックを解放しても安全なno-opです。

関数戻り値結果
system.lock.acquire(name)boolean, errortrue, nil 取得成功。false, error 既に保持中(種別 errors.ALREADY_EXISTS)。nil, error 失敗
system.lock.release(name)boolean, errortrue, nil 解放成功。false, nil 保持していないか別プロセスが保持中。nil, error 失敗
パラメータ型説明
namestringクラスタ全体のロック名

権限: ロック name に対する system.lock(ポリシーで呼び出し元がロックできる名前を制限できる)。

システム操作はセキュリティポリシー評価の対象。

アクションリソース説明
system.readmemoryメモリ統計を読み取り
system.readmemory_limitメモリ制限を読み取り
system.controlmemory_limitメモリ制限を設定
system.readgc_percentGCパーセンテージを読み取り
system.gcgcガベージコレクションを強制実行
system.gcgc_percentGCパーセンテージを設定
system.readgoroutinesgoroutine数を読み取り
system.readgomaxprocsGOMAXPROCSを読み取り
system.controlgomaxprocsGOMAXPROCSを設定
system.readcpuCPU数を読み取り
system.readpidプロセスIDを読み取り
system.readhostnameホスト名を読み取り
system.readcwd作業ディレクトリを読み取り
system.readhostsホスト / ホストプロセスを一覧
system.readmodulesロード済みモジュールを一覧
system.readsupervisorスーパーバイザー状態を読み取り
system.readnodeこのノードのアイデンティティを読み取り
system.readclusterクラスタメンバーシップとリーダーを読み取り
system.readraftRaft 状態を読み取り
system.readraft_stats生の Raft 統計マップを読み取り
system.lock<ロック名>分散ロックを取得または解放
system.exit-システムシャットダウンをトリガー
条件種別再試行可能
権限拒否errors.INVALIDno
無効な引数errors.INVALIDno
必須引数がないerrors.INVALIDno
コードマネージャが利用不可errors.INTERNALno
サービス情報が利用不可errors.INTERNALno
OSエラー (hostname, cwd)errors.INTERNALno
このノードで Raft が実行されていないerrors.INTERNALno
メンバーシップが利用不可errors.INTERNALno
ロックが既に保持中errors.ALREADY_EXISTSno

エラーの処理についてはエラー処理を参照。