Debugging & Logging - Debug Output Settings

Configure debug output options, performance monitoring, and IP filtering

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. Debug output appears only when Enable Request Debugging Output is checked; when it is cleared, no debugging information is displayed, including cftrace and cftimer output (source: Configuring debugging in the ColdFusion Administrator). Adobe recommends not enabling debugging on a production server because it affects performance. The page also offers Timer Information, Flash Form Compile Errors And Messages, Enable Performance Monitoring, and Enable CFSTAT (source: Use the ColdFusion administrator).

Enable Robust Exception Information

PurposeDisplay detailed error information when exceptions occur
Information ShownPhysical path and URI of the template, line number and snippet, SQL statement and data source name (if any), and the Java stack trace
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 database activity for SQL Query events and Stored Procedure events
Information DisplayedSQL query and stored procedure events for the request
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

PurposeShow all ColdFusion exceptions raised for the request in the debugging output
InformationAll ColdFusion exceptions raised for the request
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
CapabilitiesTrack program flow and efficiency using the cftrace tag
Use CaseDebug complex conditional logic or loops
ProductionDisable (or use with extreme caution and IP filtering)

Variables

PurposeDisplay contents of various variable scopes
Scopes AvailableAdobe describes parameters, URL parameters, cookies, sessions, and CGI variables
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 general information about the request and server
Metrics DisplayedColdFusion version, template, timestamp, user locale, user agent, user IP, and host name
Use CaseHigh-level performance monitoring

Report Execution Times

PurposeReports execution times that exceed a specified time limit
Use CaseQuickly spot slow templates

Output Format Options

Choose how debug information is displayed on your pages.

Classic Debug Output

Format
classic.cfm: the format available in ColdFusion 5 and earlier
Compatibility
Basic view with few browser restrictions
Limitations
May interfere with page layout, requires scrolling

Output appears in block format after normal page output.

Dockable Debug Output

Format
dockable.cfm: a dockable tree-based debugging panel
Browser Restrictions
Described in the Administrator online Help

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

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

FormatIndividual IP addresses, added one at a time (Add Current adds your own address); the default entry is 127.0.0.1
Single IP192.168.1.100
RangesWildcard and CIDR entries are not documented for this list; add each address separately
Important: Always include 127.0.0.1 for server-based debugging. If the list is empty and debugging options are active, ColdFusion displays debugging output for all users.

Configuration Location

Page
Debugging & Logging > Debugging IP Addresses
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
CF checks the connecting address, so all proxied clients share the proxy IP unless Tomcat's RemoteIpValve is configured

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
Memory/Rendering
Additional memory for debug data structures and HTML generation

Recommendation: Accept performance impact for debugging benefits.

Production Environment

Impact
Adobe advises against enabling debugging on a production server because it affects performance
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

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
  • 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 the Report Execution Times highlight threshold to spot slow templates
  • 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
  • Review query execution times in the Database Activity output
  • 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 Report Execution Times to find slow templates
  • 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
  • Placement: Debug output appears after normal page output, so check the end of the page

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
  • Non-HTML Output: Debug output does not help with pages that produce PDF, spreadsheet, or JSON output and can cause trouble there; turn it off for those pages with <cfsetting showdebugoutput="false"> (source: Charlie Arehart: Debugging and Error Handling in ColdFusion)

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: Enable only the debug categories you need
  • 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: Some requests arrive from an address not in the Debugging IP Addresses list (for example through a proxy or VPN)

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
  • Note: The debugging IP check compares the client address ColdFusion sees, which behind a proxy is the proxy's address. Passing X-Forwarded-For alone does not change that (Tomcat's RemoteIpValve can), and listing the proxy IP exposes debug output to every client (source: Charlie Arehart: real IP behind a proxy)
  • 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
  • Enabled with Allow Line Debugging on the Debugger Settings page
  • 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
  • Report Execution Times: Yes
  • 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
  • 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
  • Report Execution Times: Yes
  • Output Format: Dockable

Related Resources

Debugging & Logging - Debug Output Settings | ColdFusion Administrator | CFGuide