πŸš€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

Azu Development Dashboard

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! πŸŽ‰

Last updated

Was this helpful?