📊 @pixelpoule/monitoring

Package de monitoring automatique pour les instances Pixel Poule.

Envoie automatiquement les logs, erreurs et métriques de performance au Dashboard Admin centralisé.

🚀 Installation

npm install @pixelpoule/monitoring

⚙️ Configuration

1. Variables d'environnement

Ajoutez ces variables dans votre fichier .env.local (local) et dans Netlify (production) :

# Monitoring Dashboard Admin
ADMIN_MONITORING_ENABLED=true
ADMIN_DASHBOARD_URL=https://votre-dashboard.netlify.app
ADMIN_INSTANCE_ID=votre-instance-id
ADMIN_INSTANCE_SECRET=votre-instance-secret

💡 L'ADMIN_INSTANCE_ID et ADMIN_INSTANCE_SECRET vous sont fournis lors de la création de l'instance dans le Dashboard Admin.

⚠️ Important : Le middleware automatique ne fonctionne pas correctement

Le middleware createMonitoringMiddleware() a des limitations techniques avec Next.js :

• Il s'exécute AVANT les routes API, pas AUTOUR
• Il ne peut pas capturer les erreurs internes ni les vraies performances
• Ne pas utiliser pour le moment

Utilisez plutôt withMonitoring() dans vos routes API (voir ci-dessous).

📝 Utilisation

Méthode recommandée : withMonitoring() dans les routes API

Utilisez withMonitoring() pour capturer automatiquement les performances ET les erreurs :

import { withMonitoring, sendLog } from '@pixelpoule/monitoring';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  return withMonitoring(
    'processDocument',
    async () => {
      try {
        const body = await request.json();
        
        // Votre logique métier ici
        const result = await processMyData(body);

        return NextResponse.json({ success: true, result });
      } catch (error: any) {
        // Envoyer une erreur détaillée au Dashboard
        sendLog({
          type: 'api_error',
          severity: 'critical',
          message: error.message,
          context: {
            endpoint: '/api/process-document',
            component: 'DocumentProcessor',
            documentId: body?.documentId,
          },
          stackTrace: error.stack,
        });

        return NextResponse.json(
          { error: error.message },
          { status: 500 }
        );
      }
    },
    { endpoint: '/api/process-document' }
  );
}

Logs manuels pour plus de contrôle

Envoyez des logs personnalisés n'importe où dans votre code :

import { sendLog } from '@pixelpoule/monitoring';

// Log d'info
sendLog({
  type: 'info',
  severity: 'info',
  message: 'Document traité avec succès',
  context: {
    documentId: '123',
    userId: 'user-456',
  },
});

// Log d'erreur
sendLog({
  type: 'system_error',
  severity: 'critical',
  message: 'Échec de connexion à la base de données',
  context: {
    component: 'DatabaseService',
    action: 'connect',
  },
  stackTrace: error.stack,
});

📊 Ce qui est surveillé automatiquement

Avec withMonitoring() :

• ✅ Erreurs : Toute exception levée est envoyée au Dashboard
• ✅ Performance : Temps d'exécution de chaque requête
• ✅ Status codes : Réussite (200) ou erreur (500)

Avec le middleware :

• ✅ Toutes les routes API : /api/*
• ✅ Performance globale : Temps de réponse de chaque endpoint
• ✅ Méthodes HTTP : GET, POST, PUT, DELETE, etc.

🎯 Types disponibles

import type {
  LogWebhookPayload,
  PerformanceWebhookPayload,
  LogSeverity,
  LogType,
} from '@pixelpoule/monitoring';

LogSeverity

type LogSeverity = 'info' | 'warning' | 'error' | 'critical';

LogType

type LogType = 'api_error' | 'system_error' | 'validation_error' | 'auth_error' | 'info';

🔒 Sécurité

• Les requêtes vers le Dashboard sont authentifiées avec X-Instance-ID et X-Instance-Secret
• Le monitoring est silencieux : aucune erreur de monitoring ne bloque votre application
• Timeout de 5 secondes sur chaque requête de monitoring

📦 Build du package

Si vous modifiez le package :

npm run build

📄 Licence

ISC © Pixel Poule