@aventii/metrics (1.0.0)
Installation
@aventii:registry=npm install @aventii/metrics@1.0.0"@aventii/metrics": "1.0.0"About this package
@aventii/metrics
Moteur de métriques commun aux services Aventii.
Ce package fournit un mécanisme générique de collecte et de persistance de métriques pour les microservices Node.js. Il gère les métriques HTTP communes, leur stockage en mémoire et leur écriture dans des fichiers JSON quotidiens.
Les métriques propres au métier d'un service restent définies dans le service concerné.
Installation
Le package est distribué sur le registre npm privé Aventii.
npm install @aventii/metrics
L'accès au registre nécessite une configuration npm Aventii valide.
Utilisation
Création d'une instance
Le package expose createMetrics.
const path = require('path');
const { normalizeRoute } = require('@aventii/http-utils');
const { createMetrics } = require('@aventii/metrics');
const metrics = createMetrics({
directory: path.join(__dirname, 'metrics'),
timezone: 'Europe/Paris',
flushInterval: 5000,
normalizeRoute
});
La fonction normalizeRoute est injectée par le consommateur. Le
package de métriques ne dépend donc d'aucune stratégie particulière de
normalisation des routes.
Un service utilisant des règles spécifiques peut injecter son propre normaliseur configuré.
Métriques HTTP communes
L'instance expose notamment :
metrics.recordError('INVALID_TOKEN');
metrics.incrementIpError(
req.ip,
'INVALID_TOKEN'
);
Les middlewares peuvent être utilisés directement avec Express :
app.use(metrics.incrementIpActivity);
app.use(metrics.responseTimeMiddleware);
Ils permettent notamment de suivre :
- l'activité totale par IP ;
- l'activité par IP et par route normalisée ;
- les erreurs par type ;
- les erreurs par IP ;
- le nombre de requêtes et les temps de réponse par route.
Compteurs propres à un service
Le package fournit increment pour les compteurs simples dont la
signification appartient au service consommateur.
metrics.increment('uploadCount');
metrics.increment('validationCount');
metrics.increment('totalBytes', 2500);
Le package ne connaît pas la signification de ces compteurs. Il assure uniquement leur incrémentation et leur persistance.
Les agrégations métier plus complexes restent implémentées dans le microservice concerné.
Persistance
Les métriques sont conservées en mémoire et écrites dans un fichier JSON quotidien :
metrics/
└── 2026-08-18.json
Les écritures sont bufferisées selon flushInterval.
Au changement de jour, le fichier précédent est sauvegardé et le fichier du nouveau jour est chargé s'il existe déjà.
Un fichier existant est également chargé au démarrage afin de poursuivre les métriques déjà collectées.
API
createMetrics(options)
Crée une instance indépendante du moteur de métriques.
Options
{
directory: String,
timezone: String,
flushInterval: Number,
normalizeRoute: Function
}
directory est obligatoire.
timezone vaut Europe/Paris par défaut.
flushInterval vaut 5000 millisecondes par défaut. La valeur 0
provoque une écriture immédiate.
normalizeRoute reçoit une route et retourne sa représentation
normalisée. Sans fonction fournie, la route est conservée telle quelle.
Méthodes exposées
recordError(type)
incrementIpError(ip, errorType)
incrementIpActivity(req, res, next)
responseTimeMiddleware(req, res, next)
increment(key, amount)
getMetrics()
flush()
close()
flush() force immédiatement l'écriture des métriques.
close() annule un éventuel flush différé, écrit les dernières
métriques et ferme l'instance.
Tests
npm test
Les tests du package couvrent notamment :
- l'incrémentation des compteurs ;
- les erreurs par type et par IP ;
- l'activité par IP et par route ;
- l'injection du normaliseur de routes ;
- les temps de réponse ;
- la persistance et le rechargement des métriques ;
- le comportement face à un fichier de métriques corrompu.
Dependencies
Dependencies
| ID | Version |
|---|---|
| moment-timezone | ^0.6.0 |
Development Dependencies
| ID | Version |
|---|---|
| jest | ^30.0.0 |