CQLAzu CLIAuthoritySessionGithub

🚀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

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

Option 2: Compile-time Flag

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

Option 3: Configuration

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

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

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

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

JSON API

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)

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

PreviousDevelopment ToolsNextCache Metrics

Last updated

Was this helpful?