fix: Gitea Traefik routing and connection pool optimization

- Remove middleware reference from Gitea Traefik labels (caused routing issues) - Optimize Gitea connection pool settings (MAX_IDLE_CONNS=30, authentication_timeout=180s) - Add explicit service reference in Traefik labels - Fix intermittent 504 timeouts by improving PostgreSQL connection handling Fixes Gitea unreachability via git.michaelschiemer.de
2025-11-09 14:46:15 +01:00
parent 85c369e846
commit 36ef2a1e2c
1366 changed files with 104925 additions and 28719 deletions
--- a/docs/livecomponents/livecomponents-monitoring-debugging.md
+++ b/docs/livecomponents/livecomponents-monitoring-debugging.md
@@ -0,0 +1,701 @@
+# LiveComponents Monitoring & Debugging
+
+**Status**: ✅ Implemented
+**Date**: 2025-10-09
+
+Comprehensive monitoring and debugging infrastructure for LiveComponents system.
+
+---
+
+## Overview
+
+Production-ready monitoring and development debugging tools for LiveComponents:
+- **Production Monitoring**: Metrics, health checks, performance tracking
+- **Development Debugging**: Debug panel, component inspector
+- **Admin-Only Security**: All endpoints require admin authentication
+
+---
+
+## 1. Production Monitoring
+
+### 1.1 Monitoring Controller
+
+**Location**: `src/Framework/LiveComponents/Controllers/LiveComponentMonitoringController.php`
+
+**Dependencies**:
+- `CacheMetricsCollector` - Cache performance metrics
+- `ComponentRegistry` - Component statistics
+- `ComponentMetadataCache` - Metadata caching info
+- `ComponentStateCache` - State caching info
+- `ProcessorPerformanceTracker` - Optional template processor profiling
+
+### 1.2 Monitoring Endpoints
+
+#### GET `/api/livecomponents/metrics`
+**Auth**: Admin only (`#[Auth(roles: ['admin'])]`)
+
+Comprehensive system metrics including:
+```json
+{
+  "cache": {
+    "overall": {
+      "hit_rate": "85.50%",
+      "miss_rate": "14.50%",
+      "total_requests": 1000,
+      "average_lookup_time_ms": 0.15
+    },
+    "by_type": {
+      "state": { "hit_rate": "70.00%", ... },
+      "slot": { "hit_rate": "60.00%", ... },
+      "template": { "hit_rate": "80.00%", ... }
+    },
+    "performance_assessment": {
+      "state_cache": { "grade": "B", "meets_target": true },
+      "slot_cache": { "grade": "B", "meets_target": true },
+      "template_cache": { "grade": "A", "meets_target": true },
+      "overall_grade": "B+"
+    }
+  },
+  "registry": {
+    "total_components": 15,
+    "component_names": ["counter", "timer", "chat", ...],
+    "memory_estimate": 76800
+  },
+  "processors": {
+    "enabled": true,
+    "metrics": { ... }
+  },
+  "system": {
+    "memory_usage": 12582912,
+    "peak_memory": 15728640
+  },
+  "timestamp": 1696857600
+}
+```
+
+**Use Cases**:
+- Production monitoring dashboards
+- Performance trend analysis
+- Capacity planning
+- Alerting integration
+
+#### GET `/api/livecomponents/health`
+**Auth**: Public (no authentication required)
+
+Quick health check for monitoring systems:
+```json
+{
+  "status": "healthy",  // or "degraded"
+  "components": {
+    "registry": true,
+    "cache": true
+  },
+  "warnings": [],
+  "timestamp": 1696857600
+}
+```
+
+**HTTP Status Codes**:
+- `200 OK` - System healthy
+- `503 Service Unavailable` - System degraded
+
+**Use Cases**:
+- Load balancer health checks
+- Uptime monitoring (Pingdom, UptimeRobot, etc.)
+- Auto-scaling triggers
+- Alerting systems
+
+#### GET `/api/livecomponents/metrics/cache`
+**Auth**: Admin only
+
+Focused cache metrics:
+```json
+{
+  "overall": { ... },
+  "by_type": { ... },
+  "performance_assessment": { ... }
+}
+```
+
+#### GET `/api/livecomponents/metrics/registry`
+**Auth**: Admin only
+
+Component registry statistics:
+```json
+{
+  "total_components": 15,
+  "component_names": [...],
+  "memory_estimate": 76800
+}
+```
+
+#### POST `/api/livecomponents/metrics/reset`
+**Auth**: Admin only
+**Environment**: Development only
+
+Reset all collected metrics:
+```json
+{
+  "message": "Metrics reset successfully",
+  "timestamp": 1696857600
+}
+```
+
+Returns `403 Forbidden` in production.
+
+---
+
+## 2. Component Inspector
+
+### 2.1 Inspector Endpoints
+
+#### GET `/api/livecomponents/inspect/{componentId}`
+**Auth**: Admin only
+
+Detailed component inspection for debugging:
+```json
+{
+  "component": {
+    "id": "counter:demo",
+    "name": "counter",
+    "instance_id": "demo",
+    "class": "App\\Application\\LiveComponents\\CounterComponent"
+  },
+  "metadata": {
+    "properties": [
+      {
+        "name": "count",
+        "type": "int",
+        "nullable": false,
+        "hasDefault": true
+      }
+    ],
+    "actions": [
+      {
+        "name": "increment",
+        "parameters": []
+      },
+      {
+        "name": "decrement",
+        "parameters": []
+      }
+    ],
+    "constructor_params": ["id", "initialData"],
+    "compiled_at": "2025-10-09 01:45:23"
+  },
+  "state": {
+    "cached": true,
+    "data": {
+      "count": 5,
+      "label": "My Counter"
+    }
+  },
+  "cache_info": {
+    "metadata_cached": true,
+    "state_cached": true
+  },
+  "timestamp": 1696857600
+}
+```
+
+**Use Cases**:
+- Runtime debugging
+- State inspection
+- Metadata verification
+- Cache status checking
+- Development troubleshooting
+
+#### GET `/api/livecomponents/instances`
+**Auth**: Admin only
+
+List all available component types:
+```json
+{
+  "total": 15,
+  "instances": [
+    {
+      "name": "counter",
+      "class": "App\\Application\\LiveComponents\\CounterComponent",
+      "metadata_cached": true
+    },
+    {
+      "name": "timer",
+      "class": "App\\Application\\LiveComponents\\TimerComponent",
+      "metadata_cached": true
+    }
+  ],
+  "timestamp": 1696857600
+}
+```
+
+**Use Cases**:
+- Component discovery
+- System overview
+- Debugging aid
+- Cache status overview
+
+---
+
+## 3. Development Debug Panel
+
+### 3.1 Debug Panel Renderer
+
+**Location**: `src/Framework/LiveComponents/Debug/DebugPanelRenderer.php`
+
+**Features**:
+- Auto-rendered in development environment
+- Collapsible panel with component details
+- State inspection with JSON preview
+- Performance metrics (render time, memory usage)
+- Cache hit/miss indicators
+- Component metadata display
+- Zero overhead in production
+
+### 3.2 Activation
+
+**Environment Variables**:
+```bash
+# Option 1: Development environment
+APP_ENV=development
+
+# Option 2: Explicit debug flag
+LIVECOMPONENT_DEBUG=true
+```
+
+**Auto-Detection**:
+```php
+DebugPanelRenderer::shouldRender()
+// Returns true if APP_ENV=development OR LIVECOMPONENT_DEBUG=true
+```
+
+### 3.3 Debug Panel Display
+
+**Visual Example**:
+```
+┌─────────────────────────────────────────────────────┐
+│ 🔧 counter                                         ▼ │
+├─────────────────────────────────────────────────────┤
+│ Component: App\Application\LiveComponents\...      │
+│ Render Time: 2.35ms                                 │
+│ Memory: 2.5 MB                                      │
+│ Cache: ✅ HIT                                       │
+│                                                     │
+│ State:                                              │
+│ {                                                   │
+│   "count": 5,                                       │
+│   "label": "My Counter"                             │
+│ }                                                   │
+│                                                     │
+│ Actions: increment, decrement, reset                │
+│ Metadata: 3 properties, 3 actions                   │
+└─────────────────────────────────────────────────────┘
+```
+
+**Features**:
+- Click header to collapse/expand
+- Inline styles (no external CSS needed)
+- JSON-formatted state with syntax highlighting
+- Performance metrics
+- Cache status indicators
+
+### 3.4 Integration
+
+**Automatic Injection**:
+- Debug panel automatically appended after component rendering
+- Only in development environment
+- No code changes required in components
+- Fully transparent to production
+
+**Component Registry Integration**:
+```php
+// In ComponentRegistry::render()
+if ($this->debugPanel !== null && DebugPanelRenderer::shouldRender()) {
+    $renderTime = (microtime(true) - $startTime) * 1000;
+    $html .= $this->renderDebugPanel($component, $renderTime, $cacheHit);
+}
+```
+
+---
+
+## 4. Metrics Collection
+
+### 4.1 Cache Metrics Collector
+
+**Location**: `src/Framework/LiveComponents/Cache/CacheMetricsCollector.php`
+
+**Features**:
+- Real-time metric collection
+- Per-cache-type tracking (State, Slot, Template)
+- Aggregate metrics across all caches
+- Performance target validation
+- Automatic performance grading (A-F)
+
+**Metrics Tracked**:
+```php
+public function recordHit(CacheType $cacheType, float $lookupTimeMs): void
+public function recordMiss(CacheType $cacheType, float $lookupTimeMs): void
+public function recordInvalidation(CacheType $cacheType): void
+public function updateSize(CacheType $cacheType, int $size): void
+```
+
+**Performance Assessment**:
+```php
+$assessment = $collector->assessPerformance();
+// [
+//   'state_cache' => [
+//     'target' => '70.0%',
+//     'actual' => '85.5%',
+//     'meets_target' => true,
+//     'grade' => 'A'
+//   ],
+//   ...
+// ]
+```
+
+**Performance Targets**:
+- State Cache: 70% hit rate (faster initialization)
+- Slot Cache: 60% hit rate (faster resolution)
+- Template Cache: 80% hit rate (faster rendering)
+
+**Grading Scale**:
+- A: ≥90% hit rate
+- B: 80-89%
+- C: 70-79%
+- D: 60-69%
+- F: <60%
+
+### 4.2 Performance Warnings
+
+**Automatic Detection**:
+```php
+if ($collector->hasPerformanceIssues()) {
+    $warnings = $collector->getPerformanceWarnings();
+    // [
+    //   "State cache hit rate (65.2%) below target (70.0%)",
+    //   "Template cache hit rate (75.3%) below target (80.0%)"
+    // ]
+}
+```
+
+**Integration**:
+- Health check endpoint includes warnings
+- Monitoring alerts can trigger on warnings
+- Debug panel shows performance issues
+
+---
+
+## 5. Processor Performance Tracking
+
+### 5.1 Performance Tracker
+
+**Location**: `src/Framework/View/ProcessorPerformanceTracker.php`
+
+**Features**:
+- Optional profiling (disable in production)
+- Minimal overhead (<0.1ms when enabled)
+- Per-processor metrics
+- Performance grading (A-F)
+- Bottleneck identification
+
+**Activation**:
+```bash
+# Enable via environment variable
+ENABLE_TEMPLATE_PROFILING=true
+```
+
+**Metrics Tracked**:
+```php
+public function measure(string $processorClass, callable $execution): string
+// Tracks:
+// - Execution time (ms)
+// - Memory usage (bytes)
+// - Invocation count
+// - Average/min/max times
+```
+
+**Performance Report**:
+```php
+$report = $tracker->generateReport();
+// ProcessorPerformanceReport {
+//   processors: [
+//     'PlaceholderReplacer' => [
+//       'total_time_ms' => 15.3,
+//       'invocation_count' => 100,
+//       'average_time_ms' => 0.153,
+//       'grade' => 'A'
+//     ],
+//     ...
+//   ],
+//   bottlenecks: ['ForProcessor'],
+//   overall_grade: 'B+'
+// }
+```
+
+---
+
+## 6. Usage Examples
+
+### 6.1 Production Monitoring
+
+**Prometheus/Grafana Integration**:
+```bash
+# Scrape metrics endpoint
+curl -s https://api.example.com/api/livecomponents/metrics \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  | jq '.cache.overall.hit_rate'
+```
+
+**Health Check Monitoring**:
+```bash
+# Simple uptime check
+curl -f https://api.example.com/api/livecomponents/health || alert_team
+
+# Detailed health with warnings
+curl -s https://api.example.com/api/livecomponents/health | jq '.warnings[]'
+```
+
+**Alerting Rules**:
+```yaml
+# Prometheus alert rule
+- alert: LiveComponentsCacheDegraded
+  expr: livecomponents_cache_hit_rate < 0.7
+  for: 5m
+  annotations:
+    summary: "LiveComponents cache performance degraded"
+```
+
+### 6.2 Development Debugging
+
+**Component Inspection**:
+```bash
+# Inspect specific component instance
+curl https://localhost/api/livecomponents/inspect/counter:demo \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  | jq '.state.data'
+
+# List all available components
+curl https://localhost/api/livecomponents/instances \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  | jq '.instances[].name'
+```
+
+**Debug Panel**:
+```bash
+# Enable debug panel
+export APP_ENV=development
+
+# Or via dedicated flag
+export LIVECOMPONENT_DEBUG=true
+
+# Debug panel auto-appears in rendered components
+# Click panel header to collapse/expand
+```
+
+---
+
+## 7. Security Considerations
+
+### 7.1 Authentication
+
+**Admin-Only Endpoints**:
+- All monitoring endpoints require `admin` role
+- Health check endpoint is public (by design)
+- Component inspector admin-only
+- Metrics reset admin-only + development-only
+
+**Authentication Pattern**:
+```php
+#[Route('/api/livecomponents/metrics', method: Method::GET)]
+#[Auth(roles: ['admin'])]
+public function metrics(): JsonResult
+```
+
+### 7.2 Environment Restrictions
+
+**Production Safety**:
+- Debug panel disabled in production (APP_ENV check)
+- Metrics reset blocked in production
+- Performance tracking optional (minimal overhead)
+
+**Development Features**:
+- Debug panel auto-enabled in development
+- Metrics reset available
+- Component inspector with full details
+
+---
+
+## 8. Performance Impact
+
+### 8.1 Production Overhead
+
+**Metrics Collection**:
+- **Memory**: ~5KB per component metadata
+- **CPU**: <0.1ms per metric recording
+- **Storage**: In-memory metrics (no persistence)
+
+**Health Check Endpoint**:
+- **Response Time**: <10ms
+- **Memory**: Negligible
+- **CPU**: Minimal
+
+**Monitoring Endpoints**:
+- **Response Time**: 50-100ms (includes metric aggregation)
+- **Memory**: Temporary allocation for JSON serialization
+- **CPU**: Metric calculation and formatting
+
+### 8.2 Development Overhead
+
+**Debug Panel**:
+- **Render Time**: +1-2ms per component
+- **Memory**: +10KB per component (metadata + panel HTML)
+- **Zero Overhead**: Completely disabled in production
+
+**Component Inspector**:
+- **Query Time**: 10-50ms (metadata + state lookup)
+- **Memory**: Temporary allocation
+- **No Impact**: On-demand only
+
+---
+
+## 9. Integration with Performance Optimizations
+
+### 9.1 Metrics Integration
+
+**Cache Metrics**:
+- ComponentMetadataCache reports to CacheMetricsCollector
+- ComponentStateCache reports to CacheMetricsCollector
+- SlotContentCache reports to CacheMetricsCollector
+- TemplateFragmentCache reports to CacheMetricsCollector
+
+**Performance Tracking**:
+- ProcessorPerformanceTracker integrates with TemplateProcessor
+- Optional profiling via environment variable
+- Minimal overhead when disabled
+
+### 9.2 Debug Integration
+
+**Debug Panel Data Sources**:
+- ComponentMetadataCache for metadata
+- ComponentStateCache for state
+- Render timing from ComponentRegistry
+- Memory usage from PHP runtime
+
+**Component Inspector**:
+- ComponentMetadataCache for structure
+- ComponentStateCache for runtime state
+- ComponentRegistry for class mapping
+
+---
+
+## 10. Future Enhancements
+
+### 10.1 Planned Features
+
+**Metrics Persistence**:
+- Store metrics in database for historical analysis
+- Metric retention policies
+- Trend analysis and visualization
+
+**Advanced Alerting**:
+- Custom alert rules
+- Slack/Email notifications
+- Automated incident creation
+
+**Component Profiler**:
+- Detailed performance profiling per component
+- Flame graphs for render pipeline
+- Bottleneck identification
+
+**Interactive Debug UI**:
+- Web-based debug panel (alternative to inline)
+- State manipulation
+- Action testing
+- Component playground
+
+### 10.2 Integration Opportunities
+
+**APM Integration**:
+- New Relic integration
+- Datadog integration
+- Elastic APM integration
+
+**Logging Integration**:
+- Structured logging for all metrics
+- Log aggregation (ELK, Splunk)
+- Metric-to-log correlation
+
+---
+
+## 11. Troubleshooting
+
+### 11.1 Common Issues
+
+**Metrics Not Updating**:
+```bash
+# Check if metrics collector is registered
+curl https://localhost/api/livecomponents/metrics/cache | jq '.overall.total_requests'
+
+# Reset metrics (development only)
+curl -X POST https://localhost/api/livecomponents/metrics/reset \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+**Debug Panel Not Showing**:
+```bash
+# Verify environment
+echo $APP_ENV  # Should be "development"
+echo $LIVECOMPONENT_DEBUG  # Should be "true"
+
+# Check DebugPanelRenderer registration
+# Should be auto-registered via DebugPanelInitializer
+```
+
+**Health Check Failing**:
+```bash
+# Check detailed health status
+curl -s https://localhost/api/livecomponents/health | jq '.'
+
+# Check warnings
+curl -s https://localhost/api/livecomponents/health | jq '.warnings'
+```
+
+### 11.2 Performance Degradation
+
+**Cache Hit Rate Low**:
+- Check cache TTL configuration
+- Verify cache key generation
+- Review cache invalidation patterns
+- Analyze workload patterns
+
+**High Memory Usage**:
+- Check component count (registry statistics)
+- Review metadata cache size
+- Analyze state cache retention
+- Consider cache eviction policies
+
+---
+
+## Summary
+
+Comprehensive monitoring and debugging infrastructure providing:
+
+**Production**:
+- ✅ Metrics endpoint (cache, registry, performance)
+- ✅ Health check endpoint (200/503 responses)
+- ✅ Cache metrics collection with grading
+- ✅ Performance tracking (optional)
+- ✅ Admin-only security
+
+**Development**:
+- ✅ Debug panel (auto-rendered)
+- ✅ Component inspector (detailed runtime info)
+- ✅ Component instance listing
+- ✅ Metrics reset capability
+- ✅ Zero production overhead
+
+**Integration**:
+- ✅ Works with all performance optimizations
+- ✅ Integrates with cache layers
+- ✅ Hooks into component registry
+- ✅ Template processor profiling support
+- ✅ Framework-compliant patterns