📘 Documentation du module xcraft-core-probe

Aperçu

Le module xcraft-core-probe fournit des utilitaires de profilage et de mesure de performance pour l'écosystème Xcraft. Il permet d'enregistrer des événements temporels avec leurs métadonnées dans une base de données SQLite, offrant ainsi un mécanisme de monitoring et d'analyse des performances des applications Xcraft.

Sommaire

- Structure du module
- Fonctionnement global
- Exemples d'utilisation
- Interactions avec d'autres modules
- Variables d'environnement
- Détails des sources

Structure du module

Le module est organisé autour de trois composants principaux :

- lib/probe.js : Classe principale Probe qui gère la base de données SQLite et les mesures de performance
- lib/index.js : Point d'entrée conditionnel qui charge le module seulement si xcraft-core-book est disponible
- probe.js : Commandes Xcraft pour activer/désactiver le profilage via le bus de commandes

Fonctionnement global

Le système de probes fonctionne selon le principe suivant :

1. Initialisation conditionnelle : Le module ne s'active que si xcraft-core-book (SQLite) est disponible et si la variable d'environnement XCRAFT_PROBE est définie
2. Base de données dédiée : Chaque tribu Xcraft possède sa propre base de données de probes (probe-{tribe})
3. Enregistrement par lots : Les événements sont enregistrés par transactions de 10 000 entrées pour optimiser les performances
4. Mesure de delta : Chaque probe peut mesurer le temps écoulé entre son déclenchement et sa finalisation

La structure de données stockée comprend :

- timestamp : Horodatage de l'événement en millisecondes
- delta : Temps écoulé en nanosecondes (optionnel)
- topic : Identifiant du type d'événement
- payload : Données JSON associées à l'événement

Exemples d'utilisation

$3

``javascript
// Activer le profilage
await this.quest.cmd('probe.enable');

// Désactiver le profilage
await this.quest.cmd('probe.disable');
`

$3

`javascript
const xProbe = require('xcraft-core-probe');

// Enregistrer un événement simple
if (xProbe) {
xProbe.push('user.login', {userId: 123, method: 'oauth'});
}

// Mesurer le temps d'exécution d'une opération
if (xProbe) {
const endProbe = xProbe.push('database.query', {
table: 'users',
operation: 'select',
});

// ... exécution de la requête ...

endProbe(); // Enregistre le delta de temps
}
`

$3

`javascript
const xProbe = require('xcraft-core-probe');

async function processData(data) {
const endProbe =
xProbe?.push('data.processing', {
size: data.length,
type: data.type,
}) || (() => {});

try {
// Traitement des données
const result = await heavyProcessing(data);
return result;
} finally {
endProbe(); // Mesure le temps même en cas d'erreur
}
}
`

Interactions avec d'autres modules

Le module interagit avec plusieurs composants de l'écosystème Xcraft :

- [xcraft-core-book] : Fournit l'interface SQLite pour la persistance des données de profilage
- [xcraft-core-etc] : Gestion de la configuration pour déterminer l'emplacement de stockage
- [xcraft-core-host] : Récupération des arguments d'application (notamment la tribu)
- [xcraft-core-bus] : Exposition des commandes d'activation/désactivation sur le bus

Variables d'environnement

| Variable | Description | Exemple | Valeur par défaut |
| -------------- | --------------------------------------------------------- | ---------------- | ----------------------- |
| XCRAFT_PROBE | Active le système de probes si définie et différente de 0 | XCRAFT_PROBE=1 | Non définie (désactivé) |

Détails des sources

$3

Point d'entrée conditionnel qui vérifie la disponibilité de xcraft-core-book. Si le module SQLite n'est pas disponible, retourne null pour désactiver gracieusement le système de probes.

$3

#### Classe Probe

La classe Probe étend SQLite de xcraft-core-book et implémente le système de profilage.

Caractéristiques principales :

- Gestion automatique des transactions par lots (10 000 entrées)
- Base de données dédiée par tribu
- Mode WAL (Write-Ahead Logging) pour optimiser les performances
- Fermeture automatique lors de l'arrêt du processus

#### État et modèle de données

La classe maintient un état interne avec :

- _pushCounter : Compteur d'entrées pour la gestion des transactions
- _disabled : État d'activation du système
- _dbName : Nom de la base de données (format : probe-{tribe})

Structure de la table data :

`sql
CREATE TABLE data (
timestamp TEXT,
delta TEXT,
topic TEXT,
payload JSON
);
`

Index créés pour optimiser les requêtes :

- Index sur timestamp pour les recherches temporelles
- Index sur topic pour filtrer par type d'événement

#### Méthodes publiques

- setEnable(enabled) — Active ou désactive le système de probes. Retourne l'état de disponibilité après l'opération.
- push(topic, payload) — Enregistre un nouvel événement dans la base de données. Retourne une fonction de callback pour mesurer le delta de temps.
- isAvailable() — Vérifie si le système de probes est disponible et activé.
- open() — Ouvre la base de données et initialise les tables et requêtes préparées.
- close() — Ferme la base de données après avoir committé la transaction en cours.

$3

Expose les commandes Xcraft pour contrôler le système de probes via le bus de commandes.

#### Commandes disponibles

- probe.enable — Active le système de probes et affiche l'emplacement de la base de données
- probe.disable` — Désactive le système de probes

Ces commandes sont configurées pour s'exécuter en parallèle et gèrent les cas d'erreur lorsque le module n'est pas disponible.

---

_Ce document a été mis à jour pour refléter l'état actuel du code source._

[xcraft-core-book]: https://github.com/Xcraft-Inc/xcraft-core-book
[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc
[xcraft-core-host]: https://github.com/Xcraft-Inc/xcraft-core-host
[xcraft-core-bus]: https://github.com/Xcraft-Inc/xcraft-core-bus