Garry's Mod (GLua)

Guide d'installation et de configuration du plugin QuantumLogs pour Garry's Mod.

Installation

1. Téléchargez le plugin qlogs_gmod depuis votre espace client
2. Extrayez le dossier dans le répertoire addons/ de votre serveur GMod :

   garrysmod/addons/qlogs_gmod/
   

3. Le plugin se charge automatiquement au démarrage du serveur

Configuration

Éditez le fichier lua/qlogs/sh_config.lua :

-- URL de votre instance QuantumLogs
QLogs.Config.API_URL = "https://votre-instance.quantumlogs.cloud/logs"

-- Votre clé API (trouvable dans votre espace client)
QLogs.Config.API_TOKEN = "votre-cle-api-ici"

-- Intervalle d'envoi des logs (en secondes)
QLogs.Config.SEND_INTERVAL = 10

-- Taille maximum de la file d'attente avant envoi forcé
QLogs.Config.MAX_QUEUE_SIZE = 1000

-- Envoyer les logs même sur les serveurs LAN (utile pour le dev)
QLogs.Config.SEND_ON_LAN = true

-- Mode debug (affiche les messages dans la console)
QLogs.Config.DEBUG = false

Intégrations disponibles

Le plugin GMod dispose de 70+ intégrations configurables. Activez ou désactivez chaque type de log selon vos besoins dans la section QLogs.Config.Integrations :

Logs de base (activés par défaut)

DarkRP (désactivés par défaut)

Mods d'administration

Gamemodes spécifiques

TTT, Murder, Cinema, Sandbox... Chaque gamemode dispose d'intégrations dédiées.

Logs personnalisés (customs)

Vous pouvez envoyer vos propres logs depuis n'importe quel script serveur Lua.

Création d'un log

local point = QLogs.Protocol.Point("mon_measurement")
    :AddPlayer("player", ply)
    :AddField("value", "Description de l'événement")

QLogs.Send(point)

AddPlayer - Noms de préfixe autorisés

La méthode AddPlayer(prefix, player) crée automatiquement des tags à partir du préfixe. Seuls deux préfixes sont reconnus par le backend :

Exemple correct :

-- Kill : l'attaquant est "player", la victime est "target"
local point = QLogs.Protocol.Point("player_kill")
    :AddPlayer("player", attacker)   -- Crée player_name, player_global_id, player_id
    :AddPlayer("target", victim)     -- Crée target_name, target_global_id, target_id
    :AddField("value", attacker:Nick() .. " a tué " .. victim:Nick() .. " avec AK-47")

QLogs.Send(point)

Exemple incorrect :

-- NE PAS FAIRE : "attaquant" n'est pas reconnu par le backend
local point = QLogs.Protocol.Point("player_kill")
    :AddPlayer("attaquant", attacker)   -- Tags ignorés !
    :AddPlayer("victime", victim)       -- Tags ignorés !

AddField - Restrictions

La méthode AddField(key, value) n'accepte que certains types de valeurs :

AddMetadata - Données libres

Pour des données structurées supplémentaires, utilisez AddMetadata :

local point = QLogs.Protocol.Point("player_kill")
    :AddPlayer("player", attacker)
    :AddPlayer("target", victim)
    :AddField("value", attacker:Nick() .. " a tué " .. victim:Nick())
    :AddMetadata("weapon", "AK-47")
    :AddMetadata("distance", 50.5)
    :AddMetadata("headshot", true)

QLogs.Send(point)

Les métadonnées acceptent tout type (strings, nombres, tables, etc.) et sont stockées en JSON. Elles sont visibles dans le détail du log mais ne sont pas filtrables directement.

Système de personnages

Si votre serveur utilise un framework RP (DarkRP, Helix, NutScript...), vous pouvez lier les logs aux personnages des joueurs :

hook.Add("QLogs.GetCharacterID", "MonSysteme", function(ply)
    return ply:GetCharacterID()  -- Adaptez selon votre framework
end)

L'ID du personnage sera stocké dans le champ player_id des logs.

Commandes console

Mode d'envoi

Le plugin supporte deux modes d'envoi :

Mode DLL (haute performance)

Si le module DLL est installé, le plugin l'utilise automatiquement pour :

• Des requêtes HTTP asynchrones sans bloquer Lua
• Un buffer sur disque en cas de panne réseau
• Une file d'attente de 10 000 logs en mémoire

Mode Lua (fallback)

Sans le module DLL, le plugin utilise le module reqwest de Lua pour l'envoi synchrone par lots.

Vérification

Après installation :

1. Démarrez votre serveur GMod
2. Vérifiez dans la console qu'il n'y a pas d'erreur QLogs
3. Connectez-vous au serveur et effectuez quelques actions
4. Vérifiez dans le dashboard QuantumLogs que les logs apparaissent