システム
メモリ使用量、ガベージコレクション統計、CPU詳細、プロセスメタデータを含むランタイムシステム情報のクエリ。
local system = require("system")シャットダウン
Section titled “シャットダウン”終了コード付きでシステムシャットダウンをトリガー。ターミナルアプリに便利。実行中のアクターから呼び出すとシステム全体が終了:
local ok, err = system.exit(0)| パラメータ | 型 | 説明 |
|---|---|---|
code | integer | 終了コード(0 = 成功)、デフォルトは0 |
戻り値: boolean, error
モジュールの一覧
Section titled “モジュールの一覧”メタデータ付きでロード済みのすべてのLuaモジュールを取得:
local mods, err = system.modules()戻り値: table[], error
各モジュールテーブルの内容:
| フィールド | 型 | 説明 |
|---|---|---|
name | string | モジュール名 |
description | string | モジュール説明 |
class | string[] | モジュール分類タグ |
詳細なメモリ統計を取得:
local stats, err = system.memory.stats()戻り値: table, error
統計テーブルの内容:
| フィールド | 型 | 説明 |
|---|---|---|
alloc | number | 割り当てられ使用中のバイト数 |
total_alloc | number | 累積割り当てバイト数 |
sys | number | システムから取得したバイト数 |
heap_alloc | number | ヒープに割り当てられたバイト数 |
heap_sys | number | ヒープ用にシステムから取得したバイト数 |
heap_idle | number | アイドルスパン内のバイト数 |
heap_in_use | number | 非アイドルスパン内のバイト数 |
heap_released | number | OSに解放されたバイト数 |
heap_objects | number | 割り当て済みヒープオブジェクト数 |
stack_in_use | number | スタックアロケータが使用するバイト数 |
stack_sys | number | スタック用にシステムから取得したバイト数 |
mspan_in_use | number | 使用中のmspan構造のバイト数 |
mspan_sys | number | mspan用にシステムから取得したバイト数 |
num_gc | number | 完了したGCサイクル数 |
next_gc | number | 次のGCのターゲットヒープサイズ |
現在の割り当て
Section titled “現在の割り当て”現在割り当てられているバイト数を取得:
local bytes, err = system.memory.allocated()戻り値: number, error
ヒープオブジェクト
Section titled “ヒープオブジェクト”割り当て済みヒープオブジェクト数を取得:
local count, err = system.memory.heap_objects()戻り値: number, error
メモリ制限を設定(以前の値を返す):
local prev, err = system.memory.set_limit(1024 * 1024 * 100)| パラメータ | 型 | 説明 |
|---|---|---|
limit | integer | バイト単位のメモリ制限、無制限は-1 |
戻り値: number, error
現在のメモリ制限を取得:
local limit, err = system.memory.get_limit()戻り値: number, error
GCの強制実行
Section titled “GCの強制実行”ガベージコレクションを強制実行:
local ok, err = system.gc.collect()戻り値: boolean, error
GCターゲットパーセンテージ
Section titled “GCターゲットパーセンテージ”GCターゲットパーセンテージを設定(以前の値を返す)。100の値はヒープが2倍になるとGCがトリガーされることを意味します:
local prev, err = system.gc.set_percent(200)| パラメータ | 型 | 説明 |
|---|---|---|
percent | integer | GCターゲットパーセンテージ |
戻り値: number, error
現在のGCターゲットパーセンテージを取得:
local percent, err = system.gc.get_percent()戻り値: number, error
Goroutine数
Section titled “Goroutine数”アクティブなgoroutine数を取得:
local count, err = system.runtime.goroutines()戻り値: number, error
GOMAXPROCS
Section titled “GOMAXPROCS”GOMAXPROCS値を取得または設定:
-- 現在の値を取得local current, err = system.runtime.max_procs()
-- 新しい値を設定local prev, err = system.runtime.max_procs(4)| パラメータ | 型 | 説明 |
|---|---|---|
n | integer | 指定した場合、GOMAXPROCSを設定(0より大きい必要あり) |
戻り値: number, error
論理CPU数を取得:
local cpus, err = system.runtime.cpu_count()戻り値: number, error
プロセスID
Section titled “プロセスID”現在のプロセスIDを取得:
local pid, err = system.process.pid()戻り値: number, error
システムホスト名を取得:
local hostname, err = system.process.hostname()戻り値: string, error
作業ディレクトリ
Section titled “作業ディレクトリ”ランタイムの現在の作業ディレクトリを取得:
local dir, err = system.process.cwd()戻り値: string, error
プロセスホスト
Section titled “プロセスホスト”ワーカーとキューの統計情報とともにすべてのプロセスホストを一覧:
local hosts, err = system.hosts.list()戻り値: table[], error
各ホストテーブルの内容:
| フィールド | 型 | 説明 |
|---|---|---|
id | string | ホストレジストリID |
workers | number | ワーカープールサイズ |
processes | number | このホスト上のアクティブなプロセス数 |
executed | number | 実行された総ステップ数 |
stolen | number | 他のホストから奪取したステップ数 |
queue_depth | number | ホストキュー内の保留アイテム数 |
特定のホストで実行中のプロセスを一覧:
local procs, err = system.hosts.processes("app:host")| パラメータ | 型 | 説明 |
|---|---|---|
host_id | string | ホストレジストリID |
戻り値: table[], error
各プロセステーブルの内容:
| フィールド | 型 | 説明 |
|---|---|---|
pid | string | プロセスID |
host | string | ホストID |
source | string | ソースエントリID |
state | string | プロセス状態 |
steps | number | 実行されたステップ数 |
started_at | number | 開始タイムスタンプ(ナノ秒) |
parent | string | 親PID(なしの場合は省略) |
actor_id | string | アクターID(なしの場合は省略) |
stats | table | プロセス固有の統計(オプション) |
サービス状態
Section titled “サービス状態”特定の監視対象サービスの状態を取得:
local state, err = system.supervisor.state("namespace:service")| パラメータ | 型 | 説明 |
|---|---|---|
service_id | string | サービスID(例: “namespace:service”) |
戻り値: table, error
状態テーブルの内容:
| フィールド | 型 | 説明 |
|---|---|---|
id | string | サービスID |
status | string | 現在の状態 |
desired | string | 望ましい状態 |
retry_count | number | リトライ回数 |
last_update | number | 最終更新タイムスタンプ(ナノ秒) |
started_at | number | 開始タイムスタンプ(ナノ秒) |
details | string | オプションの詳細(フォーマット済み) |
すべてのサービス状態
Section titled “すべてのサービス状態”すべての監視対象サービスの状態を取得:
local states, err = system.supervisor.states()戻り値: table[], error
各状態テーブルは system.supervisor.state() と同じ形式。
クラスタプリミティブ
Section titled “クラスタプリミティブ”system.node、system.cluster、system.raft、system.lock サブテーブルはクラスタリング層を公開します。クラスタリングが有効な場合に最も役立ちます。スタンドアロンノードでは予測可能な形で機能が制限されます — system.raft.* は “raft not available” を報告し、system.cluster はローカルノードのみを報告し、system.lock はクラスタリングが提供するグローバルレジストリを必要とします。
すべての読み取り呼び出しはローカルかつ安価です: このノードのコミット済み状態のビューを報告し、ネットワークをブロックしません。
ノードアイデンティティ
Section titled “ノードアイデンティティ”system.node はクラスタ内のこのノード自身のアイデンティティを報告します。
local id, err = system.node.id() -- このノードのIDlocal 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。
クラスタメンバーシップ
Section titled “クラスタメンバーシップ”system.cluster はクラスタ全体のビューを報告します: メンバーと誰がリーダーかを報告します。
local members, err = system.cluster.members() -- ノードテーブルの配列local leader, err = system.cluster.leader() -- リーダーノードID、不明な場合は ""local n, err = system.cluster.size() -- 見えているメンバー数system.cluster.members() はノードテーブルの配列を返します。ローカルノードは一度含まれ先頭にソートされます。
| フィールド | 型 | 説明 |
|---|---|---|
id | string | ノードID |
is_local | boolean | 呼び出しノードの場合はtrue |
addr | string | 通知されたアドレス(不明の場合は省略) |
meta | table | 文字列から文字列へのゴシップメタデータ(なしの場合は省略) |
| 関数 | 戻り値 | 備考 |
|---|---|---|
system.cluster.members() | table[], error | メンバーシップ情報に到達できない場合エラー |
system.cluster.leader() | string, error | 現在の Raft リーダーのID。リーダーが不明または Raft が存在しない場合は "" (エラーなし) |
system.cluster.size() | number, error | 見えているメンバー数。メンバーシップ情報が利用できない場合は 0 |
権限: cluster に対する system.read。
Raft状態
Section titled “Raft状態”system.raft はこのノードの Raft コンセンサスコアのローカルビューを読み取ります。このノードで Raft が実行されていない場合、すべての関数は nil, error(“raft not available”)を返します。
local leader, err = system.raft.is_leader() -- booleanlocal 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, error | true, nil 取得成功。false, error 既に保持中(種別 errors.ALREADY_EXISTS)。nil, error 失敗 |
system.lock.release(name) | boolean, error | true, nil 解放成功。false, nil 保持していないか別プロセスが保持中。nil, error 失敗 |
| パラメータ | 型 | 説明 |
|---|---|---|
name | string | クラスタ全体のロック名 |
権限: ロック name に対する system.lock(ポリシーで呼び出し元がロックできる名前を制限できる)。
システム操作はセキュリティポリシー評価の対象。
| アクション | リソース | 説明 |
|---|---|---|
system.read | memory | メモリ統計を読み取り |
system.read | memory_limit | メモリ制限を読み取り |
system.control | memory_limit | メモリ制限を設定 |
system.read | gc_percent | GCパーセンテージを読み取り |
system.gc | gc | ガベージコレクションを強制実行 |
system.gc | gc_percent | GCパーセンテージを設定 |
system.read | goroutines | goroutine数を読み取り |
system.read | gomaxprocs | GOMAXPROCSを読み取り |
system.control | gomaxprocs | GOMAXPROCSを設定 |
system.read | cpu | CPU数を読み取り |
system.read | pid | プロセスIDを読み取り |
system.read | hostname | ホスト名を読み取り |
system.read | cwd | 作業ディレクトリを読み取り |
system.read | hosts | ホスト / ホストプロセスを一覧 |
system.read | modules | ロード済みモジュールを一覧 |
system.read | supervisor | スーパーバイザー状態を読み取り |
system.read | node | このノードのアイデンティティを読み取り |
system.read | cluster | クラスタメンバーシップとリーダーを読み取り |
system.read | raft | Raft 状態を読み取り |
system.read | raft_stats | 生の Raft 統計マップを読み取り |
system.lock | <ロック名> | 分散ロックを取得または解放 |
system.exit | - | システムシャットダウンをトリガー |
| 条件 | 種別 | 再試行可能 |
|---|---|---|
| 権限拒否 | errors.INVALID | no |
| 無効な引数 | errors.INVALID | no |
| 必須引数がない | errors.INVALID | no |
| コードマネージャが利用不可 | errors.INTERNAL | no |
| サービス情報が利用不可 | errors.INTERNAL | no |
| OSエラー (hostname, cwd) | errors.INTERNAL | no |
| このノードで Raft が実行されていない | errors.INTERNAL | no |
| メンバーシップが利用不可 | errors.INTERNAL | no |
| ロックが既に保持中 | errors.ALREADY_EXISTS | no |
エラーの処理についてはエラー処理を参照。