This downloadable package provides a curated set of ColdFusion logging and log rotation templates designed to standardize, harden, and automate your application logging. It bundles production-ready CFML helpers, log rotation scripts for Windows and Linux, example configurations for structured logs, and a quickstart guide. If you’ve wrestled with noisy logs, unbounded disk growth, or inconsistent formats that complicate Troubleshooting, these templates give you a repeatable, battle-tested starting point.
Contents
show
What You’ll Get
- PDF quickstart (12 pages)
- Installation Checklist
- Configuration matrix for Adobe ColdFusion 2018/2021/2023 and Lucee 5.x
- Troubleshooting guide
- CFML templates
- Logger.cfc (structured logging helper with correlation IDs and context)
- AppLog.cfm (drop-in wrapper for cflog and custom categories)
- Application.cfc snippet for centralized init/config
- Log rotation templates
- Linux: logrotate.d sample with size- and time-based rotation, compression, and retention
- Windows: PowerShell rotation script (.ps1) with scheduled task XML
- Structured logging examples
- JSON Lines format for file logs and forwarders (ELK/Logstash/Graylog/Splunk)
- Sample pattern layout for human-readable logs
- External logging configs (optional)
- log4j2.xml RollingFile examples for external appenders
- Syslog/UDP forwarding pointer config samples
- DevOps scripts
- Health check (verify permissions, free space, rotation working)
- Backfill and compress existing logs
- Environment templates
- Docker-friendly paths and entrypoints
- Windows service and Linux systemd-friendly directories
Supported environments
- Adobe ColdFusion 2018/2021/2023
- Lucee 5.x
- Windows Server 2016/2019/2022
- Ubuntu/CentOS/RHEL/Amazon Linux
- Bare metal, VM, Docker
Overview
Logging and log rotation are foundational for observability, Compliance, and long-term stability. These templates help you:
- Implement consistent log formats across CFML apps
- Enforce rotation and retention policies
- Reduce disk footprint with compression
- Improve traceability with correlation IDs and per-request context
- Integrate with centralized logging pipelines
They respect ColdFusion’s native logging (cflog, CF Administrator logs) while giving you options to standardize app logs and offload rotation to the operating system or Scheduled tasks.
Benefits
- Faster troubleshooting: Consistent fields and JSON-ready logs streamline search and filtering.
- Safer operations: Automated rotation prevents disk exhaustion and service outages.
- Compliance-friendly: Audit-friendly timestamps, immutability options, and retention controls.
- Drop-in simplicity: Use the CFML helpers without disrupting existing logging.
- Portable: Works across Adobe ColdFusion and Lucee, on Windows and Linux, including containers.
How to Use
Step-by-Step Installation
-
Prepare
- Determine your log directory (e.g., Linux: /var/log/coldfusion/app; Windows: C:\ColdFusion\logs\app).
- Ensure the ColdFusion service account has write permissions.
- Decide on rotation strategy: OS-level rotation (logrotate or Task Scheduler) or app-level rotation.
-
Download and extract
- Extract the ZIP to a working directory (e.g., /opt/cf-logging-kit or C:\cf-logging-kit).
- Review the PDF quickstart and choose OS templates that match your setup.
-
Install CFML helpers
- Copy /cfml/Logger.cfc to your application’s /includes or /models folder.
- Copy /cfml/AppLog.cfm where you keep utility includes.
- Add the Application.cfc snippet from /cfml/snippets/Application.cfc to wire in the logger during onApplicationStart.
-
Configure logging paths and formats
- In Application.cfc, set this.logDir and this.env (dev/test/prod).
- Choose JSON or human-readable pattern format in Logger.cfc defaults.
-
Set up rotation (Linux)
- Copy /rotation/linux/app-logrotate.conf to /etc/logrotate.d/yourapp.
- Edit the path to your logs and retention (rotate 14, daily/weekly, size 50M, compress, delaycompress).
- Test with: sudo logrotate -d /etc/logrotate.d/yourapp, then run: sudo logrotate -f /etc/logrotate.d/yourapp.
-
Set up rotation (Windows)
- Place /rotation/windows/Rotate-CFLogs.ps1 in C:\cf-logging-kit.
- Edit variables at top (LogPath, MaxSizeMB, RetainDays).
- Import scheduled task: schtasks /Create /XML C:\cf-logging-kit\Rotate-CFLogs.xml /TN CFLogRotation
- Run once to validate: powershell -ExecutionPolicy Bypass -File .\Rotate-CFLogs.ps1 -Verbose
-
Optional: External appenders
- For advanced filtering or offloading, apply /external/log4j2.xml as a reference for RollingFile or Socket appenders. Note: Do not overwrite ColdFusion’s internal log4j2 config unless you fully understand the implications. Use the example to configure your own app-specific loggers.
-
Validate
- Generate test entries using the sample CFML page in /cfml/examples/log-test.cfm.
- Confirm rotation, compression, and deletion policies work.
- Check timestamps (UTC recommended), level filtering, and JSON validity.
-
Ship to central logging (optional)
- Configure Filebeat/Fluent Bit/Vector to ship logs from your log directory to ELK/Graylog/Splunk.
- Use the provided parsing hints (JSON Lines) for zero-translation ingestion.
Included CFML Examples
Logger.cfc (excerpt)
- Structured logging with a consistent schema:
- timestamp, level, category, message
- requestId, sessionId, userId
- tags, data (arbitrary struct)
- Helper methods: info(), warn(), error(), debug(), Audit()
- Auto-infers request context, falling back gracefully in background tasks
Example usage:
- logger.info(“Order placed”, { orderId=rc.orderId, total=rc.total }, [“checkout”,”orders”])
- logger.error(“Payment declined”, { code=err.code, gateway=”stripe” })
Application.cfc snippet (excerpt)
- Creates one application-scoped logger
- Sets environment, log directory, default level, and format (JSON/pattern)
- Adds per-request correlation IDs
Rotation Templates
Linux (logrotate) sample behaviors:
- Rotate daily or when file exceeds 50 MB
- Keep last 14 files
- compress + delaycompress
- create mode 0640 with CF user/group
- postrotate hook to send SIGHUP to your forwarder if needed
Windows (PowerShell) sample behaviors:
- Rotate when file exceeds MaxSizeMB
- Zip rotated files with timestamp suffix
- Remove archives older than RetainDays
- Optional event log entry on rotation
Best practices
- Use UTC timestamps: Avoid ambiguity across regions and DST. Configure your logger to emit UTC.
- Prefer structured logs: JSON Lines and consistent fields make search and alerting far easier.
- Normalize categories: e.g., app.auth, app.payments, app.email.
- Redact sensitive data: Tokenize or remove PII, secrets, and credentials. The Logger.cfc includes a simple redaction hook.
- Set sensible retention: Balance compliance with disk usage (e.g., 14–30 days locally; ship long-term to centralized storage).
- Right-size log levels: Default to info; elevate to warn/error only when actionable; use debug for development and troubleshooting.
- Add correlation IDs: Generate a requestId at request start; propagate to downstream services and logs.
- Monitor disk and rotation: Alert on free space thresholds; verify rotation runs daily.
- Don’t modify ColdFusion internal logging unless necessary: Prefer app-level files and OS-level rotation for safety.
How It Works with Adobe ColdFusion and Lucee
- CFML logging via cflog: These templates wraps cflog and file appends to allow structured JSON while retaining native logging if desired.
- ColdFusion Administrator settings: Retain default CF admin log settings; use this toolkit for application logs. You can still view CF service logs separately.
- Lucee compatibility: Works as-is for Lucee app logs; use OS-level rotation for simplicity.
- External log4j2: Provided as examples for applications you control; avoid replacing server-level config unless you test thoroughly.
Benefits and Use Cases
- Rapid incident response: Search by requestId across apps and services to reconstruct user journeys.
- Performance tuning: Emit timing metrics (e.g., dbQueryMs) into JSON payloads for trend analysis.
- Security and auditing: Use logger.audit() to record sensitive state changes with immutable rotation.
- Multi-environment deployments: Consistent paths and formats across dev, test, and prod reduce surprises.
- Cloud and containers: Lightweight files + sidecar shippers scale cleanly in Docker/Kubernetes.
Configuration Tips and Advanced Options
- Switch formats at runtime: Toggle JSON vs. pattern with an environment variable (LOG_FORMAT=json|pattern).
- Sampling noisy logs: Drop or sample debug for high-throughput endpoints to reduce costs.
- App-specific log directories: Per-app folders improve isolation and permissions.
- Log forwarding fallback: If central pipeline is down, files remain locally with rotation to prevent outages.
- Automated health checks: Schedule the included health script weekly to validate permissions and rotation status.
Key Takeaways
- These templates give you a consistent, structured approach to ColdFusion logging with automated log rotation and retention.
- Installation is lightweight: drop in CFML helpers, configure paths, and enable OS-level rotation scripts.
- Use JSON Lines and correlation IDs for powerful, centralized search and troubleshooting.
- Keep ColdFusion’s internal logging intact; standardize application logs with this toolkit for safety and portability.
FAQ
How do I integrate this with existing cflog statements?
Include Logger.cfc and gradually migrate critical cflog calls to logger.info()/error(). You can run both in parallel while transitioning. The wrapper can also emit to cflog for Backward compatibility.
Can I use this in containers?
Yes. Set the log directory to a writable volume (e.g., /var/log/app). Use the Docker-friendly entrypoint to run rotation in a sidecar or rely on the orchestrator’s log drivers while still writing structured logs.
Will this change ColdFusion’s built-in logs?
No. By default, it only manages your application logs. It does not alter ColdFusion Administrator logs unless you explicitly replace server-level logging, which is not recommended.
How do I prevent sensitive data from being logged?
Use the redaction hook in Logger.cfc to scrub keys like password, token, authorization, and cardNumber. Keep Security-sensitive logs separate with restricted permissions.
What retention period should I choose?
Common defaults are 14–30 days on the server with long-term retention handled by your central logging platform. Choose based on compliance, storage, and incident response needs.
