Structured Logs and Traces

Structured Logging Principles

You should move beyond plain text logs to structured, machine-parseable formats that make analysis and debugging easier:

• JSON Format: Easy to parse and query
• Consistent Fields: timestamp, level, message, context
• Correlation IDs: Track requests across services
• Contextual Data: User ID, session ID, request ID

Container Logging Strategy

For containerized applications, you should follow the twelve-factor app methodology for logging:

• Write logs to stdout/stderr rather than to files on disk
• Use JSON layout for structured output that's easy to parse
• Let your container orchestration platform handle log collection and forwarding
• Centralize all logs in an aggregation system like Elasticsearch, CloudWatch, or Splunk

// Configure Log4j for JSON output to stdout
// In log4j2.xml or ColdFusion Administrator
<Appenders>
    <Console name="STDOUT" target="SYSTEM_OUT">
        <JsonLayout compact="true" eventEol="true" />
    </Console>
</Appenders>

Log Levels and When to Use Them

• FATAL: Application cannot continue
• ERROR: Operation failed, needs attention
• WARN: Potentially harmful situation
• INFO: Important business events
• DEBUG: Detailed diagnostic info (dev/staging only)
• TRACE: Very detailed debugging (dev only)

ColdFusion Logging Best Practices

<cflog
    file="application"
    type="information"
    text="User logged in: userID=#userID#">

<!--- Include correlation ID for request tracking --->
<cflog
    file="application"
    type="error"
    text="Payment failed: orderID=#orderID#, correlationID=#request.correlationID#">

<!--- Log structured data as JSON --->
<cflog
    file="application"
    type="information"
    text="#serializeJSON({
        'event': 'orderCompleted',
        'orderID': orderID,
        'amount': total,
        'userID': userID,
        'correlationID': request.correlationID
    })#">

Log Rotation and Retention

You should configure log rotation to prevent disk space exhaustion on your servers:

• Traditional Servers: Use Log4j RollingFileAppender
• Containers: Let platform handle rotation (Kubernetes, Docker)
• Retention: 30-90 days depending on compliance requirements
• Archival: Move old logs to object storage (S3, Azure Blob)

Metrics and Monitoring

You should expose key metrics for monitoring systems to track application health and performance:

• JMX Metrics: Heap usage, GC stats, thread pools (monitor with JVM tuning)
• PMT Integration: Built-in performance metrics
• Custom Metrics: Business KPIs, error rates
• Health Endpoints: /healthcheck.cfm for load balancers

<!--- Simple health check endpoint --->
<cfset response = {
    "status": "healthy",
    "timestamp": now(),
    "version": "2025.0.1",
    "checks": {
        "database": checkDatabase(),
        "cache": checkCache()
    }
}>
<cfcontent type="application/json">
<cfoutput>#serializeJSON(response)#</cfoutput>

Distributed Tracing

You should implement distributed tracing for microservices architectures to track requests across multiple services:

• Generate a unique trace ID for each incoming request
• Propagate the trace ID to all downstream service calls
• Use W3C Trace Context standard headers for interoperability
• Include the trace ID in all log messages to correlate events

<!--- Generate or extract trace ID --->
<cfset request.traceID = getHTTPRequestData().headers["traceparent"] ?: createUUID()>

<!--- Propagate to downstream services --->
<cfhttp url="#serviceURL#" method="GET">
    <cfhttpparam type="header" name="traceparent" value="#request.traceID#">
</cfhttp>

<!--- Include in all logs --->
<cflog file="application" type="info"
    text="Processing request: traceID=#request.traceID#">

Security and Compliance

• Never log passwords, credit card numbers, or personally identifiable information (PII)
• Implement masking or redaction for sensitive data that must be logged
• Encrypt logs both in transit and at rest to protect sensitive information
• Implement appropriate log retention policies to comply with regulations like GDPR and HIPAA
• Control access to log files and logging systems using proper authentication and authorization