AppsStudioWorkflowsOptimize workflow engine performance

Configure rate limits

This topic explains how to configure rate limits for the workflow engine’s task workers.

Prerequisites

  • Platform 6.3 or newer installed
  • System administrator access to modify Platform configuration
  • Access to the workflow engine configuration API (for runtime configuration)

Configuration parameters

Rate limiting parameters are set at the Platform instance level in environment variables, your .properties configuration file, or your profile document.

Property name (.properties)DescriptionTypeDefaultMinimumMaximum
task_worker_rate_limitThe maximum number of tasks to run per period. Set to 0 to disable the rate limiter.Integer00None
task_worker_rate_limit_periodThe time period in seconds for the task worker rate limit.Integer11None
task_worker_thread_countThe number of worker threads available for task processing. All threads share the configured rate limit. Integer114

Parameters explained

Task worker rate limit

Primary rate limit control for task execution.

  • Set to a positive integer to enable rate limiting.
  • Set to 0 to disable completely.
  • Represents the maximum number of tasks that can execute per period.

Task worker rate limit period

Defines the time window (in seconds) for the rate limit.

  • Set to a positive integer (seconds).
  • Works with task_worker_rate_limit to define the execution rate.
  • Example: task_worker_rate_limit=100 with task_worker_rate_limit_period=1 = 100 tasks per second.

In most cases, use the default period of one second unless you need to rate limit to slower than one task per second.

Task worker thread count

Controls how many task worker threads run within the Platform instance.

  • Each worker processes tasks concurrently.
  • All workers share the configured rate limit.
  • More workers can improve CPU utilization and throughput.
  • Example: Three task workers at 100 tasks per period total (33 per worker) can better utilize available CPU while maintaining the same rate limit.
  • Default: 1 task worker.
  • Maximum: 4 task workers. Itential Platform doesn’t allow values above 4. The task worker uses every thread you allocate to it, and setting this too high can consume all available CPU and memory resources and degrade overall system performance, including API responsiveness and health check reliability.

For guidance on choosing and adjusting a value within this range, see Tune rate limits.

Configuration approach

Rate limiting can be set at startup and adjusted at runtime through the workflow engine API.

At startup: Set in Platform-level environment variables, your .properties configuration file, or your profile document. Configuration loads when the workflow engine starts and persists across restarts.

At runtime: Adjust via the workflow engine HTTP API without a restart. Changes take effect immediately but are not persisted across restarts unless also updated in configuration files.

Configure at startup (persistent)

1

Determine appropriate rate limits

Choose rate limits based on system resource capacity (CPU, memory), typical workflow volumes and patterns, peak usage times, and downstream service capacity. Monitor your system under typical load and adjust based on observed performance.

2

Set configuration

Set rate limit parameters in your Platform-level configuration:

$task_worker_rate_limit=100
$task_worker_rate_limit_period=1
$task_worker_thread_count=2
3

Restart the Platform

Restart your Itential Platform instance to load the configuration changes.

4

Verify configuration

Verify the configuration has been applied using one of these options:

Option 1: Check system logs

Open the workflow engine log files and look for entries confirming rate limit settings, for example, “Task rate limit enabled at X tasks per Y seconds” and “Number of task workers: X.” Verify the logged values match your configuration.

Option 2: View in Admin Essentials

Navigate to Admin Essentials, select Configuration from the left sidebar, locate the task_worker_* configuration parameters, and verify the values match your configuration.

If values don’t match or no initialization messages appear, check configuration file syntax, verify the configuration is at the Platform level, ensure the Platform version is six or newer, and review system logs for configuration errors.

Configure at runtime (immediate, not persistent)

Use the runtime API to adjust rate limits immediately without restarting services. Changes take effect right away but are not persisted across restarts.

1

Call the configuration API

Parameters:

  • task_worker_rate_limit
  • task_worker_rate_limit_period
  • task_worker_thread_count

Example API call:

$curl -L -g -X PUT 'http://localhost:3000/workflow_engine/workers/rate_limit?token=••••••' \
>-H 'Content-Type: application/json' \
>-d '{
>    "rateLimit": 10,
>    "rateLimitPeriod": 1,
>    "threadCount": 2
>}'
2

Verify configuration

Query the configuration API to confirm the new values:

$curl -L -g -X GET 'http://localhost:3000/workflow_engine/workers/rate_limit?token=••••••'

Runtime API changes override configuration file settings until Platform restart. After a restart, configuration loads from files.

Configuration examples

Basic task rate limiting

Enable task rate limiting at 50 tasks per second:

$task_worker_rate_limit=50
$task_worker_rate_limit_period=1

Rate limiting slower than one task per second

Configure rate limiting for very slow task execution:

$task_worker_rate_limit=1
$task_worker_rate_limit_period=5

Result: one task per five seconds (0.2 tasks per second).

Disable rate limiting

$task_worker_rate_limit=0

Task workers process tasks as quickly as possible without rate limiting.

Task rate limiting with multiple workers

Enable task rate limiting with multiple workers to better utilize CPU:

$task_worker_rate_limit=150
$task_worker_rate_limit_period=1
$task_worker_thread_count=3

Result: 150 tasks per second total, ~50 tasks per second per worker.

Adjust for CPU cores

Small instance (4 cores):

$task_worker_rate_limit=100
$task_worker_rate_limit_period=1
$task_worker_thread_count=2

Result: 100 tasks per second total, ~50 tasks per second per worker.

Large instance (12 cores):

$task_worker_rate_limit=200
$task_worker_rate_limit_period=1
$task_worker_thread_count=3

Result: 200 tasks per second total, ~67 tasks per second per worker.

task_worker_thread_count is capped at 4. Start with a lower value and increase incrementally. See Tune rate limits.