Sistema

El módulo system informa del estado del runtime, memoria, proceso, host, supervisor y clúster. También expone controles seleccionados del runtime.

Esta es una referencia de API. La mayoría de fragmentos muestran una operación aislada; controles como el apagado, los ajustes del runtime y los locks distribuidos requieren autorización explícita de políticas y un tratamiento de errores específico de la aplicación.

Carga

local system = require("system")

Apagado

Solicita el apagado del sistema con un código de salida. Llamar a esta función desde cualquier proceso o actor termina todo el sistema:

local ok, err = system.exit(0)

Devuelve: boolean, error

Listar Módulos

Lista los módulos Lua cargados y sus metadatos:

local mods, err = system.modules()

Devuelve: table[], error

Cada tabla de módulo contiene:

Fuentes de Despliegue

La sub-tabla system.source lee la línea base de despliegue normalizada: el conjunto de entradas producido por las fuentes con las que se ensambló la aplicación, antes de aplicar cualquier historial del registro.

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

Devuelve: table, error

owners viene ordenado con el propietario de la aplicación primero y luego el resto alfabéticamente. El propietario de la aplicación es la cadena "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

La carga se toma de una única generación estable de fuentes, de modo que las entradas y los propietarios siempre describen la misma línea base. Las rutas del sistema de archivos detrás de cada fuente son privadas del runtime y no se exponen; una carga fallida reporta un error interno genérico en vez de filtrar la ruta subyacente.

Permiso: system.read sobre sources

Estadísticas de Memoria

Obtener estadísticas detalladas de memoria:

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

Devuelve: table, error

La tabla de estadísticas contiene:

Asignación Actual

Obtener los bytes actualmente asignados:

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

Devuelve: number, error

Objetos del Heap

Obtener el número de objetos de heap asignados:

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

Devuelve: number, error

Límite de Memoria

Establecer el límite de memoria (devuelve el valor anterior):

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

Devuelve: number, error

Obtener el límite de memoria actual:

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

Devuelve: number, error

Forzar GC

Forzar la recolección de basura:

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

Devuelve: boolean, error

Porcentaje Objetivo del GC

Establecer el porcentaje objetivo del GC (devuelve el valor anterior). Un valor de 100 significa que el GC se activa cuando el heap se duplica:

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

Devuelve: number, error

Obtener el porcentaje objetivo del GC actual:

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

Devuelve: number, error

Recuento de Goroutines

Obtener el número de goroutines activas:

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

Devuelve: number, error

GOMAXPROCS

Obtener o establecer el valor de GOMAXPROCS mediante el selector gomaxprocs:

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

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

Devuelve: number, error

Recuento de CPUs

Obtener el número de CPUs lógicas:

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

Devuelve: number, error

ID de Proceso

Obtener el ID del proceso actual:

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

Devuelve: number, error

Hostname

Obtener el hostname del sistema:

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

Devuelve: string, error

Directorio de Trabajo

Obtener el directorio de trabajo actual del runtime:

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

Devuelve: string, error

Hosts de Proceso

Listar todos los hosts de proceso con estadísticas de workers y colas:

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

Devuelve: table[], error

Cada tabla de host contiene:

Listar procesos ejecutándose en un host específico:

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

Devuelve: table[], error

Cada tabla de proceso contiene:

Estado del Servicio

Obtener el estado de un servicio supervisado específico:

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

Devuelve: table, error

La tabla de estado contiene:

Todos los Estados de Servicios

Obtener los estados de todos los servicios supervisados:

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

Devuelve: table[], error

Cada tabla de estado tiene el mismo formato que system.supervisor.state().

Primitivas del clúster

Las sub-tablas system.node, system.cluster, system.raft y system.lock exponen la capa de clustering. Son más útiles cuando el clustering está habilitado; en un nodo independiente degradan de forma predecible — system.raft.* reporta "raft not available", system.cluster reporta solo el nodo local, y system.lock requiere el almacén KV respaldado por Raft que proporciona el clustering.

Las llamadas de lectura informan de la vista local del estado confirmado de este nodo y no bloquean en la red.

Identidad del nodo

system.node reporta la propia identidad de este nodo en el cluster.

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"

Permiso: system.read sobre node.

Membresía del cluster

system.cluster informa de los miembros del clúster y del líder actual.

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() devuelve un array de tablas de nodo. El nodo local se incluye una vez y aparece primero.

Permiso: system.read sobre cluster.

Estado de Raft

system.raft lee la vista local de este nodo del núcleo de consenso Raft. Cada función devuelve nil, error ("raft not available") cuando Raft no está ejecutándose en este nodo.

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)

Permiso: system.read sobre raft, excepto system.raft.stats() que requiere system.read sobre raft_stats.

Bloqueos distribuidos

system.lock proporciona exclusión mutua a nivel de cluster. Un bloqueo es un nombre globalmente único propiedad del proceso que llama. Está construido sobre el almacén KV del sistema replicado por Raft, por lo que puede existir como máximo un titular en todo el cluster, y el bloqueo se libera automáticamente cuando el proceso titular sale o su nodo se va — no hay bloqueo atascado que limpiar.

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

La adquisición es fail-fast: cuando el lock ya está tomado, la llamada devuelve false inmediatamente en lugar de bloquear. Los callers proporcionan las políticas de retry y backoff necesarias. Solo el holder actual puede liberar un lock; un intento de liberación por otro proceso es un no-op.

Permiso: system.lock sobre el name del bloqueo (de modo que la política puede restringir qué nombres puede bloquear un caller).

Permisos

Las operaciones del sistema están sujetas a evaluación de política de seguridad.

Errores

Consulte Manejo de Errores para trabajar con errores.