Module `alemca`

Le module alemca permet d'interagir avec le service Alemca. Il s'agit d'un module par défaut nommé alemca. Il expose plusieurs fonctions pour écrire des messages, compresser des données, gérer les connexions et manipuler des commandes.

Pour l'importer il faut utiliser la déclaration suivante :

local alemca = require("alemca")

Configuration

Le module alemca nécessite une configuration spécifique pour fonctionner. Cette configuration est définie dans le fichier de configuration de l'agent.

Pour la configuration voici un exemple de toutes les options possibles :

iot:
  alemca: # configuration de la connexion à alemca
    max_cache_size: 1024 # taille maximum du cache en octets
    destinations: # destinations des messages
      - name: "destination_name" # nom de la destination
        exchange: "destination_name" # nom de l'échange
        routing_key: "destination_name" # clé de routage
        queue_not_durable: false # file non durable
        exchange_type: "direct" # type d'échange

Détails de la configuration

max_cache_size : Taille maximum du cache en octets. Si le cache dépasse cette taille, les messages les plus anciens seront supprimés.
destinations : Liste des destinations des messages. Chaque destination doit avoir un nom, un échange, une clé de routage, et d'autres options comme la durabilité de la file et le type d'échange.
name : Nom de la destination. Utilisé pour identifier la destination dans le code Lua.
exchange : Nom de l'échange. Utilisé pour publier des messages.
routing_key : Clé de routage. Utilisée pour diriger les messages vers la bonne file d'attente.
queue_not_durable : Indique si la file d'attente est non durable. Si true, la file d'attente ne sera pas persistée après un redémarrage.
exchange_type : Type d'échange. Peut être direct, fanout, topic, ou headers. Définit comment les messages sont routés vers les files d'attente.

Fonctions Lua

Tableau des fonctions

Fonction	Signature Lua	Rôle	Retour (succès)	Retour (échec)
`write`	`bool, err = alemca.write(routingKey, payload [, headers])`	Publie immédiatement `payload` sur la queue `routingKey` (exchange et routingKey identiques).	`true, nil`	`nil, "msg"`
`writebatch`	`bool, err = alemca.writebatch(payload)`	Ajoute `payload` au cache disque `amqp.cache`.	`true, nil`	`nil, "msg"`
`sendbatch`	`bool, err = alemca.sendbatch(routingKey [, unique=false [, compress=false [, headers]]])`	Vide le cache sur `routingKey`. `unique=true` : envoie ligne par ligne. `compress=true` : gzip.	`true, nil`	`nil, "msg"`
`compress`	`compressed, err = alemca.compress(str)`	Retourne `str` compressé (gzip + base64).	`string, nil`	`nil, "msg"`
`status`	`connected, err = alemca.status()`	Vérifie la connexion AMQP.	`true, nil`	`false, "msg"`
`getbatch`	`len, err = alemca.getbatch()`	Nombre de lignes dans `amqp.cache`.	`n, nil`	`nil, "msg"`
`clearbatch`	`bool, err = alemca.clearbatch()`	Purge le cache.	`true, nil`	`nil, "msg"`
`read`	`msg, err = alemca.read(queueName)`	Bloque max 5 s et renvoie le prochain message de `queueName`.	`string, nil`	`nil, "msg"`
`read (ack)`	`msg, tag, err = alemca.read(queueName, true)`	Lit un message avec accusé de réception différé.	`string, tag, nil`	`nil, nil, "msg"`
`ack`	`bool, err = alemca.ack(tag)`	Accuse réception d’un message précédemment lu.	`true, nil`	`nil, "msg"`
`nack`	`bool, err = alemca.nack(tag [, requeue])`	Rejette un message, avec ou sans réinjection dans la file.	`true, nil`	`nil, "msg"`
`writemetrics`	`err = alemca.writemetrics(metrics [, types [, units [, tags [, ident]]]])`	Convertit la table `metrics` en JSON et l’écrit dans `metrics.cache`.	`nil`	`"msg"`
`pushmetrics`	`err = alemca.pushmetrics()`	Envoie le contenu de `metrics.tmp` vers `data_metrics_ex`.	`nil`	`"msg"`
`newcommand`	`bool, err = alemca.newcommand(cmdTable)`	Planifie l’exécution différée d’un script (Lua) distant.	`true, nil`	`nil, "msg"`
`get_entity`	`entity, err = alemca.get_entity([ident])`	Récupère l’entité Core.	`luaTable, nil`	`nil, "msg"`
`get_children`	`children, err = alemca.get_children([ident])`	Récupère les enfants d’une entité.	`luaTable, nil`	`nil, "msg"`
`get_attribute`	`attrs, err = alemca.get_attribute([ident])`	Récupère les attributs d’une entité.	`luaTable, nil`	`nil, "msg"`
`get_config`	`cfg, err = alemca.get_config([ident])`	Récupère la configuration d’une entité.	`luaTable, nil`	`nil, "msg"`
Champs	`alemca.ident`, `alemca.token`, `alemca.name`, `alemca.type`	Accès direct aux métadonnées chargées.	–	–

`alemca.write(routing_key, message[, headers])`

Publie un message à Alemca.

Paramètres :
routing_key (string) : La clé de routage pour le message. ()
message (string) : Le message à envoyer.
headers (table, optionnel) : Un tableau contenant des en-têtes supplémentaires pour le message.
Retour :
true si l'envoi est réussi, sinon retourne une erreur.

local ok, err = alemca.write("uc.raw.temp", '{"t":25.4,"u":"°C"}')
assert(ok, err)

`alemca.writebatch(message [, batchName])`

Écrit un lot de messages dans le cache. Sépare les messages par des retours à la ligne. Si le cache dépasse la taille maximale, les messages les plus anciens sont supprimés.

Paramètres :
message (string) : Le message à ajouter au cache.
batchName (string, optionnel) : Nom du lot de messages. Si non spécifié, le nom par défaut est utilisé (amq.cache).
Retour :
true si l'écriture est réussie, sinon retourne une erreur.

alemca.writebatch('{"ts":1680000000,"v":12}')
alemca.writebatch('{"ts":1680000005,"v":13}', "temp_batch.cache")

-- plus tard …
local ok, err = alemca.sendbatch("uc.raw.series", false, true)
assert(ok, err)

`alemca.sendbatch(routing_key[, send_mode[, compress_mode[, headers [, batchName]]]])`

Envoie un lot de messages à Alemca.

Paramètres :
routing_key (string) : La clé de routage pour les messages.
send_mode (boolean, optionnel) : Si true, tous les messages du cache sont envoyés en un a un ; sinon, ils sont envoyés en une seule fois (séparé par un retour a la ligne) (défaut : false).
compress_mode (boolean, optionnel) : Si true, les messages sont compressés avant l'envoi (défaut : false).
headers (table, optionnel) : Un tableau d'en-têtes supplémentaires pour les messages.
batchName (string, optionnel) : Nom du lot de messages. Si non spécifié, le nom par défaut est utilisé (amq.cache).
Retour :
true si l'envoi est réussi, sinon retourne une erreur.

alemca.writebatch('{"ts":1680000000,"v":12}')
alemca.writebatch('{"ts":1680000005,"v":13}', "temp_batch.cache")

-- plus tard …
local ok, err = alemca.sendbatch("uc.raw.series", true)
assert(ok, err)

-- plus tard …
local ok, err = alemca.sendbatch("uc.raw.series", false, true, nil, "temp_batch.cache")
assert(ok, err)

`alemca.compress(message)`

Compresse un message en utilisant l'algorithme GZIP.

Paramètres :
message (string) : Le message à compresser.
Retour :
Le message compressé ou une erreur.

`alemca.status()`

Retourne le statut de la connexion à Alemca.

Paramètres : Aucun
Retour :
true si connecté, sinon retourne une erreur.

`alemca.getbatch()`

Retourne la longueur du lot de messages en cache.

Paramètres : Aucun
Retour :
La longueur du lot ou une erreur.

`alemca.clearbatch()`

Efface le lot de messages en cache.

Paramètres : Aucun
Retour :
true si l'effacement est réussi, sinon retourne une erreur.

`alemca.read(routing_key[, ack])`

Lit un message depuis Alemca.

Paramètres :
routing_key (string) : La clé de routage du message à lire.
ack (boolean, optionnel) : Si true, retourne un tag pour pouvoir "ack" le message après traitement. Si false ou omis, le message est lu sans accusé de réception.
Retour :
Mode simple : message, nil
Mode ack : message, tag, nil
Échec : nil, "msg" (ou 3e valeur en mode ack)

local msg, err = alemca.read("alerts")
if msg then
  print("ALERT:", msg)
else
  print("no alert:", err)
end

Mode ack:

local msg, tag, err = alemca.read("alerts", true)
if msg then
  print("ALERT:", msg)
else
  print("no alert:", err)
end

alemca.ack(tag) -- accuse réception du message

`alemca.ack(tag)`

Accuse réception d'un message précédemment lu.

Paramètres :
tag (string) : Le tag du message à accuser réception.
Retour :
status ou une erreur.

local tag = "12345" -- tag obtenu lors de la lecture du message
local ok, err = alemca.ack(tag)
assert(ok, err)

`alemca.nack(tag)`

Accuse réception d'un message précédemment lu, mais indique qu'il n'a pas été traité correctement.

Paramètres :
tag (string) : Le tag du message à accuser réception.
Retour :
status ou une erreur.

local tag = "12345" -- tag obtenu lors de la lecture du message
local ok, err = alemca.nack(tag)
assert(ok, err)

`alemca.writemetrics(metrics[, types[, units[, tags[, ident]]]])`

Écrit des métriques dans le cache.

Paramètres :
metrics (table) : Un tableau contenant les métriques.
types (table, optionnel) : Un tableau indiquant les types de métriques.
units (table, optionnel) : Un tableau indiquant les unités de chaque métrique.
tags (table, optionnel) : Un tableau de tags optionnels à inclure.
ident (string, optionnel) : L'identifiant à utiliser (par défaut, celui de l'instance Alemca).
Retour :
true si l'écriture est réussie, sinon retourne une erreur.

alemca.writemetrics(
  {
    { cpu_usage = 75 },
    { memory_usage = 2048 },
    { disk_space = 50000 }
  },
  {
    { cpu_usage = "percent" },
    { memory_usage = "MB" },
    { disk_space = "MB" }
  },
  { 
    cpu_usage = "percent",
    memory_usage = "MB",
    disk_space = "MB"
  },
  { environment = "production", region = "us-west" }
)

`alemca.pushmetrics()`

Force l'envoie les métriques depuis le cache vers Alemca. Sinon elles sont envoyées automatiquement à intervalle régulier.

Paramètres : Aucun
Retour :
true si l'envoi est réussi, sinon retourne une erreur.

`alemca.newcommand(command)`

Crée une nouvelle commande pour Alemca.

Paramètres :
command (table) : Un tableau représentant la commande à exécuter. Les champs requis incluent script, job_ident, variables, constants, attributes, scheduled_time, et expire_time.
Retour :
true si la commande est créée avec succès, sinon retourne une erreur.

local cmd = {
  script = "reboot.lua",
  job_ident = "reboot-2025-04-30-02h",
  variables = { delay = 10 },
  constants = {},
  attributes = { reason = "nightly-maintenance" },
  scheduled_time = os.time() + 3600,   -- dans 1 h
  expire_time = os.time() + 86400,     -- invalide après 24 h
  cancel = ""
}

local ok, err = alemca.newcommand(cmd)
assert(ok, err)

`alemca.get_entity([ident])`

Récupère l'entité Core.

Paramètres :
ident (string, optionnel) : L'identifiant de l'entité à récupérer. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.
Retour :
Un tableau Lua représentant l'entité.
nil et un message d'erreur en cas d'échec.

local entity, err = alemca.get_entity("my_entity")
if entity then
  print("Entity:", entity.name)
else
  print("Error:", err)
end

`alemca.get_children([ident])`

Récupère les enfants de l'entité Core.

Paramètres :
ident (string, optionnel) : L'identifiant de l'entité dont on veut récupérer les enfants. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.
Retour :
Un tableau Lua contenant les enfants de l'entité.
nil et un message d'erreur en cas d'échec.

local children, err = alemca.get_children("my_entity")

if children then
  for _, child in ipairs(children) do
    print("Child:", child.name)
  end
else
  print("Error:", err)
end

`alemca.get_attribute([ident])`

Récupère les attributs de l'entité Core.

Paramètres :
ident (string, optionnel) : L'identifiant de l'entité dont on veut récupérer les attributs. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.
Retour :
Un tableau Lua contenant les attributs de l'entité.
nil et un message d'erreur en cas d'échec.

local attrs, err = alemca.get_attribute("my_entity")
if attrs then
  for key, value in pairs(attrs) do
    print("Attribute:", key, "=", value)
  end
else
  print("Error:", err)
end

`alemca.get_config([ident])`

Récupère la configuration de l'entité Core.

Paramètres :
ident (string, optionnel) : L'identifiant de l'entité dont on veut récupérer la configuration. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.
Retour :
Un tableau Lua contenant la configuration de l'entité.
nil et un message d'erreur en cas d'échec.

local cfg, err = alemca.get_cconfig("my_entity")
if cfg then
  for key, value in pairs(cfg) do
    print("Config:", key, "=", value)
  end
else
  print("Error:", err)
end

Champs Lua associés

alemca.ident : Retourne l'identifiant de l'instance Alemca.
alemca.token : Retourne le token de l'instance Alemca.
alemca.name : Retourne le nom de l'instance Alemca.
alemca.type : Retourne le type de l'instance Alemca, contante a alemca.

Module alemca

Configuration

Détails de la configuration

Fonctions Lua

Tableau des fonctions

alemca.write(routing_key, message[, headers])

alemca.writebatch(message [, batchName])

alemca.sendbatch(routing_key[, send_mode[, compress_mode[, headers [, batchName]]]])

alemca.compress(message)

alemca.status()

alemca.getbatch()

alemca.clearbatch()

alemca.read(routing_key[, ack])

alemca.ack(tag)

alemca.nack(tag)

alemca.writemetrics(metrics[, types[, units[, tags[, ident]]]])

alemca.pushmetrics()

alemca.newcommand(command)

alemca.get_entity([ident])

alemca.get_children([ident])

alemca.get_attribute([ident])

alemca.get_config([ident])