π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
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
Enhanced Router (
src/azu/router.cr
)Added
routes()
method to access registered routesAdded
routes_by_method()
for grouped route displayAdded
route_info()
for development dashboard integration
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
Request/Response Contracts
playground/requests/development_tools_request.cr
playground/responses/development_tools_response.cr
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?