# Analytics Framework

> **Dokumentationshinweis:** Diese Dokumentation ist vollständig aktualisiert und stellt die aktuelle Implementierung des Analytics Frameworks korrekt dar.

## Übersicht

Das Analytics Framework ist ein leistungsstarkes System zur Erfassung, Speicherung und Analyse von Daten über die Nutzung und Leistung Ihrer Anwendung. Es ist vollständig in das Framework integriert und ermöglicht die Erfassung verschiedener Arten von Ereignissen, darunter Seitenaufrufe, Benutzeraktionen, API-Aufrufe, Fehler und Geschäftsereignisse.

Das Framework basiert auf dem Performance-System und bietet eine flexible, erweiterbare Architektur für verschiedene Analyseanforderungen, ohne auf externe Dienste angewiesen zu sein.

## Hauptkomponenten

### AnalyticsCollector

Die zentrale Klasse für die Erfassung von Analytics-Daten:

```php
use App\Framework\Analytics\AnalyticsCollector;
use App\Framework\Analytics\AnalyticsCategory;

// Benutzeraktion erfassen
$analyticsCollector->trackAction(
    'button_click',
    AnalyticsCategory::USER,
    ['button_id' => 'submit', 'page' => '/checkout']
);

// Seitenaufruf erfassen
$analyticsCollector->trackPageView(
    '/products',
    ['referrer' => '/home', 'user_id' => $userId]
);

// Fehler erfassen
$analyticsCollector->trackError(
    'validation_error',
    ['field' => 'email', 'message' => 'Invalid email format']
);

// Geschäftsereignis erfassen
$analyticsCollector->trackBusinessEvent(
    'order_completed',
    ['order_id' => '12345', 'amount' => 99.99, 'items' => 3]
);

// API-Aufruf erfassen
$analyticsCollector->trackApiCall(
    '/api/products',
    'GET',
    200,
    ['duration' => 45, 'cache_hit' => true]
);
```

### AnalyticsCategory

Ein Enum, das die verschiedenen Kategorien von Analytics-Daten definiert:

```php
use App\Framework\Analytics\AnalyticsCategory;

// Verfügbare Kategorien
$category = AnalyticsCategory::USER;       // Benutzeraktionen
$category = AnalyticsCategory::SYSTEM;     // Systemereignisse
$category = AnalyticsCategory::BUSINESS;   // Geschäftsereignisse
$category = AnalyticsCategory::PERFORMANCE; // Leistungsmetriken
$category = AnalyticsCategory::SECURITY;   // Sicherheitsereignisse
```

### AnalyticsStorage

Das Interface für die Speicherung von Analytics-Daten:

```php
use App\Framework\Analytics\Storage\AnalyticsStorage;

interface AnalyticsStorage
{
    // Rohdaten speichern
    public function storeRawData(string $eventType, array $data): void;
    
    // Aggregierte Daten speichern
    public function storeAggregatedData(string $metricName, float $value, array $tags = []): void;
    
    // Rohdaten abrufen
    public function getRawData(string $eventType, \DateTimeInterface $from, \DateTimeInterface $to): array;
    
    // Aggregierte Daten abrufen
    public function getAggregatedData(string $metricName, \DateTimeInterface $from, \DateTimeInterface $to, array $tags = []): array;
}
```

Das Framework bietet eine leistungsoptimierte Implementierung:

```php
use App\Framework\Analytics\Storage\PerformanceBasedAnalyticsStorage;

// Leistungsoptimierte Speicherung
$storage = new PerformanceBasedAnalyticsStorage(
    $filesystem,
    $performanceSystem,
    $clock,
    $config
);
```

### AnalyticsMiddleware

Eine Middleware, die automatisch Analytics-Daten für HTTP-Anfragen erfasst:

```php
use App\Framework\Analytics\Middleware\AnalyticsMiddleware;

// In der Bootstrap-Datei oder Router-Konfiguration
$app->addMiddleware(AnalyticsMiddleware::class);
```

Die Middleware erfasst automatisch:
- Seitenaufrufe
- API-Aufrufe
- Leistungsmetriken (Antwortzeit, Speicherverbrauch)
- HTTP-Statuscodes
- Benutzeragenten und Referrer

### SecurityAnalyticsListener

Ein Listener, der Sicherheitsereignisse in Analytics-Daten umwandelt:

```php
use App\Framework\Analytics\Listeners\SecurityAnalyticsListener;
use App\Framework\Analytics\Bridges\SecurityEventBridge;

// In der Bootstrap-Datei
$securityEventBridge = SecurityEventBridge::create(
    $container->get(SecurityAnalyticsListener::class),
    $config->securityAnalyticsEnabled
);

$eventDispatcher->addListener(SecurityEventInterface::class, [$securityEventBridge, 'handleSecurityEvent']);
```

## Datenerfassung

### Benutzeraktionen

Benutzeraktionen repräsentieren Interaktionen des Benutzers mit der Anwendung:

```php
$analyticsCollector->trackAction(
    'button_click',     // Aktionsname
    AnalyticsCategory::USER, // Kategorie
    [                   // Zusätzliche Daten
        'button_id' => 'submit',
        'page' => '/checkout',
        'user_id' => $userId
    ]
);
```

### Seitenaufrufe

Seitenaufrufe repräsentieren den Besuch einer Seite durch einen Benutzer:

```php
$analyticsCollector->trackPageView(
    '/products',        // Pfad
    [                   // Zusätzliche Daten
        'referrer' => '/home',
        'user_id' => $userId,
        'device_type' => 'mobile'
    ]
);
```

### Fehler

Fehler repräsentieren Probleme, die während der Ausführung der Anwendung auftreten:

```php
$analyticsCollector->trackError(
    'validation_error', // Fehlertyp
    [                   // Zusätzliche Daten
        'field' => 'email',
        'message' => 'Invalid email format',
        'user_id' => $userId
    ]
);

// Oder mit einer Exception
try {
    // Code, der eine Exception werfen könnte
} catch (\Exception $e) {
    $analyticsCollector->trackException($e);
}
```

### Geschäftsereignisse

Geschäftsereignisse repräsentieren wichtige Ereignisse aus geschäftlicher Sicht:

```php
$analyticsCollector->trackBusinessEvent(
    'order_completed',  // Ereignisname
    [                   // Zusätzliche Daten
        'order_id' => '12345',
        'amount' => 99.99,
        'items' => 3,
        'user_id' => $userId
    ]
);
```

### API-Aufrufe

API-Aufrufe repräsentieren Anfragen an die API der Anwendung:

```php
$analyticsCollector->trackApiCall(
    '/api/products',    // Pfad
    'GET',              // Methode
    200,                // Statuscode
    [                   // Zusätzliche Daten
        'duration' => 45,
        'cache_hit' => true,
        'user_id' => $userId
    ]
);
```

## Konfiguration

### AnalyticsConfig

Die `AnalyticsConfig`-Klasse enthält die Konfiguration für das Analytics Framework:

```php
use App\Framework\Analytics\AnalyticsConfig;

// Standardkonfiguration
$config = AnalyticsConfig::default();

// Benutzerdefinierte Konfiguration
$config = new AnalyticsConfig(
    $enabled = true,
    $samplingRate = 1.0,
    $securityAnalyticsEnabled = true,
    $dataPath = '/var/www/html/storage/analytics',
    $bufferSize = 1000,
    $retentionDays = 365,
    $trackPageViews = true,
    $trackApiCalls = true,
    $trackUserActions = true,
    $trackErrors = true,
    $trackPerformance = true
);
```

### Umgebungsvariablen

Die Konfiguration kann auch über Umgebungsvariablen angepasst werden:

```
ANALYTICS_ENABLED=true
ANALYTICS_SAMPLING_RATE=0.1
SECURITY_ANALYTICS_ENABLED=true
ANALYTICS_DATA_PATH=/var/www/html/storage/analytics
ANALYTICS_BUFFER_SIZE=1000
ANALYTICS_RETENTION_DAYS=365
ANALYTICS_TRACK_PAGE_VIEWS=true
ANALYTICS_TRACK_API_CALLS=true
ANALYTICS_TRACK_USER_ACTIONS=true
ANALYTICS_TRACK_ERRORS=true
ANALYTICS_TRACK_PERFORMANCE=true
```

## Datenanalyse

### Rohdaten abrufen

```php
// Rohdaten für Seitenaufrufe abrufen
$pageViews = $analyticsStorage->getRawData(
    'page_view',
    new \DateTimeImmutable('-7 days'),
    new \DateTimeImmutable()
);

// Rohdaten für Geschäftsereignisse abrufen
$orders = $analyticsStorage->getRawData(
    'business_event_order_completed',
    new \DateTimeImmutable('-30 days'),
    new \DateTimeImmutable()
);
```

### Aggregierte Daten abrufen

```php
// Aggregierte Daten für Seitenaufrufe abrufen
$pageViewStats = $analyticsStorage->getAggregatedData(
    'analytics_page_views_total',
    new \DateTimeImmutable('-7 days'),
    new \DateTimeImmutable(),
    ['path' => '/products']
);

// Aggregierte Daten für API-Aufrufe abrufen
$apiCallStats = $analyticsStorage->getAggregatedData(
    'analytics_api_calls_total',
    new \DateTimeImmutable('-7 days'),
    new \DateTimeImmutable(),
    ['path' => '/api/products', 'method' => 'GET']
);
```

### Dashboard

Das Analytics-Dashboard bietet eine visuelle Darstellung der erfassten Daten:

```php
use App\Framework\Analytics\Dashboard\AnalyticsDashboard;

// Dashboard initialisieren
$dashboard = new AnalyticsDashboard($analyticsStorage);

// Statistiken abrufen
$stats = $dashboard->getStats(
    new \DateTimeImmutable('-7 days'),
    new \DateTimeImmutable()
);

// Spezifische Statistiken abrufen
$pageViewStats = $dashboard->getPageViewStats();
$errorStats = $dashboard->getErrorStats();
$performanceStats = $dashboard->getPerformanceStats();
$businessStats = $dashboard->getBusinessStats();
```

## Integration

### Service-Container

Der Analytics-Service wird automatisch registriert und kann per Dependency Injection verwendet werden:

```php
use App\Framework\Analytics\AnalyticsCollector;

class UserController
{
    public function __construct(
        private readonly AnalyticsCollector $analyticsCollector
    ) {}
    
    public function register(Request $request): Response
    {
        // Benutzerregistrierung verarbeiten
        
        // Geschäftsereignis erfassen
        $this->analyticsCollector->trackBusinessEvent(
            'user_registered',
            ['user_id' => $user->id, 'email_domain' => $emailDomain]
        );
        
        return $response;
    }
}
```

### Event-Integration

Das Analytics Framework kann mit dem Event-System des Frameworks integriert werden:

```php
use App\Framework\Analytics\EventSubscribers\AnalyticsEventSubscriber;

// In der Bootstrap-Datei
$eventDispatcher->addSubscriber(new AnalyticsEventSubscriber($analyticsCollector));
```

## Leistungsoptimierung

### Sampling

Um die Leistung bei hohem Datenaufkommen zu verbessern, unterstützt das Analytics Framework Sampling:

```php
// Sampling-Rate konfigurieren (10% der Daten erfassen)
$config = new AnalyticsConfig(
    $enabled = true,
    $samplingRate = 0.1
);
```

### Pufferung

Das Analytics Framework verwendet Pufferung, um die Anzahl der Schreibvorgänge zu reduzieren:

```php
// Puffergröße konfigurieren
$config = new AnalyticsConfig(
    $enabled = true,
    $samplingRate = 1.0,
    $securityAnalyticsEnabled = true,
    $dataPath = '/var/www/html/storage/analytics',
    $bufferSize = 1000 // Anzahl der Ereignisse im Puffer
);
```

### Asynchrone Verarbeitung

Für maximale Leistung kann die Analytics-Verarbeitung asynchron erfolgen:

```php
use App\Framework\Analytics\AsyncAnalyticsCollector;

// Asynchronen Collector verwenden
$asyncCollector = new AsyncAnalyticsCollector(
    $analyticsCollector,
    $queue
);

// Daten asynchron erfassen
$asyncCollector->trackPageView('/products');
```

## Datenverwaltung

### Datenaufbewahrung

Das Analytics Framework unterstützt automatische Datenaufbewahrungsrichtlinien:

```php
// Aufbewahrungsdauer konfigurieren
$config = new AnalyticsConfig(
    $enabled = true,
    $samplingRate = 1.0,
    $securityAnalyticsEnabled = true,
    $dataPath = '/var/www/html/storage/analytics',
    $bufferSize = 1000,
    $retentionDays = 365 // Daten für 1 Jahr aufbewahren
);
```

### Datenexport

Daten können für die weitere Analyse exportiert werden:

```php
use App\Framework\Analytics\Export\AnalyticsExporter;

// Exporter initialisieren
$exporter = new AnalyticsExporter($analyticsStorage);

// Daten exportieren
$csvData = $exporter->exportToCsv(
    'page_view',
    new \DateTimeImmutable('-7 days'),
    new \DateTimeImmutable()
);

// Daten in Datei speichern
file_put_contents('page_views.csv', $csvData);
```

## Fehlerbehebung

### Logging

Das Analytics Framework bietet umfangreiches Logging für die Fehlerbehebung:

```php
// In der AnalyticsCollector-Klasse
$this->logger->info("Analytics: trackAction called with action={$action}, category={$category->value}");
$this->logger->error("Analytics: Failed to store data", ['error' => $e->getMessage()]);
```

### Häufige Probleme

#### Keine Daten werden erfasst

Mögliche Ursachen:
- Analytics ist deaktiviert (`enabled = false`)
- Sampling-Rate ist zu niedrig
- Fehler beim Speichern der Daten

Lösung:
- Überprüfen Sie die Konfiguration
- Erhöhen Sie die Sampling-Rate
- Überprüfen Sie die Logs auf Fehler

#### Hohe Serverbelastung

Mögliche Ursachen:
- Zu viele Ereignisse werden erfasst
- Puffergröße ist zu klein
- Synchrone Verarbeitung bei hohem Datenaufkommen

Lösung:
- Reduzieren Sie die Sampling-Rate
- Erhöhen Sie die Puffergröße
- Verwenden Sie asynchrone Verarbeitung

## Weiterführende Informationen

- [Analytics Konfiguration](configuration.md)
- [Analytics Beispiele](examples.md)
- [Performance-Monitoring](/components/performance/index.md)