Command Line Tools

analyze performance

Analyzes application performance, identifying bottlenecks and optimization opportunities in your Wheels application.

Usage

wheels analyze performance [--target=<target>] [--duration=<seconds>] [--report] [--threshold=<ms>] [--profile]

Parameters

Parameter	Description	Default
`--target`	Analysis target: `all`, `controller`, `view`, `query`, `memory`	`all`
`--duration`	Duration to run analysis in seconds (1-300)	`30`
`--report`	Generate HTML performance report with charts	`false`
`--threshold`	Performance threshold in milliseconds for slow requests	`100`
`--profile`	Enable profiling mode for real metrics (when available)	`false`

Description

The analyze performance command monitors your Wheels application to identify performance bottlenecks and provide optimization recommendations. It tracks metrics in real-time and provides both console output and optional HTML reports.

What It Monitors

Request Performance: Response times, slow requests, controller/action patterns
Database Queries: Query execution times, slow queries, query patterns
Memory Usage: Memory consumption, peak usage, memory trends
View Rendering: Template rendering times (when target includes views)
Overall Health: Performance score and grade (A-F)

Performance Grading

The analyzer assigns a performance grade based on collected metrics:

A (90-100): Excellent performance
B (80-89): Good performance
C (70-79): Acceptable performance
D (60-69): Poor performance, optimization needed
F (0-59): Critical performance issues

Examples

Basic performance analysis

Monitor all metrics for 30 seconds:

wheels analyze performance

Extended monitoring

Analyze for 2 minutes:

wheels analyze performance --duration=120

Focus on database performance

Monitor only database queries:

wheels analyze performance --target=query

Focus on memory usage

Monitor only memory consumption:

wheels analyze performance --target=memory

Adjust performance threshold

Set slow request threshold to 200ms:

wheels analyze performance --threshold=200

Enable profiling mode

Attempt to collect real metrics (if available):

wheels analyze performance --profile

Generate HTML report

Create a detailed HTML report with charts:

wheels analyze performance --report

Complete analysis

Full analysis with all options:

wheels analyze performance --target=all --duration=60 --threshold=200 --profile --report

Output Format

Console Output

Analyzing application performance...

Starting performance monitoring for 30 seconds...
Target: all
Threshold: 100ms

[====================] 100% Complete!
Profiling mode disabled
==================================================
       PERFORMANCE ANALYSIS COMPLETE
==================================================

Data Source: SIMULATED (Enable --profile for real data)

Request Performance
--------------------------------------------------
Requests Analyzed:          42
Average Response Time:     156ms
Slowest Request:          891ms
Fastest Request:           23ms
Slow Requests (>100ms):     18

Database Performance
--------------------------------------------------
Queries Executed:           42
Average Query Time:        28ms
Slow Queries (>50ms):       8

Memory Usage
--------------------------------------------------
Average Memory:           193MB
Peak Memory:              205MB

Top Slow Requests:
--------------------------------------------------
  1. reports.index() - 891ms
  2. users.create() - 645ms
  3. products.update() - 523ms
  4. orders.index() - 412ms
  5. dashboard.show() - 387ms

Top Slow Queries:
--------------------------------------------------
  1. SELECT * FROM orders WHERE id = ? - 187ms
  2. UPDATE products WHERE id = ? - 156ms
  3. SELECT * FROM users WHERE id = ? - 98ms

==================================================
Performance Grade: B (83/100)
==================================================

Performance Recommendations:
--------------------------------------------------
  * Implement caching strategies for frequently accessed data
  * Optimize database queries and add appropriate indexes
  * Enable query result caching in production
  * Minimize database round trips
  * Use connection pooling for database connections

HTML Report

The HTML report includes:

Performance Dashboard: Visual metrics with color-coded indicators
Performance Grade: Large visual display of grade and score
Charts:
- Response time trends over monitoring period
- Memory usage over time
Detailed Tables:
- Top 10 slow requests with timing
- Top 10 slow queries with execution times
Recommendations: Context-aware optimization suggestions

Reports are saved to: reports/performance-[timestamp].html

Data Collection

Simulated Mode (Default)

Generates realistic performance patterns
Useful for testing and demonstration
Provides consistent baseline metrics

Profile Mode (—profile)

When enabled, attempts to:

Access ColdFusion’s metrics service
Hook into Wheels debug information
Collect real request/response times
Capture actual query execution data
Falls back to simulation if real data unavailable

Performance Thresholds

Default thresholds used for categorization:

Slow Requests: > 100ms (configurable via —threshold)
Slow Queries: > 50ms (fixed)
High Memory: > 500MB
Response Time Categories:
- Fast: < 100ms
- Moderate: 100-300ms
- Slow: > 300ms

Recommendations

The analyzer provides context-aware recommendations based on:

High Average Response Time (>200ms): Suggests caching strategies
Slow Queries Detected: Recommends indexing and query optimization
High Memory Usage (>500MB): Suggests memory optimization
Multiple Slow Requests: Recommends async processing and lazy loading

Integration

CI/CD Pipeline

Exit codes for automation:

0: Performance acceptable
1: Performance issues detected (slow requests or queries found)

Example Jenkins integration:

stage('Performance Check') {
    steps {
        sh 'wheels analyze performance --duration=60 --threshold=200'
    }
}

Monitoring Strategy

Run regularly in staging environment
Compare metrics over time to track improvements
Use HTML reports for stakeholder communication
Set appropriate thresholds based on application requirements

Best Practices

Baseline First: Establish performance baselines before optimization
Target Specific Areas: Use —target to focus on suspected bottlenecks
Realistic Load: Run during typical usage patterns for accurate results
Profile Mode: Enable —profile when real metrics are needed
Regular Monitoring: Schedule regular performance checks
Track Trends: Save reports to track performance over time

Limitations

Simulated Data: Default mode uses simulated data; enable —profile for real metrics
Single Instance: Monitors single application instance only
External Services: Doesn’t track external API or service calls
Browser Performance: Server-side only, doesn’t measure client-side performance

Troubleshooting

No real data with —profile

Ensure application has debug mode available
Check ColdFusion administrator settings
Verify appropriate permissions for metrics access

High memory usage reported

Normal for JVM applications
Monitor trends rather than absolute values
Consider JVM heap settings

All requests showing as slow

Adjust threshold to match application expectations
Check if application is under unusual load
Verify database connection pool settings