[Tuto] [dzVents] Passer le log d'un script en mode DEBUG sans modifier le source

Chrominator · Message par **Chrominator** » 02 avr. 2026, 13:04

Petit tuto au sujet du débug des scripts, j'avais cherché le moyen de reproduire une mécanique que j'avais mis en œuvre avant que dzVents n'existe, cherché par moi-même et sur Internet depuis longtemps sans succès.
Certainement que d'autres utilisent cette technique, mais je n'en ai pas trouvé la trace.

Le but est de pouvoir afficher dans le log de domoticz lors de l'exécution d'un script tout ce qui doit être affiché avec le niveau LOG_DEBUG.
Normalement il faut modifier le source et la section logging = { pour y ajouter le niveau d'observation choisi.

On peut l'éviter de la manière suivante :

Il faut définir une fonction de log un peu différente de celle issue de domoticz, et l'appeler en lieu et place de celle de domoticz dans le script.

Ensuite il suffit de mettre le nom du script dans une variable de domoticz pour que tout ce qui est défini avec le niveau LOG_DEBUG s'affiche dans le log.
Mettre nil ou retirer le nom du script dans la variable supprimera le mode débug et les messages ne seront plus affichés.

Note : pas testé avec la version 2026.1

Intérêts :

Tout est géré au niveau de l'interface de domoticz.
Pas nécessaire d'avoir accès au système de fichiers si le source n'est pas dans les évènements de domoticz.
Le timestamp du script source n'est pas modifié (utile pour savoir quand le script a été modifié pour une autre raison que de le passer en LOG_DEBUG).
Passage de plusieurs scripts en mode DEBUG possible par une seule action

Prérequis :

Avoir accès au script domoticz/scripts/dzVents/scripts/global_data.lua
Modifier ce script avec la fonction customLog montrée plus bas ici
Créer un switch virtuel nommé ModeDebug de type On/Off
Créer une variable nommée script_debug de type string initialisée avec la valeur nil
Intégrer l'appel de la fonction customLog dans le ou les scripts sujets du débug
Définir une variable locale SCRIPT_NAME qui servira de marker dans le script sujet du débug
Le niveau doit impérativement être positionné à domoticz.LOG_INFO dans le script qui doit être soumis au mode DEBUG.

Mise en œuvre :

Fonction customLog à ajouter à votre global_data.lua

Code : Tout sélectionner

        customLog = function(dz, scriptName, message, level)
            local switchDebug = dz.devices('ModeDebug')
            local varDebug    = dz.variables('script_debug')
            local isDebug = (switchDebug and switchDebug.active) or (varDebug and string.find(varDebug.value, scriptName) ~= nil)
            level = level or dz.LOG_INFO
            if (level == dz.LOG_DEBUG) then
                if isDebug then
                    dz.log('🛠️ [' .. scriptName .. '] [DEBUG] ' .. message, dz.LOG_INFO)
                end
            elseif (level == dz.LOG_ERROR) then
                dz.log('⚠️error⚠️ [' .. scriptName .. '] ' .. message, level)
            elseif (level == dz.LOG_STATUS) then
                dz.log('✅️ [' .. scriptName .. '] ' .. message, level)
			else
                dz.log('💎 [' .. scriptName .. '] ' .. message, level)
            end
        end,

Variable locale à définir dans chaque script (normalement vous l'avez déjà fait en suivant les tutos ici).
Cette variable doit être déclarée tout au début du script, avant la section return {
Personnellement j'utilise le nom du script sur le système de fichier, mais vous pouvez définir n'importe quel littéral.
Attention de ne pas copier le return ci-dessous dans votre script, il est là pour situer où placer la variable dans le script.
Exemple :
Code : Tout sélectionner
```
local SCRIPT_NAME = string.match(debug.getinfo(1, "S").short_src, "([^\\/]-)$")

return
{
```

Fonction qui redéfini la fonction de log à ajouter dans chaque script juste après le execute = function(domoticz)

Code : Tout sélectionner

        -- Shortcut to log
        local function log(msg, level)
            if domoticz.helpers and domoticz.helpers.customLog then
                domoticz.helpers.customLog(domoticz, SCRIPT_NAME, msg, level)
            else
                domoticz.log(msg, level or domoticz.LOG_INFO)
            end
        end

Ensuite, veillez à remplacer tous les appels d'origine à la fonction domoticz.log de votre script par log tout simplement et les mêmes paramètres (voir exemple ci-dessous).

Tests :

Pour tester la bonne mise en œuvre de ceci, un petit script qui utilise ces fonctions.
On l'appellera test_LOGXXX.lua pour l'exemple.

Code : Tout sélectionner

--[[

	Test LOGXXX to pass script in DEBUG mode without changing the source file 

    2026-04-02  : Initial version
    Author      : chrominator@free.fr
	
    Principle : 	Display various message in domoticz's log with various levels to 
			check log helper's behaviour

--]]    

local SCRIPT_NAME = string.match(debug.getinfo(1, "S").short_src, "([^\\/]-)$")

return
{
    active = true,
    on =
    {
    	timer = {
	"every minute",
	},
    },

    logging = {
        level = domoticz.LOG_INFO,
	marker = SCRIPT_NAME
    },
    
    execute = function(domoticz)
        -- Shortcut to log
        local function log(msg, level)
            if domoticz.helpers and domoticz.helpers.customLog then
                domoticz.helpers.customLog(domoticz, SCRIPT_NAME, msg, level)
            else
                domoticz.log(msg, level or domoticz.LOG_INFO)
            end
        end

	log('Displayed text in log with level LOG_INFO', domoticz.LOG_INFO)
	log('Displayed text in log with level LOG_DEBUG', domoticz.LOG_DEBUG)
	log('Displayed text in log with level LOG_ERROR', domoticz.LOG_ERROR)
	log('Displayed text in log with level LOG_STATUS', domoticz.LOG_STATUS)
    end
}

Si vous vous arrêtez là, vous ne devriez pas voir les messages de niveau LOG_DEBUG des scripts dans le log.
Pour voir ces messages, il faut ajouter le nom du script dont on veut voir les messages à la variable script_debug.

: Capture d'écran 2026-04-02 123125.png (7.97 Kio) Consulté 513 fois

On peut ajouter plusieurs noms de scripts dans cette variable quand on veut en passer plusieurs en mode débug, c'est l'existence de la chaîne spécifiée dans la variable qui servira à passer le script en question dans l'état LOG_DEBUG.
Pour ce faire, on peut initialiser la variable script_debug avec la valeur test_LOGXXX.lua;test_LOGYYY.lua
Les deux scripts passeront en mode debug.

Exemple d'exécution en mode DEBUG de ce script :

: Capture d'écran 2026-04-02 122917.png (16.25 Kio) Consulté 513 fois

Pour arrêter le mode DEBUG d'un script, simplement retirer le nom de la variable script_debug, ou mettre nil si aucun script ne doit être en débug.

Dernière précision. Activer le switch ModeDebug passe tous les scripts en mode DEBUG sans qu'on doive initialiser une valeur dans la variable script_debug.

: Capture d'écran 2026-04-02 123823.png (9.83 Kio) Consulté 513 fois

Je l'utilise rarement, car le log devient très vite illisible...

En espérant que ceci puisse servir.