Michael Schiemer
55a330b223
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
508 lines
12 KiB
Markdown
508 lines
12 KiB
Markdown
# 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)
|