traffic-monitor-mqtt/README.md

Zentrales Traffic Monitoring via MQTT für Node.js Anwendungen

# traffic-monitor-mqtt

MQTT-basiertes Traffic-Monitoring für Node.js Anwendungen.

## Installation

```bash
npm install traffic-monitor-mqtt
```

## Verwendung

### Basis-Setup

```javascript
const { TrafficMonitor } = require('traffic-monitor-mqtt');

// Debug-Logs aktivieren (optional aber empfohlen)
process.env.DEBUG = 'traffic-monitor:*';

const monitor = new TrafficMonitor({
  mqtt: {
    host: 'your.mqtt.host',
    port: 1883,
    ssl: false,  // Optional: true für SSL/TLS
    auth: {      // Optional: Authentifizierung
      username: 'your-username',
      password: 'your-password'
    },
    tls: {       // Optional: TLS Konfiguration
      ca: 'path/to/ca.pem',
      cert: 'path/to/cert.pem',
      key: 'path/to/key.pem',
      rejectUnauthorized: true
    }
  },
  client: {
    applicationName: 'my-service',    // Name der Anwendung
    environment: 'production',        // Umgebung (production, staging, development)
    hostname: 'srv-01'               // Host-Identifier
  },
  // Optional:
  debug: true,              // Aktiviert Debug-Logging
  batchSize: 10,           // Anzahl der Events pro Batch (Standard: 10)
  batchIntervalMs: 1000    // Sendeintervall in Millisekunden (Standard: 1000)
});

// Verbindung herstellen (wichtig!)
await monitor.connect();
```

### MongoDB Integration

```javascript
// MongoDB Client wrappen
const wrappedClient = monitor.wrapMongoClient(mongoClient);

// Ab jetzt werden alle Operationen automatisch überwacht:
const db = wrappedClient.db('mydb');
const collection = db.collection('mycollection');

// Beispiel-Operationen:
await collection.insertOne({ ... });
await collection.find({ ... }).toArray();
await collection.updateMany({ ... }, { ... });
```

Überwachte MongoDB-Operationen:
- `find` und alle Cursor-Operationen (`toArray`, `next`, `forEach`, etc.)
- `aggregate` und Pipeline-Operationen
- `insertOne`, `insertMany`
- `updateOne`, `updateMany`
- `deleteOne`, `deleteMany`
- `bulkWrite`
- `watch` (Changestreams)
- und viele mehr...

### Express Integration

```javascript
app.use(monitor.expressMiddleware());
```

### Custom Events

Mit Custom Events können Sie beliebige Ereignisse in Ihrer Anwendung überwachen:

```javascript
// Event registrieren
monitor.registerCustomEvent({
  name: 'http-request',           // Eindeutiger Name des Events
  category: 'api',                // Kategorie für Gruppierung
  description: 'API Request',     // Optionale Beschreibung
  targetSystem: 'external-api',   // Optionales Zielsystem
  tags: {                        // Optionale Tags
    method: 'POST',
    endpoint: '/users'
  }
});

// Event auslösen
await monitor.triggerCustomEvent(
  'http-request',                // Name des registrierten Events
  {                             // Optionale Event-Daten
    statusCode: 200,
    responseTime: 150,
    payload: { /* ... */ }
  },
  150                           // Optionale Ausführungszeit in ms
);

// Event entfernen
monitor.unregisterCustomEvent('http-request');

// Alle registrierten Events abrufen
const events = monitor.getRegisteredCustomEvents();
```

Custom Events werden automatisch:
- Mit Timestamp versehen
- Mit Client-Informationen angereichert
- Mit Performance-Metriken versehen
- Über MQTT an den konfigurierten Broker gesendet

## Features

### MongoDB Monitoring
- ✅ Vollständige Unterstützung für alle MongoDB-Operationen
- ✅ Intelligente Erkennung von Cursor- und ChangeStream-Objekten
- ✅ Korrekte Behandlung von synchronen und asynchronen Methoden
- ✅ Detailliertes Tracking von Pipeline-Stages
- ✅ Umfassende Bulk-Operation-Analyse
- ✅ Changestream-Event-Tracking

### Custom Event Monitoring
- ✅ Flexible Event-Konfiguration
- ✅ Automatische Performance-Messung
- ✅ Benutzerdefinierte Tags und Metadaten
- ✅ Gruppierung nach Kategorien
- ✅ Zielsystem-Tracking

### Performance
- ✅ Optimierte Event-Batching
- ✅ Effiziente Payload-Größenberechnung
- ✅ Methoden-Caching
- ✅ Minimaler Overhead
- ✅ Non-blocking Event-Verarbeitung

### Robustheit
- ✅ Automatische Wiederverbindung
- ✅ Fehlertolerantes Event-Batching
- ✅ Typsichere Implementierung
- ✅ Umfassende Testabdeckung

## Konfigurationsoptionen

### MQTT Optionen (`mqtt`)
- `host`: MQTT Broker Hostname
- `port`: MQTT Broker Port
- `ssl`: SSL/TLS aktivieren (Boolean, optional)
- `auth`: Authentifizierung (optional)
  - `username`: MQTT Benutzername
  - `password`: MQTT Passwort
- `tls`: SSL/TLS Optionen (optional)
  - `ca`: CA Zertifikat
  - `cert`: Client Zertifikat
  - `key`: Client Key
  - `rejectUnauthorized`: Nicht vertrauenswürdige Zertifikate ablehnen

### Client Optionen (`client`)
- `applicationName`: Name der Anwendung
- `environment`: Umgebung ('production', 'staging', 'development')
- `hostname`: Host-Identifier

### Event-Batching Optionen
- `batchSize`: Anzahl der Events pro Batch (Standard: 10)
- `batchIntervalMs`: Sendeintervall in Millisekunden (Standard: 1000)

## Event-Format

Jedes Event enthält:
- Timestamp (ISO 8601)
- Client-Informationen (Name, Environment, Hostname)
- Operationstyp (z.B. 'db:find', 'custom:api')
- Zielsystem (z.B. 'mongodb:mydb', 'external-api')
- Performance-Metriken (Ausführungszeit, Payload-Größe)
- Operationsspezifische Details

## Debug-Logging

Aktivieren Sie Debug-Logs mit:
```bash
export DEBUG=traffic-monitor:*
```

Verfügbare Debug-Namespaces:
- `traffic-monitor:mqtt`: MQTT-Verbindung und Events
- `traffic-monitor:mongodb`: MongoDB-Operationen
- `traffic-monitor:event-batcher`: Event-Batching
- `traffic-monitor:custom-event`: Custom Events

## Tests

```bash
npm test
```

## Lizenz

MIT