← Back to ColdFusion Administrator Reference

Debugging & Logging - Debug Output Settings

Configure debug output options, performance monitoring, and IP filtering

Last updated: October 27, 20258 min read

Overview

Debug Output Settings control what debugging information ColdFusion displays at the bottom of pages during development and testing. When enabled, the debug output provides invaluable insights into application performance, database queries, variable states, execution times, and potential issues. This comprehensive debugging information helps developers identify bottlenecks, troubleshoot errors, and optimize application code.

Proper configuration of debug output settings is critical for both development productivity and production security. While debugging should be extensively used during development, it must be carefully restricted or completely disabled in production environments to prevent information disclosure and performance degradation.

Debug Output Options

Configure which debugging information ColdFusion displays at the bottom of pages during development and testing.

Enable Robust Exception Information

PurposeDisplay detailed error information when exceptions occur
Information ShownFull stack traces, error context, variable values at error point
DevelopmentEssential for debugging - always enable
ProductionMUST be disabled - exposes sensitive information
Security Critical: Reveals file paths, database structure, and internal logic. Technical errors confuse end users. Log errors to files and show user-friendly error pages in production.

Database Activity

PurposeShow all database queries executed during request
Information DisplayedSQL statements, execution time, record counts, datasource names, bound parameters
Use CasesIdentify slow queries, detect N+1 query problems, verify query optimization
Performance ImpactMinimal overhead in development
Production: Never enable - significant performance penalty and security risk.

Exception Information

PurposeDisplay caught exceptions in debug output
InformationException type, message, where caught, handling details
Development ValueTrack exceptions even when handled gracefully; identify try/catch blocks that swallow errors
ProductionDisable to prevent information leakage

Tracing Information

PurposeShow cftrace output in debug section
CapabilitiesDisplay developer-added trace points, track code execution path, output variable values at specific points, measure time between trace points
Use CaseDebug complex conditional logic or loops
ProductionDisable (or use with extreme caution and IP filtering)

Variables

PurposeDisplay contents of various variable scopes
Scopes AvailableURL, Form, Cookie, CGI, Client, Session, Application, Server, Request
Development ValueVerify variable values and structure; essential for troubleshooting session issues
Performance ImpactLarge session/application scopes can slow rendering
Security Critical: NEVER enable in production - may expose passwords, tokens, and sensitive data. Serious security vulnerability.

General Debug Information

PurposeShow overall request execution metrics
Metrics DisplayedTotal page processing time, template cache hits/misses, CFC calls and timing, heap memory usage, request thread details
Use CaseHigh-level performance monitoring

Minimum Execution Time

PurposeOnly show debug output for requests exceeding specified time (milliseconds)
Default0 (show for all requests)
Recommended Value100-500ms during performance tuning
BenefitReduces debug output noise from fast requests; identifies pages requiring optimization

Maximum Execution Time Highlight

PurposeHighlight queries or operations exceeding time threshold
Visual IndicatorRed or bold formatting for slow operations
Recommended50-100ms for query highlighting
Use CaseQuickly spot slow database queries

Output Format Options

Choose how debug information is displayed on your pages.

Classic Debug Output

Format
Traditional HTML table format appended to page bottom
Compatibility
Works with all page types and layouts
Limitations
May interfere with page layout, requires scrolling

Use for simple debugging needs or older applications.

Dockable Debug Output

Format
Modern floating panel with collapsible sections
Features
Search/filter, copy functionality, repositionable
Requirements
JavaScript must be enabled

Recommended: Preferred format for modern development with better developer experience.

Tree Format for Variables

Purpose
Display complex variable structures as expandable trees
Navigation
Collapse/expand nested structures
Performance
Renders large structures more efficiently

Recommended: Enable for better variable inspection and clarity.

IP Address Filtering

Restrict debug output to specific IP addresses for security in production environments.

Purpose and Importance

Security LayerRestrict debug output to specific IP addresses
Use CaseEnable debugging in production for specific developers only
Emergency DebuggingSafely debug production issues without exposing data to all users
Best Practice: Always use IP filtering if any debug settings enabled in production. Same code can run in dev/prod with IP-based debug control.

IP Address Configuration

FormatComma-separated list of IP addresses or patterns
Single IP192.168.1.100
IP Range192.168.1.* or 192.168.1.0/24
Multiple IPs192.168.1.100, 192.168.1.101, 10.0.0.*
Important: Always include 127.0.0.1 for server-based debugging. May support IPv6 addresses depending on version.

Configuration Location

Primary
Administrator debugging settings page (this page)
Alternative
Dedicated IP Addresses page under Debugging section
Scope
Server-wide setting (affects all applications)

IP filtering applies to all debug output settings.

Testing IP Filtering

Verification
Access site from allowed and disallowed IPs
VPN Consideration
VPN may change your apparent IP address
Proxy/Load Balancers
Configure to pass through real client IP

Use whatismyip.com to verify your actual IP address.

Performance Impact

Understanding the performance cost of debug output in different environments.

Development Environment

Impact
Minimal - acceptable overhead for single-developer usage
Page Load Time
10-50ms additional processing time
Memory/Rendering
Additional memory for debug data structures and HTML generation

Recommendation: Accept performance impact for debugging benefits.

Production Environment

Impact
Severe: 20-40% performance degradation possible
Memory/CPU
Debug data kept in memory per request, additional CPU processing
Scalability
Reduced concurrent request capacity, larger page sizes

Verdict: NEVER enable in production without extreme caution.

Selective Debugging Strategies

Minimum Execution Time
Only debug slow requests
IP Filtering
Limit to one or two developer IPs
Selective Options
Enable only specific debug categories needed

Time-limit debugging to active sessions. Use APM tools for production monitoring.

Security Considerations

Debug output can expose sensitive information - understand the risks and implement proper safeguards.

Information Disclosure Risks

Debug output can expose:
  • File Paths: Server directory structure
  • Database Details: Table names, column names, data
  • Credentials: Passwords in variables or query parameters
  • Business Logic: Application flow and structure
  • API Keys: Tokens and keys visible in variables
  • Session Data: User information, authentication tokens
  • Stack Traces: Code structure, library versions, vulnerabilities

Production Security Rules

Critical Rules:
  • Rule #1: NEVER enable debug output in production for all users
  • Rule #2: If absolutely necessary, use strict IP filtering
  • Rule #3: Enable only for minimum time required
  • Rule #4: Disable robust exception information always
  • Rule #5: Never show variable dumps in production
  • Rule #6: Use custom error pages for production errors
  • Rule #7: Monitor for unauthorized debug output exposure

PCI DSS Compliance

Risk
Debug output with cardholder data is violation
Requirement
Must be disabled in production payment processing systems

HIPAA Compliance

Risk
PHI exposure in debug output is breach
Requirement
Must be disabled when handling protected health information

GDPR Compliance

Risk
Personal data in debug output may violate privacy regulations
Requirement
Must protect EU citizen personal data from disclosure

SOC 2 & Auditing

Risk
Uncontrolled debug output fails security controls
Requirement
Log when debug settings are changed and by whom

Best Practices

Development Environment

  • Enable all debug output options for maximum visibility
  • Use dockable debug output format for better UX
  • Leave minimum execution time at 0 to see all requests
  • Enable robust exception information for detailed error context
  • Show all variable scopes during active development
  • Use cftrace liberally to mark execution checkpoints
  • Review debug output regularly to spot performance issues early
  • Pay attention to query execution times and N+1 problems

Staging/QA Environment

  • Enable debug output with IP filtering to QA team addresses
  • Use minimum execution time (100-250ms) to focus on performance issues
  • Enable database activity to verify query optimization
  • Test with debug output disabled to verify production-like performance
  • Use staging to validate that debug is properly disabled for production

Production Environment

  • Disable ALL debug output settings for normal operation
  • Never enable robust exception information
  • Use custom error templates for user-friendly error pages
  • Log errors to files instead of displaying them
  • If emergency debugging needed, use strict IP filtering
  • Only enable specific debug categories (e.g., database only)
  • Document debug output changes in change management system
  • Disable debug output immediately after troubleshooting
  • Use proper APM tools (FusionReactor) for production monitoring

Security Best Practices

  • Review debug output for sensitive data before sharing screenshots
  • Sanitize debug output when reporting bugs to vendors
  • Use IP filtering as defense-in-depth, not sole security measure
  • Regularly audit debug output settings across all servers
  • Include debug settings in security review checklist
  • Train developers on risks of debug output in production
  • Automate checks for debug settings in deployment pipeline

Performance Optimization

  • Use debug output to identify slow database queries
  • Set query execution time threshold to highlight problematic queries
  • Monitor total database time as percentage of page load time
  • Look for repeated identical queries (caching opportunities)
  • Identify N+1 query patterns in loops
  • Use execution time filtering to focus on slow pages
  • Compare debug metrics before and after optimization

Common Issues and Solutions

Debug Output Not Appearing

  • Symptom: Debug settings enabled but no output shown
  • Cause: IP address not in allowed list
  • Solution: Verify your IP address and add to allowed list
  • AJAX Requests: Debug output not shown for AJAX/API responses
  • Content-Type: Non-HTML responses don't include debug output
  • cfcontent: Using cfcontent bypasses debug output

Debug Output Interfering with Page Layout

  • Symptom: Debug output breaks page design
  • Cause: Classic debug format conflicts with page HTML/CSS
  • Solution: Switch to dockable debug output format
  • Alternative: Use cfdump to specific file instead of inline
  • PDF Issues: Debug output prevents PDF generation

Performance Degradation with Debug Enabled

  • Symptom: Site significantly slower with debug enabled
  • Cause: Debug overhead, especially with variable dumps
  • Solution: Disable variable scope display
  • Alternative: Use minimum execution time to reduce output
  • Large Sessions: Disable session variable display if very large

Sensitive Data Visible in Debug Output

  • Symptom: Passwords, tokens visible in debug variables
  • Immediate Action: Disable variable display immediately
  • Code Fix: Remove sensitive data from shared scopes
  • Prevention: Use local variables for sensitive data
  • Best Practice: Never store passwords in session/application scope

Debug Output Not Showing for Some Requests

  • Symptom: Debug output intermittent
  • Cause: Minimum execution time set too high
  • Solution: Lower or remove minimum execution time threshold
  • Fast Pages: Pages loading under threshold won't show debug
  • Caching: Cached pages may not trigger debug output

IP Filtering Not Working

  • Symptom: Debug output showing to unintended users
  • Cause: IP filter misconfigured or not applied
  • Proxy Issues: Load balancer IP instead of client IP
  • Solution: Configure proxy to pass X-Forwarded-For header
  • Testing: Verify IP filtering from multiple addresses

Alternative Debugging Approaches

File-Based Debugging

  • Use cflog for structured logging to files
  • Use cfdump with output="file" for detailed dumps
  • Tail log files in real-time during debugging
  • Safe for production - no information disclosure to users

APM Tools

  • FusionReactor: Comprehensive performance monitoring
  • SeeFusion: Lightweight monitoring alternative
  • New Relic: Cloud-based APM platform
  • Benefits: Production-safe, detailed metrics, alerting
  • Cost: Commercial tools require licensing

Line Debugger

  • Step-through debugging with breakpoints
  • Available in ColdFusion Builder or compatible IDEs
  • More precise than debug output for complex issues
  • See separate Debugger settings for configuration

Custom Debug Output

  • Build application-specific debug panels
  • Control exactly what information is displayed
  • Implement own IP filtering or authentication
  • Store debug data in database for historical analysis

Configuration Examples

Recommended Development Settings

  • Enable Robust Exception Information: Yes
  • Database Activity: Yes
  • Exception Information: Yes
  • Tracing Information: Yes
  • Variables: All scopes
  • General Debug Information: Yes
  • Minimum Execution Time: 0ms
  • Output Format: Dockable
  • IP Filtering: Not required in development

Emergency Production Debugging

  • Enable Robust Exception Information: No
  • Database Activity: Yes (if database issue suspected)
  • Exception Information: No
  • Tracing Information: No
  • Variables: None
  • General Debug Information: Yes
  • Minimum Execution Time: 100-500ms (focus on slow requests)
  • Output Format: Dockable
  • IP Filtering: Single admin IP only

Performance Profiling Settings

  • Enable Robust Exception Information: No
  • Database Activity: Yes
  • Exception Information: No
  • Tracing Information: Yes (if using cftrace)
  • Variables: None
  • General Debug Information: Yes
  • Minimum Execution Time: 100ms
  • Query Execution Time Threshold: 50ms
  • Output Format: Dockable

Related Resources