Files

Michael Schiemer 55a330b223 Enable Discovery debug logging for production troubleshooting

- Add DISCOVERY_LOG_LEVEL=debug
- Add DISCOVERY_SHOW_PROGRESS=true
- Temporary changes for debugging InitializerProcessor fixes on production

2025-08-11 20:13:26 +02:00

13 KiB

Raw Blame History

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:

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:

// 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:

// 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:

$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:

$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:

$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:

$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:

$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:

$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:

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

trackApiCalls

Aktiviert oder deaktiviert die Erfassung von API-Aufrufen:

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

trackUserActions

Aktiviert oder deaktiviert die Erfassung von Benutzeraktionen:

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

trackErrors

Aktiviert oder deaktiviert die Erfassung von Fehlern:

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

trackPerformance

Aktiviert oder deaktiviert die Erfassung von Leistungsmetriken:

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

Konfiguration in der Anwendung

Konfigurationsdatei

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

// 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:

// 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:

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

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

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

// 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:

$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:

$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:

$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

// Ü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