# Development Dashboard

A comprehensive Development Dashboard HTTP handler for the Azu web framework that provides real-time insights into application performance, metrics, and runtime behavior.

> **⚠️ Important**: The Development Dashboard requires **Performance Monitoring** to be enabled. Performance monitoring in Azu is completely optional and disabled by default for zero overhead in production.

## 🔧 Prerequisites

### Enable Performance Monitoring

The development dashboard depends on performance metrics collection. You must enable performance monitoring:

**Option 1: Environment Variable**

```bash
export PERFORMANCE_MONITORING=true
export PERFORMANCE_PROFILING=true        # Optional: Detailed profiling
export PERFORMANCE_MEMORY_MONITORING=true # Optional: Memory tracking
```

**Option 2: Compile-time Flag**

```bash
crystal build --define=performance_monitoring src/app.cr
```

**Option 3: Configuration**

```crystal
Azu.configure do |config|
  config.performance_enabled = true
  config.performance_profiling_enabled = true
  config.performance_memory_monitoring = true
end
```

### When Performance Monitoring is Disabled

If `PERFORMANCE_MONITORING=false` (default):

* Dashboard will show limited functionality
* Most metrics will display "N/A" or zero values
* Only basic system information will be available
* No performance overhead is incurred

## 🎨 Dashboard Preview

<div><figure><img src="https://3356793631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MTf8GCZ6EEAl3cCP3mp%2Fuploads%2FZs0ccgUxZHlOAHs2zQy5%2Fdev-dashboard.jpg?alt=media&#x26;token=d6acddee-3c88-4297-9262-3e0fe6d91e88" alt=""><figcaption></figcaption></figure> <figure><img src="https://3356793631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MTf8GCZ6EEAl3cCP3mp%2Fuploads%2Fm0mKruOOsVrWW48BxRGv%2Fdev-dashboard-errors.jpg?alt=media&#x26;token=7601d23c-b913-46f1-a5de-5f2c8a2f266c" alt=""><figcaption></figcaption></figure> <figure><img src="https://3356793631-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MTf8GCZ6EEAl3cCP3mp%2Fuploads%2F37BlzUZ0iWLghEZTdPp5%2Fdev-dashboard-routes.jpg?alt=media&#x26;token=eef57fd3-0673-4735-94d0-3f85a7b9e5f4" alt=""><figcaption></figcaption></figure></div>

_The Azu Development Dashboard provides a comprehensive overview of your application's performance, cache metrics, component lifecycle, error logs, and system information in a beautiful, modern interface._

The dashboard features:

* **📊 Real-time Metrics**: Live performance data with automatic refresh
* **🎨 Modern UI**: Professional design with color-coded status indicators
* **📱 Responsive Layout**: Grid-based design that adapts to screen size
* **⚡ Zero Config**: Works out of the box with sensible defaults
* **🔄 Live Updates**: Auto-refresh every 30 seconds with visual feedback
* **🚀 Fast Performance**: Optimized rendering with minimal overhead

## 📋 What's Implemented

### Core Components

1. **DevDashboardHandler** (`src/azu/handler/dev_dashboard.cr`)
   * Clean, extensible HTTP handler following Azu patterns
   * Beautiful HTML dashboard with modern CSS styling
   * Real-time metrics collection and display
   * Auto-refresh every 30 seconds
   * Metrics clearing functionality
   * **Graceful degradation** when performance monitoring is disabled
2. **Enhanced Router** (`src/azu/router.cr`)
   * Added `routes()` method to access registered routes
   * Added `routes_by_method()` for grouped route display
   * Added `route_info()` for development dashboard integration
3. **Development Tools Endpoint** (`playground/endpoints/development_tools_endpoint.cr`)
   * Test data generation for dashboard demonstration
   * Error simulation capabilities
   * Cache and component testing
   * Metrics management
   * **Conditional functionality** based on performance monitoring availability
4. **Request/Response Contracts**
   * `playground/requests/development_tools_request.cr`
   * `playground/responses/development_tools_response.cr`
5. **Comprehensive Documentation** (`docs/advanced/development-dashboard.md`)

## 🎯 Dashboard Sections Implemented

### ✅ 1. Application Status (Always Available)

* **Uptime**: Human-readable format (2h 15m 30s)
* **Memory Usage**: Current memory consumption in MB
* **Process Information**: PID and environment
* **Crystal Version**: Runtime environment details

**When Performance Monitoring Enabled:**

* **Total Requests**: Count from PerformanceMetrics
* **Error Rate**: Percentage with color-coded status
* **CPU Usage**: Realistic performance tracking

### ✅ 2. Performance Metrics (Requires Performance Monitoring)

**When Enabled:**

* **Average Response Time**: From PerformanceMetrics.aggregate\_stats
* **P95/P99 Response Times**: Percentile calculations
* **Memory Allocation**: Peak usage and deltas
* **Requests/Second**: Real-time throughput calculation
* **GC Statistics**: Crystal garbage collector metrics

**When Disabled:**

* Shows "Performance monitoring disabled"
* Displays placeholder values
* Provides instructions to enable monitoring

### ✅ 3. Cache Metrics (Partial Functionality)

**Always Available:**

* **Cache Store Type**: Memory/Redis/Null detection
* **Basic Configuration**: TTL, max size, enabled status

**When Performance Monitoring Enabled:**

* **Hit Rate**: Color-coded performance indicator
* **Operation Breakdown**: GET, SET, DELETE statistics
* **Processing Times**: Average cache operation duration
* **Data Volume**: Total data written in MB
* **Error Rates**: Cache operation failure tracking

### ✅ 4. Component Lifecycle (Requires Performance Monitoring)

**When Enabled:**

* **Total Components**: Active component count
* **Mount/Unmount Events**: Lifecycle tracking
* **Refresh Events**: Component update frequency
* **Average Component Age**: Lifespan analysis

**When Disabled:**

* Shows basic component registry information
* Component count without performance data

### ✅ 5. Error Logs (Requires Performance Monitoring)

**When Enabled:**

* **Recent Errors**: Last 50 error requests
* **Detailed Information**: Timestamp, method, path, status
* **Performance Impact**: Processing time and memory usage
* **Error Classification**: 4xx vs 5xx categorization

**When Disabled:**

* Basic error information only
* No performance correlation data

### ✅ 6. Route Listing (Always Available)

* **All Registered Routes**: Dynamic route discovery
* **HTTP Methods**: Color-coded badges
* **Handler Information**: Endpoint class names
* **Path Parameters**: URL patterns display

### ✅ 7. System Information (Always Available)

* **Crystal Version**: Runtime environment details
* **Process Information**: PID and environment
* **GC Statistics**: Heap size and collection counts
* **Environment Detection**: Development/production mode

### ✅ 8. Test Results (Mocked)

* **Code Coverage**: Percentage with progress bar
* **Test Counts**: Total, failed, success metrics
* **Suite Performance**: Execution time tracking
* **Last Run Timestamp**: Test execution history

## 🛠 Technical Features

### Performance Optimizations

* **LRU Cache**: Route caching for frequent requests
* **Memory Management**: Rolling window of metrics (max 10,000)
* **Lazy Loading**: Metrics collected only when needed
* **Efficient Rendering**: String building with pre-allocated capacity

### Security Features

* **Development Only**: Environment-based access control
* **Optional Authentication**: Localhost restriction example
* **Safe Data Handling**: Proper escaping and validation
* **Error Boundaries**: Graceful fallback for metric collection failures

### User Experience

* **Modern UI**: Professional dashboard design with gradients
* **Responsive Layout**: Grid-based adaptive layout
* **Auto-refresh**: Live data updates every 30 seconds
* **Interactive Elements**: Buttons, hover effects, progress bars
* **Status Indicators**: Color-coded metrics (green/yellow/red)

## 📦 Usage Example

### Basic Integration

```crystal
require "azu"

module MyApp
  include Azu

  configure do
    # Performance monitoring must be enabled at compile time
    {% if env("PERFORMANCE_MONITORING") == "true" || flag?(:performance_monitoring) %}
      performance_monitor = Handler::PerformanceMonitor.new
    {% end %}
  end
end

# Conditional handler chain based on performance monitoring
{% if env("PERFORMANCE_MONITORING") == "true" || flag?(:performance_monitoring) %}
  MyApp.start [
    Azu::Handler::RequestId.new,
    Azu::Handler::DevDashboard.new,              # 👈 Full dashboard functionality
    MyApp::CONFIG.performance_monitor.not_nil!,  # Required for metrics
    Azu::Handler::Rescuer.new,
    Azu::Handler::Logger.new,
  ]
{% else %}
  MyApp.start [
    Azu::Handler::RequestId.new,
    Azu::Handler::DevDashboard.new,              # 👈 Limited functionality
    Azu::Handler::Rescuer.new,
    Azu::Handler::Logger.new,
  ]
{% end %}
```

### Access Dashboard

```
http://localhost:4000/dev-dashboard
```

### Generate Test Data

```
http://localhost:4000/dev-tools?action=generate_test_data
```

### Clear Metrics

```
http://localhost:4000/dev-dashboard?clear=true
```

## 🎨 Dashboard Preview

The dashboard features:

* **🎨 Modern Design**: Professional gradient header, card-based layout
* **📊 Visual Metrics**: Progress bars, color-coded status indicators
* **📱 Responsive**: Grid layout adapts to screen size
* **🔄 Live Updates**: Auto-refresh with visual feedback
* **⚡ Fast Loading**: Optimized rendering and minimal HTTP requests

### Example Metrics Display

```
📊 Application Status
├── Uptime: 2h 15m 30s ✅
├── Memory Usage: 145.2 MB
├── Total Requests: 1,247
├── Error Rate: 2.1% ✅
└── CPU Usage: 18.3%

⚡ Performance Metrics
├── Avg Response Time: 45.2ms
├── P95 Response Time: 127ms
├── P99 Response Time: 284ms
├── Requests/Second: 12.4 ✅
└── Peak Memory: 23.7MB

💾 Cache Metrics
├── Hit Rate: 87.3% ✅
├── Total Operations: 45,231
├── GET Operations: 32,145
├── SET Operations: 8,942
├── Avg Processing Time: 1.2ms
└── Data Written: 127.3MB
```

## 🔧 Extension Points

### Custom Metrics

```crystal
class ExtendedDevDashboard < Azu::Handler::DevDashboard
  private def collect_dashboard_data
    data = super
    data["custom_metrics"] = collect_custom_metrics
    data
  end
end
```

### JSON API

```crystal
struct DashboardApiEndpoint
  include Azu::Endpoint(EmptyRequest, JsonResponse)

  get "/api/dashboard"

  def call : JsonResponse
    dashboard = Azu::Handler::DevDashboard.new
    JsonResponse.new(dashboard.collect_dashboard_data)
  end
end
```

### Real-time Updates (Future Enhancement)

```crystal
# WebSocket integration for live updates
class LiveDashboardChannel < Azu::Channel
  ws "/dashboard-live"

  def on_connect
    spawn do
      loop do
        broadcast_metrics
        sleep 5.seconds
      end
    end
  end
end
```

## 🚀 Suggested Enhancements

### 1. **Charts Integration**

* Add Chart.js for visual metrics
* Real-time graphs for response times
* Memory usage trend charts
* Cache hit rate over time

### 2. **Advanced Filtering**

* Filter errors by time range
* Route-specific performance metrics
* Component type filtering
* Search functionality

### 3. **Export Capabilities**

* Export metrics to JSON/CSV
* Performance report generation
* Historical data persistence
* Metric comparison tools

### 4. **Alerting System**

* Threshold-based alerts
* Email/Slack notifications
* Performance degradation detection
* Memory leak warnings

### 5. **Database Integration**

* Real database connection status
* Query performance monitoring
* Migration status tracking
* Database-specific metrics

## 🔍 Code Quality Features

### Type Safety

* Full Crystal type annotations
* Compile-time validation
* Null safety with proper handling
* Union type management

### Error Handling

* Comprehensive exception catching
* Graceful degradation
* Fallback data display
* Debug logging integration

### Memory Management

* Bounded metric collections
* Automatic cleanup
* GC-friendly data structures
* Memory leak prevention

### Testing Support

* Mock data generation
* Test scenario simulation
* Metric validation helpers
* Development workflow integration

## 📚 Documentation

* **API Reference**: Complete method documentation
* **Usage Examples**: Real-world integration patterns
* **Best Practices**: Performance and security guidelines
* **Troubleshooting**: Common issues and solutions
* **Extension Guide**: Custom dashboard development

## 🎯 Benefits

### For Developers

* **📈 Performance Insights**: Real-time application behavior
* **🐛 Debugging Support**: Error tracking and analysis
* **⚡ Optimization Guidance**: Bottleneck identification
* **🔧 Development Tools**: Integrated testing utilities

### For DevOps

* **📊 Monitoring**: Application health visibility
* **🚨 Alerting**: Performance issue detection
* **📋 Reporting**: Metric collection and analysis
* **🔍 Diagnostics**: System state inspection

### For Teams

* **🤝 Collaboration**: Shared performance visibility
* **📖 Documentation**: Self-documenting metrics
* **🎯 Optimization**: Data-driven improvements
* **🚀 Productivity**: Faster development cycles

***

This implementation provides a **production-ready development dashboard** that intelligently adapts to your performance monitoring configuration. Whether you need zero-overhead production deployments or comprehensive development insights, the dashboard scales to your needs while maintaining excellent performance and user experience.

**Ready to use**: Enable performance monitoring and visit `/dev-dashboard`! 🎉
