Event Gateways - Settings

Configure global event gateway settings and resource allocation

Overview

Event Gateway Settings control the global configuration and resource allocation for all event gateways in ColdFusion. These settings determine how ColdFusion manages event processing threads, message queuing, and overall gateway performance.

Proper configuration of these settings is essential for optimal event gateway performance, especially in high-volume environments where multiple gateways are processing events concurrently.

Gateway Service Settings

Core settings that control event gateway service behavior.

Enable Event Gateway Services

PurposeMaster switch to enable or disable all event gateways
DefaultDisabled
ImpactWhen disabled, no event gateways will start, even if configured with automatic startup
RecommendationEnable only if you are using event gateways
Performance: If you are not using event gateways, leave this disabled to reduce server resource consumption and startup time.

Startup Timeout (seconds)

PurposeMaximum time to wait for all gateways to start during ColdFusion startup
Default60 seconds
RecommendationIncrease if you have multiple gateways or gateways that connect to slow external services
ImpactControls how long ColdFusion waits during startup before timing out gateway initialization
Warning: Setting this too low can cause gateways to fail startup. Setting it too high can delay ColdFusion startup if gateways have connection issues.

Thread Pool Configuration

Control the number of threads available for event processing across all gateways.

Maximum Number of Gateway Threads

PurposeTotal number of threads available for processing gateway events
Default50 threads
ScopeShared across all gateway instances
RecommendationLow volume: 10-25 threads
Medium volume: 50-100 threads
High volume: 100-200+ threads
Tuning Guidelines:
  • Monitor thread usage under typical load
  • Increase if events are queuing excessively
  • Consider number of active gateways and expected concurrent events
  • Balance with available CPU cores and memory
  • Each thread consumes memory (typically 1-2 MB per thread)

Thread Idle Timeout (milliseconds)

PurposeHow long idle threads remain alive before being terminated
Default60000 ms (60 seconds)
RecommendationKeep default for most scenarios; increase for bursty workloads
ImpactLower values free up resources faster but may cause thread churn in variable workloads
Performance Consideration: Longer idle timeouts reduce thread creation overhead during traffic spikes but consume more memory during idle periods.

Event Queue Settings

Configure how ColdFusion queues and processes gateway events.

Maximum Queue Size

PurposeMaximum number of events that can be queued across all gateways
Default1000 events
BehaviorWhen full, new events may be rejected or block depending on gateway implementation
RecommendationLow volume: 500-1000
Medium volume: 2000-5000
High volume: 10000+
Memory Impact: Larger queues consume more memory. Each queued event holds message data in memory until processed. Monitor heap usage when increasing queue sizes.
Tuning Strategy:
  • Monitor queue depth under normal and peak loads
  • If queue frequently fills up, increase thread pool first
  • Only increase queue size if events arrive faster than threads can process
  • Very large queues may indicate processing bottlenecks that need optimization

Enable Queue Persistence

PurposePersist queued events to disk to survive server restarts
DefaultDisabled
ImpactEnabled: Events survive restarts but with performance overhead
Disabled: Events lost on restart but better performance
RecommendationEnable only for critical events that cannot be lost
Trade-offs:
  • Enabled: Guarantees event delivery but adds I/O overhead
  • Disabled: Better performance but events in queue are lost on restart
  • Consider external message queuing systems (RabbitMQ, Kafka) for high-reliability requirements

Event Processing Behavior

CFC Method Timeout (seconds)

PurposeMaximum time allowed for CFC listener methods to execute
Default30 seconds
RecommendationFast processing: 10-30 seconds
Complex processing: 60-120 seconds
ImpactPrevents long-running event handlers from blocking threads indefinitely
Best Practice: Keep event processing fast. For long-running tasks, queue them for asynchronous processing using scheduled tasks or separate worker processes.

Retry Failed Events

PurposeAutomatically retry events that fail processing
Retry AttemptsConfigurable (typically 3 retries)
Retry DelayExponential backoff recommended
Implementation: Retry logic is typically implemented in the gateway Java class or CFC listener. Configure retry behavior per gateway type based on requirements.

Monitoring Event Gateways

Use ColdFusion functions to monitor event gateway performance:

Gateway Monitoring Examples
// Get gateway statistics
helper = getGatewayHelper();

// List all gateways and their states
gateways = helper.getGateways();
for (gateway in gateways) {
  state = helper.getGatewayState(gateway);
  writeOutput("#gateway#: #state#<br>");
}

// Get queue information
queueInfo = helper.getQueueInfo();
writeDump(queueInfo);

// Monitor specific gateway
gatewayStats = helper.getGatewayStatistics("SMS_Notifications");
writeOutput("Queue depth: #gatewayStats.queueDepth#<br>");
writeOutput("Messages processed: #gatewayStats.messagesProcessed#<br>");
writeOutput("Messages failed: #gatewayStats.messagesFailed#<br>");

// Check gateway status
if (helper.getGatewayState("SMS_Notifications") != "RUNNING") {
  // Gateway is down - send alert
  writeLog(
    file = "gateway-monitor",
    type = "error",
    text = "SMS_Notifications gateway is not running"
  );

  // Attempt restart
  helper.startGateway("SMS_Notifications");
}
// Scheduled task to monitor gateway health
// Run every 5 minutes

component {

  public void function run() {
    var helper = getGatewayHelper();
    var gateways = helper.getGateways();
    var issues = [];

    // Check each gateway
    for (var gateway in gateways) {
      var state = helper.getGatewayState(gateway);

      if (state != "RUNNING") {
        arrayAppend(issues, {
          gateway: gateway,
          issue: "Not running",
          state: state
        });

        // Attempt automatic restart
        try {
          helper.startGateway(gateway);
          writeLog(
            file = "gateway-monitor",
            text = "Auto-restarted gateway: #gateway#"
          );
        } catch (any e) {
          writeLog(
            file = "gateway-monitor",
            type = "error",
            text = "Failed to restart #gateway#: #e.message#"
          );
        }
      }

      // Check queue depth
      var stats = helper.getGatewayStatistics(gateway);
      if (stats.queueDepth > 500) {
        arrayAppend(issues, {
          gateway: gateway,
          issue: "High queue depth",
          queueDepth: stats.queueDepth
        });
      }
    }

    // Send alerts if issues found
    if (arrayLen(issues)) {
      sendGatewayAlert(issues);
    }
  }

  private void function sendGatewayAlert(required array issues) {
    var message = "Gateway Issues Detected:#chr(10)#";

    for (var issue in arguments.issues) {
      message &= "- #issue.gateway#: #issue.issue#";
      if (structKeyExists(issue, "queueDepth")) {
        message &= " (depth: #issue.queueDepth#)";
      }
      message &= chr(10);
    }

    // Send email alert
    cfmail(
      to = "ops@example.com",
      from = "cfserver@example.com",
      subject = "ColdFusion Gateway Alert",
      type = "text"
    ) {
      writeOutput(message);
    }
  }

}

Performance Tuning Recommendations

Low Volume (< 100 events/min)

Thread Pool
10-25 threads
Queue Size
500-1000 events
Persistence
Optional based on criticality

Conservative settings for occasional event processing with minimal resource overhead.

Medium Volume (100-1000 events/min)

Thread Pool
50-100 threads
Queue Size
2000-5000 events
Persistence
Enable for critical events

Balanced configuration for steady event processing with room for traffic spikes.

High Volume (> 1000 events/min)

Thread Pool
100-200+ threads
Queue Size
10000+ events
Persistence
Consider external message queue

Aggressive settings for high-throughput scenarios. Monitor memory and CPU carefully.

General Tuning Strategy:
  • Start with conservative settings and increase based on monitoring
  • Monitor thread pool utilization and queue depth under load
  • Increase threads before increasing queue size
  • Optimize CFC event handlers for fast processing
  • Consider dedicated ColdFusion instances for high-volume gateways
  • Use external message queuing (RabbitMQ, Kafka) for very high volumes

Common Issues & Solutions

Events Being Dropped

Symptom: Gateway events are not reaching CFC handlers, messages appear to be lost
Solutions:
  • Check if event queue is full (increase queue size or thread pool)
  • Monitor thread pool utilization (increase threads if maxed out)
  • Review CFC handler logs for errors during processing
  • Verify Event Gateway Services are enabled
  • Check gateway instance is running and not failed
  • Review coldfusion-event.log for errors

High Memory Usage

Symptom: ColdFusion memory usage increases significantly when event gateways are active
Solutions:
  • Reduce thread pool size if over-allocated
  • Decrease queue size to reduce queued event memory
  • Optimize CFC handlers to release resources promptly
  • Check for memory leaks in custom gateway Java code
  • Disable queue persistence if not needed
  • Increase JVM heap size if genuinely needed for workload

Slow Event Processing

Symptom: Events are processed slowly, queue depth steadily increases
Solutions:
  • Increase thread pool size to process events faster
  • Optimize CFC handler performance (database queries, external calls)
  • Implement asynchronous processing for slow operations
  • Check for thread contention or database bottlenecks
  • Consider horizontal scaling (multiple CF instances)
  • Review CFC method timeout settings

Related Resources