michaelschiemer/docs/components/analytics/configuration.md

# Analytics Konfiguration

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

## Übersicht

Das Analytics Framework bietet umfangreiche Konfigurationsmöglichkeiten, um das Verhalten und die Leistung an die Anforderungen Ihrer Anwendung anzupassen. Diese Dokumentation beschreibt die verfügbaren Konfigurationsoptionen und wie Sie diese anwenden können.

## Konfigurationsklasse

Die zentrale Klasse für die Analytics-Konfiguration ist `AnalyticsConfig`. Diese Klasse enthält alle Einstellungen, die das Verhalten des Analytics Frameworks steuern:

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

// Konfiguration erstellen
$config = new AnalyticsConfig(
    $enabled = true,                         // Analytics aktivieren/deaktivieren
    $samplingRate = 1.0,                     // Sampling-Rate (0.0 - 1.0)
    $securityAnalyticsEnabled = true,        // Sicherheits-Analytics aktivieren
    $dataPath = '/var/www/html/storage/analytics', // Pfad für Datenspeicherung
    $bufferSize = 1000,                      // Puffergröße für Ereignisse
    $retentionDays = 365,                    // Aufbewahrungsdauer in Tagen
    $trackPageViews = true,                  // Seitenaufrufe erfassen
    $trackApiCalls = true,                   // API-Aufrufe erfassen
    $trackUserActions = true,                // Benutzeraktionen erfassen
    $trackErrors = true,                     // Fehler erfassen
    $trackPerformance = true                 // Leistungsmetriken erfassen
);
```

## Standardkonfiguration

Die `AnalyticsConfig`-Klasse bietet eine Standardkonfiguration, die für die meisten Anwendungen geeignet ist:

```php
// Standardkonfiguration verwenden
$config = AnalyticsConfig::default();
```

Die Standardkonfiguration aktiviert alle Features mit sinnvollen Standardwerten:
- Analytics aktiviert
- 100% Sampling (alle Daten werden erfasst)
- Sicherheits-Analytics aktiviert
- 1000 Ereignisse im Puffer
- 365 Tage Aufbewahrungsdauer
- Alle Tracking-Typen aktiviert

## Umgebungsvariablen

Die Konfiguration kann auch über Umgebungsvariablen angepasst werden:

```php
// In der AnalyticsConfig-Klasse
public static function default(): self
{
    return new self(
        enabled: filter_var($_ENV['ANALYTICS_ENABLED'] ?? true, FILTER_VALIDATE_BOOLEAN),
        samplingRate: (float)($_ENV['ANALYTICS_SAMPLING_RATE'] ?? 1.0),
        securityAnalyticsEnabled: filter_var($_ENV['SECURITY_ANALYTICS_ENABLED'] ?? true, FILTER_VALIDATE_BOOLEAN),
        dataPath: $_ENV['ANALYTICS_DATA_PATH'] ?? '/var/www/html/storage/analytics',
        bufferSize: (int)($_ENV['ANALYTICS_BUFFER_SIZE'] ?? 1000),
        retentionDays: (int)($_ENV['ANALYTICS_RETENTION_DAYS'] ?? 365),
        trackPageViews: filter_var($_ENV['ANALYTICS_TRACK_PAGE_VIEWS'] ?? true, FILTER_VALIDATE_BOOLEAN),
        trackApiCalls: filter_var($_ENV['ANALYTICS_TRACK_API_CALLS'] ?? true, FILTER_VALIDATE_BOOLEAN),
        trackUserActions: filter_var($_ENV['ANALYTICS_TRACK_USER_ACTIONS'] ?? true, FILTER_VALIDATE_BOOLEAN),
        trackErrors: filter_var($_ENV['ANALYTICS_TRACK_ERRORS'] ?? true, FILTER_VALIDATE_BOOLEAN),
        trackPerformance: filter_var($_ENV['ANALYTICS_TRACK_PERFORMANCE'] ?? true, FILTER_VALIDATE_BOOLEAN)
    );
}
```

Beispiel für eine `.env`-Datei:

```
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
```

## Konfigurationsoptionen im Detail

### Grundlegende Optionen

#### enabled

Aktiviert oder deaktiviert das gesamte Analytics Framework:

```php
$config = new AnalyticsConfig(
    enabled: true, // Analytics aktivieren
    // ... weitere Optionen
);

// oder

$config = new AnalyticsConfig(
    enabled: false, // Analytics deaktivieren
    // ... weitere Optionen
);
```

Wenn deaktiviert, werden keine Daten erfasst, und alle Aufrufe an den `AnalyticsCollector` werden ignoriert.

#### samplingRate

Definiert den Prozentsatz der Daten, die erfasst werden sollen:

```php
$config = new AnalyticsConfig(
    enabled: true,
    samplingRate: 1.0, // 100% der Daten erfassen
    // ... weitere Optionen
);

// oder

$config = new AnalyticsConfig(
    enabled: true,
    samplingRate: 0.1, // 10% der Daten erfassen
    // ... weitere Optionen
);
```

Die Sampling-Rate ist nützlich, um die Datenmenge und die Serverbelastung bei hohem Datenaufkommen zu reduzieren. Ein Wert von 0.1 bedeutet, dass nur 10% aller Ereignisse erfasst werden.

#### securityAnalyticsEnabled

Aktiviert oder deaktiviert die Erfassung von Sicherheitsereignissen:

```php
$config = new AnalyticsConfig(
    enabled: true,
    samplingRate: 1.0,
    securityAnalyticsEnabled: true, // Sicherheits-Analytics aktivieren
    // ... weitere Optionen
);
```

Wenn aktiviert, werden Sicherheitsereignisse (wie Anmeldeversuche, CSRF-Angriffe, WAF-Blockierungen) erfasst und analysiert.

### Speicheroptionen

#### dataPath

Definiert den Pfad, in dem Analytics-Daten gespeichert werden:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    dataPath: '/var/www/html/storage/analytics',
    // ... weitere Optionen
);
```

Stellen Sie sicher, dass dieser Pfad existiert und für die Anwendung beschreibbar ist.

#### bufferSize

Definiert die Anzahl der Ereignisse, die im Speicher gepuffert werden, bevor sie auf die Festplatte geschrieben werden:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    bufferSize: 1000, // 1000 Ereignisse puffern
    // ... weitere Optionen
);
```

Ein größerer Puffer reduziert die Anzahl der Schreibvorgänge, erhöht aber den Speicherverbrauch und das Risiko von Datenverlust bei einem Absturz.

#### retentionDays

Definiert die Anzahl der Tage, für die Analytics-Daten aufbewahrt werden:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    retentionDays: 365, // Daten für 1 Jahr aufbewahren
    // ... weitere Optionen
);
```

Ältere Daten werden automatisch gelöscht, um Speicherplatz zu sparen.

### Tracking-Optionen

#### trackPageViews

Aktiviert oder deaktiviert die Erfassung von Seitenaufrufen:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    trackPageViews: true, // Seitenaufrufe erfassen
    // ... weitere Optionen
);
```

#### trackApiCalls

Aktiviert oder deaktiviert die Erfassung von API-Aufrufen:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    trackApiCalls: true, // API-Aufrufe erfassen
    // ... weitere Optionen
);
```

#### trackUserActions

Aktiviert oder deaktiviert die Erfassung von Benutzeraktionen:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    trackUserActions: true, // Benutzeraktionen erfassen
    // ... weitere Optionen
);
```

#### trackErrors

Aktiviert oder deaktiviert die Erfassung von Fehlern:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    trackErrors: true, // Fehler erfassen
    // ... weitere Optionen
);
```

#### trackPerformance

Aktiviert oder deaktiviert die Erfassung von Leistungsmetriken:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    trackPerformance: true, // Leistungsmetriken erfassen
);
```

## Konfiguration in der Anwendung

### Konfigurationsdatei

Die Analytics-Konfiguration kann in einer dedizierten Konfigurationsdatei definiert werden:

```php
// config/analytics.php
return [
    'enabled' => true,
    'sampling_rate' => 1.0,
    'security_analytics_enabled' => true,
    'data_path' => '/var/www/html/storage/analytics',
    'buffer_size' => 1000,
    'retention_days' => 365,
    'track_page_views' => true,
    'track_api_calls' => true,
    'track_user_actions' => true,
    'track_errors' => true,
    'track_performance' => true,
];
```

### Dependency Injection

Die Konfiguration kann über Dependency Injection in die Anwendung eingebunden werden:

```php
// In einem Service Provider oder Container-Konfiguration
$container->set(AnalyticsConfig::class, function () {
    return new AnalyticsConfig(
        enabled: true,
        samplingRate: 0.1,
        // ... weitere Optionen
    );
});
```

### Laufzeitkonfiguration

Die Konfiguration kann zur Laufzeit angepasst werden:

```php
// Analytics-Konfiguration aktualisieren
$newConfig = new AnalyticsConfig(
    enabled: true,
    samplingRate: 0.5, // Sampling-Rate anpassen
    // ... weitere Optionen
);

// Konfiguration aktualisieren
$analyticsManager->updateConfig($newConfig);
```

## Umgebungsspezifische Konfiguration

Es ist oft sinnvoll, unterschiedliche Konfigurationen für verschiedene Umgebungen zu verwenden:

### Produktionsumgebung

```php
// Produktionskonfiguration
$config = new AnalyticsConfig(
    enabled: true,
    samplingRate: 0.1, // Reduzierte Sampling-Rate für hohe Lasten
    securityAnalyticsEnabled: true,
    dataPath: '/var/www/html/storage/analytics',
    bufferSize: 5000, // Größerer Puffer für bessere Leistung
    retentionDays: 365,
    trackPageViews: true,
    trackApiCalls: true,
    trackUserActions: true,
    trackErrors: true,
    trackPerformance: true
);
```

### Entwicklungsumgebung

```php
// Entwicklungskonfiguration
$config = new AnalyticsConfig(
    enabled: true,
    samplingRate: 1.0, // Alle Daten erfassen für einfachere Fehlersuche
    securityAnalyticsEnabled: true,
    dataPath: '/var/www/html/storage/analytics',
    bufferSize: 100, // Kleinerer Puffer für sofortiges Feedback
    retentionDays: 30, // Kürzere Aufbewahrungsdauer
    trackPageViews: true,
    trackApiCalls: true,
    trackUserActions: true,
    trackErrors: true,
    trackPerformance: true
);
```

### Testumgebung

```php
// Testkonfiguration
$config = new AnalyticsConfig(
    enabled: false, // Deaktiviert für Tests
    samplingRate: 1.0,
    securityAnalyticsEnabled: false,
    dataPath: '/tmp/analytics',
    bufferSize: 10,
    retentionDays: 1,
    trackPageViews: false,
    trackApiCalls: false,
    trackUserActions: false,
    trackErrors: false,
    trackPerformance: false
);
```

## Leistungsoptimierung

### Sampling für hohe Lasten

Bei hohem Datenaufkommen kann die Sampling-Rate reduziert werden, um die Serverbelastung zu verringern:

```php
$config = new AnalyticsConfig(
    enabled: true,
    samplingRate: 0.01, // Nur 1% der Daten erfassen
    // ... weitere Optionen
);
```

### Pufferoptimierung

Die Puffergröße kann angepasst werden, um die Anzahl der Schreibvorgänge zu optimieren:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    bufferSize: 10000, // Größerer Puffer für weniger Schreibvorgänge
    // ... weitere Optionen
);
```

### Selektives Tracking

Nicht alle Tracking-Typen müssen aktiviert sein. Deaktivieren Sie die Typen, die Sie nicht benötigen:

```php
$config = new AnalyticsConfig(
    // ... vorherige Optionen
    trackPageViews: true,
    trackApiCalls: true,
    trackUserActions: false, // Benutzeraktionen deaktivieren
    trackErrors: true,
    trackPerformance: false // Leistungsmetriken deaktivieren
);
```

## Fehlerbehebung

### 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
- Stellen Sie sicher, dass der Datenpfad existiert und beschreibbar ist

```php
// Überprüfen Sie die Konfiguration
var_dump($analyticsConfig);

// Erhöhen Sie die Sampling-Rate
$newConfig = new AnalyticsConfig(
    enabled: true,
    samplingRate: 1.0, // 100% der Daten erfassen
    // ... weitere Optionen
);

// Überprüfen Sie die Berechtigungen des Datenpfads
if (!is_writable($analyticsConfig->dataPath)) {
    echo "Datenpfad ist nicht beschreibbar: " . $analyticsConfig->dataPath;
}
```

#### 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

```php
// Reduzieren Sie die Sampling-Rate
$newConfig = new AnalyticsConfig(
    enabled: true,
    samplingRate: 0.1, // Nur 10% der Daten erfassen
    // ... weitere Optionen
);

// Erhöhen Sie die Puffergröße
$newConfig = new AnalyticsConfig(
    // ... vorherige Optionen
    bufferSize: 10000, // Größerer Puffer
    // ... weitere Optionen
);
```

## Weiterführende Informationen

- [Analytics Framework Übersicht](index.md)
- [Analytics Beispiele](examples.md)
- [Performance-Monitoring](/components/performance/index.md)