Contents
show
Introduction
This downloadable resource is a complete, vendor-agnostic setup guide that shows you how to instrument Adobe ColdFusion and Lucee CFML applications with New Relic and Datadog APM. It includes everything you need to go from zero to full-stack observability—APM traces, JVM metrics, logs, dashboards, and alerting—across Windows, Linux, Docker, and Kubernetes. If you’ve ever struggled with -javaagent flags, license keys, or deciding what to monitor first, this guide removes the guesswork with proven configurations, step-by-step checklists, and ready-to-import dashboards.
What You’ll Get
- PDF guide (32 pages) with:
- Overview of observability for ColdFusion (APM, Infrastructure, logs, SLOs)
- Side-by-side instructions for New Relic and Datadog
- Checklists for Windows, Linux, Docker, Kubernetes
- Troubleshooting playbooks and verification steps
- Configuration templates:
- newrelic.yml with sensible defaults
- Datadog dd-java-agent flags and datadog.yaml log collection snippets
- JMX Integration samples for JVM, Tomcat, and CF-specific metrics
- Importable dashboards:
- New Relic NRQL dashboards (JSON)
- Datadog APM/Infra/Logs dashboards (JSON)
- Alert monitors:
- Apdex and web transaction time SLOs
- Error rate, memory, GC pause, thread pool saturation, JDBC pool exhaustion
- Automation snippets:
- setenv.sh and jvm.config fragments for ColdFusion
- Dockerfile and docker-compose.yml samples
- Kubernetes manifests and Helm values for agents
- Runbooks and checklists:
- Code examples:
- Custom attributes and events (New Relic Java API)
- Custom spans and tags (Datadog Java tracer)
- Log enrichment with trace IDs
Overview
This setup guide helps you capture end-to-end visibility for ColdFusion workloads by instrumenting the JVM with New Relic or Datadog APM agents, forwarding logs, and standardizing tags across services and environments. It is designed for Adobe ColdFusion 2018/2021/2023 and Lucee 5+, running on Tomcat, IIS/IIS Connector, or embedded servlet containers.
Key capabilities covered:
- APM transaction traces, distributed tracing, and service maps
- JVM health: heap, GC, threads, CPU, JMX metrics
- Application logs with trace/log correlation
- Dashboards and alerting for SLIs/SLOs
- CI/CD-friendly and container/Kubernetes-ready Deployment patterns
Supported Environments
| Component | Versions/Platforms (examples) |
|---|---|
| Adobe ColdFusion | 2018, 2021, 2023 |
| Lucee | 5.x |
| Java | 8, 11, 17 |
| Tomcat | 8.5, 9, 10 |
| OS | Windows Server 2016–2022; Ubuntu/RHEL/CentOS/AlmaLinux |
| Containers | Docker (Linux), Kubernetes (EKS/AKS/GKE, on-prem) |
Note: Always verify specific agent compatibility with your exact runtime and JDK; versions above are commonly supported at the time of writing.
Benefits
- Faster incident resolution through high-fidelity APM traces and correlated logs
- Reduced blind spots with JVM, Tomcat, and CF-specific metrics surfaced via JMX
- Standardized tagging (service, env, version) for reliable dashboards, SLOs, and cost reporting
- Safer rollouts with Deployment markers and version-aware alerting
- Cost control through sampling, data retention policies, and log filtering
How to Use This Download
- Extract the ZIP to a secure workspace (e.g., /opt/cf-observability or C:\cf-observability).
- Choose your vendor path: New Relic or Datadog. Both are fully documented with parallel steps.
- Follow the environment-specific setup: Windows, Linux, Docker, Kubernetes.
- Import dashboards and alerts for instant visibility.
- Validate signals: APM traces, JVM metrics, and logs appear within minutes after restart.
- Roll out progressively: staging first, then production, following the included checklist.
Installation and Configuration
New Relic APM for ColdFusion (Java Agent)
1) Download agent and prepare configuration
- Obtain the New Relic Java agent (newrelic-java.zip) from New Relic.
- Unzip to a directory readable by the ColdFusion service, e.g.:
- Linux: /opt/newrelic
- Windows: C:\newrelic
- Copy the provided newrelic.yml template from the download and set:
- license_key: YOUR_NEW_RELIC_LICENSE_KEY
- app_name: ColdFusion App (Env)
- attributes.include/exclude for PII safety
2) Add the -javaagent flag
- Adobe ColdFusion jvm.config location:
- Linux: /opt/ColdFusion2021/cfusion/bin/jvm.config (adjust version/path)
- Windows: C:\ColdFusion2021\cfusion\bin\jvm.config
- Append to java.args:
- -javaagent:/opt/newrelic/newrelic.jar (Linux)
- -javaagent=C:\newrelic\newrelic.jar (Windows)
Tip: Alternatively, for Tomcat setenv.sh:
- CATALINA_OPTS=”$CATALINA_OPTS -javaagent:/opt/newrelic/newrelic.jar”
3) Restart and verify
- Restart ColdFusion/Tomcat service.
- In New Relic APM, confirm the application appears with web transactions such as /index.cfm and CFML-servlet URIs.
- Import the included New Relic dashboards (NRQL JSON).
4) Logs and Infrastructure (optional but recommended)
- Install New Relic Infrastructure Agent and enable log forwarding.
- Configure log paths:
- Linux examples: /opt/ColdFusion/cfusion/logs/.log, Tomcat logs/catalina.out
- Windows examples: C:\ColdFusion\cfusion\logs\.log
- Enable tracing/log correlation by including trace IDs in logs (see logging snippets in the pack).
Datadog APM for ColdFusion (dd-java-agent)
1) Download agent and set core variables
- Download dd-java-agent.jar to:
- Linux: /opt/datadog/dd-java-agent.jar
- Windows: C:\datadog\dd-java-agent.jar
- Decide on standardized tags:
- DD_SERVICE=coldfusion-app
- DD_ENV=prod|staging|dev
- DD_VERSION=1.2.3
2) Add the -javaagent flag and configuration
- Update jvm.config or setenv.sh to include:
- -javaagent:/opt/datadog/dd-java-agent.jar
- -Ddd.service=coldfusion-app -Ddd.env=prod -Ddd.version=1.2.3
- -Ddd.logs.injection=true -Ddd.trace.enabled=true
- Alternatively, set environment variables (Docker/K8s friendly):
- DD_SERVICE, DD_ENV, DD_VERSION, DD_LOGS_INJECTION=true
3) Install Datadog Agent and enable APM/logs
- On host: install the Datadog Agent, enable apm_config.enabled: true.
- Enable log collection and tail ColdFusion logs:
- conf.d/coldfusion.d/conf.yaml:
logs:- type: file
path: /opt/ColdFusion/cfusion/logs/.log
service: coldfusion-app
source: coldfusion
env: prod
- type: file
- conf.d/coldfusion.d/conf.yaml:
4) Restart and verify
- Restart ColdFusion/Tomcat.
- In Datadog APM, confirm service names, resources (CFML URIs), traces, and dependency maps.
- Import the included Datadog dashboards (JSON).
Docker and Kubernetes Examples
Dockerfile snippet (New Relic)
- COPY newrelic /opt/newrelic
- ENV NEW_RELIC_APP_NAME=”ColdFusion App (Prod)” NEW_RELIC_LICENSE_KEY=XXXX
- ENV JAVA_TOOL_OPTIONS=”-javaagent:/opt/newrelic/newrelic.jar”
Dockerfile snippet (Datadog)
- COPY dd-java-agent.jar /opt/datadog/dd-java-agent.jar
- ENV DD_SERVICE=coldfusion-app DD_ENV=prod DD_VERSION=1.2.3
- ENV JAVA_TOOL_OPTIONS=”-javaagent:/opt/datadog/dd-java-agent.jar -Ddd.logs.injection=true”
Kubernetes (Datadog) via environment variables
- deployment.yaml container env:
- name: DD_SERVICE value: coldfusion-app
- name: DD_ENV value: prod
- name: DD_VERSION value: “1.2.3”
- name: JAVA_TOOL_OPTIONS value: “-javaagent:/opt/datadog/dd-java-agent.jar -Ddd.logs.injection=true”
- Use the Datadog Admission Controller to auto-inject the dd-java-agent if preferred.
Kubernetes (New Relic)
- Mount the agent via initContainer or bake into the image; set JAVA_TOOL_OPTIONS with -javaagent.
- Run newrelic-infra DaemonSet for infra metrics and log forwarding.
Best practices
- Standardize tags: Always set service, env, version. Use consistent names across APM, logs, and infra.
- Protect sensitive data: Use attributes.exclude (New Relic) and log scrubbing/redaction (Datadog) to avoid PII in events, spans, and logs.
- Alert on user experience: Track Apdex, p95 web latency, and error rate per service/environment.
- Watch the JVM: Heap usage, GC time, thread states, JDBC pool metrics. Use the included JMX templates.
- Control costs:
- Sample traces where appropriate.
- Reduce log verbosity in production.
- Filter noisy paths (e.g., health checks) from APM statistics if they skew SLIs.
- Deployment markers: Annotate releases to correlate latency/error changes with code or configuration changes.
- Progressive rollout: Stage → canary → production with pre-defined rollback conditions.
Step-by-Step Quick Start (Windows and Linux)
Windows (Adobe ColdFusion)
- Place agent
- New Relic: C:\newrelic\newrelic.jar and newrelic.yml
- Datadog: C:\datadog\dd-java-agent.jar
- Edit jvm.config
- Path: C:\ColdFusion2021\cfusion\bin\jvm.config
- Append -javaagent flag to java.args (one agent at a time; choose New Relic or Datadog)
- For Datadog, add -Ddd.service, -Ddd.env, -Ddd.version
- Configure logs
- New Relic Infra or Datadog Agent to tail C:\ColdFusion\cfusion\logs\.log
- Restart services
- Restart ColdFusion and, if used, the Tomcat/IIS connector service
- Verify
- Confirm APM metrics, traces, and logs in the vendor UI
Linux (Adobe ColdFusion or Lucee)
- Place agent
- New Relic: /opt/newrelic/newrelic.jar and newrelic.yml
- Datadog: /opt/datadog/dd-java-agent.jar
- Edit jvm.config or setenv.sh
- /opt/ColdFusion2021/cfusion/bin/jvm.config or $CATALINA_BASE/bin/setenv.sh
- Add -javaagent and relevant system properties
- Configure logs
- Enable and point the Infra/Datadog Agent to CF/Tomcat logs
- Restart service
- systemctl restart coldFusion2021 or catalina.sh stop/start
- Validate
- Check APM UI and the included dashboards
Logging Integration and Trace Correlation
- Datadog: Enable -Ddd.logs.injection=true or DD_LOGS_INJECTION=true to add trace IDs to logs automatically. Ensure the Agent tails the same logs.
- New Relic: Use log forwarders and enable linking metadata so logs show trace.id and span.id. The included samples show logback/log4j patterns with New Relic linking metadata.
Recommended log files to collect:
- ColdFusion: application.log, exception.log, scheduler.log
- Tomcat: catalina.out, localhost_access_log.*
- JVM: GC logs (optional for tuning)
Custom Instrumentation (Advanced)
- New Relic Java API:
- NewRelic.recordCustomEvent(“CFJob”, {name:”reindex”, status:”ok”})
- Use custom attributes on transactions for tenantId, siteId, or region (avoid PII).
- Datadog Java tracer:
- Create custom spans around expensive CFML/Java integrations via Java interop.
- Add tags: _dd.origin, tenant, component to aid filtering.
Note: Since ColdFusion runs on the JVM, standard Java agent techniques apply, but always test custom code. The guide includes code snippets and patterns.
Benefits and Use Cases
- Production stability: Detect slow CFML templates, JDBC pool saturation, or Memory leaks before users notice.
- Performance Optimization: Pinpoint p95 latency spikes to specific queries, remote calls, or templates.
- Release confidence: Correlate Performance regressions with deployments using version tags and markers.
- Compliance and Security: Centralized log retention with scrubbing; Audit-friendly dashboards.
- Hybrid and container workloads: Uniform monitoring whether on VMs, Docker, or Kubernetes.
Pros and cons of Each Approach
- New Relic
- Pros: Excellent out-of-the-box APM experience, strong NRQL analytics, cohesive UI
- Cons: Some log pipeline steps require infra agent; pricing/limits may require tuning
- Datadog
- Pros: Powerful unified APM/Infra/Logs with many native integrations; easy log/trace correlation
- Cons: Tag cardinality and log ingestion require careful cost governance
The guide shows how to mitigate Common pitfalls for both platforms.
Troubleshooting
- Agent not detected
- Confirm only one -javaagent is active at a time
- Verify correct jvm.config and that ColdFusion restarts picked up changes
- Check file permissions for agent directories
- No data in APM
- Validate license/API keys and outbound connectivity to vendor endpoints
- Ensure the app receives traffic after restart
- Missing logs
- Confirm agent log tail configuration and paths
- Check log rotation and permissions
- High overhead
- Reduce trace sampling rate, disable verbose instrumentation modules, lower log verbosity
The PDF includes a comprehensive troubleshooting matrix.
Key Takeaways
- Install a single Java agent (-javaagent) per ColdFusion JVM and choose standardized tags for clarity.
- Capture APM, logs, and infra metrics together to unlock trace-log correlation and reliable SLOs.
- Use the included templates, dashboards, and alerts to get production-grade visibility in under an hour.
- Protect data and control costs by sampling traces and scrubbing logs.
FAQ
How do I switch from New Relic to Datadog (or vice versa)?
Stop ColdFusion, remove the existing -javaagent from jvm.config or setenv.sh, add the other vendor’s -javaagent and variables, then restart. Only one Java agent should be active at a time. Keep your dashboards and alerts from both vendors in Version control so you can re-import easily.
Will this work with Lucee CFML?
Yes. Lucee runs on the JVM and can be instrumented using the same Java agent approach. Update the correct startup script or JVM config for your Lucee/Tomcat deployment and restart.
Do I need to instrument IIS when using the IIS connector for ColdFusion?
No. Instrument the ColdFusion JVM. IIS serves static content and proxies dynamic requests to ColdFusion; the APM agent must run inside the JVM where CFML executes.
How much performance overhead should I expect?
Typical overhead for modern Java APM agents is modest (often low single-digit percentages). The guide shows how to tune sampling, disable expensive modules, and reduce log verbosity if needed.
Can I run this in containers and Kubernetes?
Yes. Use JAVA_TOOLOPTIONS with the -javaagent flag, set DD* or New Relic env variables, and deploy the vendor’s infrastructure/log agent as a sidecar/DaemonSet. The included Docker and Helm snippets cover common patterns.
