Trama | Configuration

Configuration

Defaults live in src/main/resources/application.yaml. Hoplite loads resource and environment sources.

Core Keys

Key	Default	Purpose
`runtime.enabled`	`true`	Enable workers.
`runtime.workerCount`	`4`	Worker concurrency.
`runtime.maxStepsPerExecution`	`25`	Checkpoint cadence.
`runtime.store`	`REDIS`	Execution storage backend.
`redis.topology`	`STANDALONE`	Choose standalone Redis or Redis Cluster client mode.
`redis.cluster.nodes`	`[]`	Cluster seed nodes used when `redis.topology=CLUSTER`.
`redis.queue.keyPrefix`	`saga:executions`	Prefix for shard-aware ready and in-flight queues.
`redis.consumer.batchSize`	`50`	Queue claim batch.
`redis.consumer.processingTimeoutMillis`	`60000`	In-flight lease timeout.
`redis.consumer.requeueIntervalMillis`	`5000`	How often expired in-flight work is requeued.
`redis.sharding.virtualShardCount`	`1024`	Virtual shard fan-out used by rendezvous allocation.
`redis.sharding.membershipKey`	`saga:runtime:pods`	Redis ZSET used for worker membership.
`redis.sharding.membershipTtlMillis`	`10000`	Worker membership expiration window.
`redis.sharding.heartbeatIntervalMillis`	`3000`	How often each worker refreshes its membership entry.
`redis.sharding.refreshIntervalMillis`	`2000`	How often each worker recalculates shard ownership.
`redis.sharding.claimerCount`	`4`	Parallel shard claimers per worker process.
`rateLimit.maxFailures`	`5`	Block threshold.
`metrics.enabled`	`true`	Enable metrics endpoint.
`telemetry.enabled`	`false`	Enable OTEL exporter.

Redis Cluster

Trama now supports Redis Cluster-aware queue sharding. Ready/in-flight keys, execution metadata, and rate-limit keys are written with hash tags so multi-key Lua operations stay inside one Redis slot.

Use redis.topology: CLUSTER to enable the Lettuce cluster client.
Set redis.cluster.nodes to one or more reachable cluster seed nodes.
Keep the same redis.queue.keyPrefix on every worker pod.
Give each worker process a unique redis.sharding.podId so rendezvous ownership is stable.
Tune redis.sharding.virtualShardCount and redis.sharding.claimerCount together when scaling out.

redis:
  topology: "CLUSTER"
  cluster:
    nodes:
      - "redis://redis-cluster-0.redis:6379"
      - "redis://redis-cluster-1.redis:6379"
      - "redis://redis-cluster-2.redis:6379"
  queue:
    keyPrefix: "saga:executions"
  consumer:
    batchSize: 100
    processingTimeoutMillis: 60000
    requeueIntervalMillis: 5000
  sharding:
    podId: "${HOSTNAME}"
    virtualShardCount: 1024
    membershipKey: "saga:runtime:pods"
    membershipTtlMillis: 10000
    heartbeatIntervalMillis: 3000
    refreshIntervalMillis: 2000
    claimerCount: 4

Environment Overrides

Supported overrides include:

RUNTIME_ENABLED
METRICS_ENABLED
TELEMETRY_ENABLED
REDIS_URL
REDIS_TOPOLOGY
REDIS_CLUSTER_NODES
DATABASE_HOST
DATABASE_PORT
DATABASE_DATABASE
DATABASE_USER
DATABASE_PASSWORD

Profiles

Dev profile

runtime:
  workerCount: 2
  emptyPollDelayMillis: 100
metrics:
  enabled: true
telemetry:
  enabled: false

Prod profile (split API and Workers)

In production, run API pods separately from worker pods. API instances should not process queue jobs.

API deployment profile

runtime:
  enabled: false
metrics:
  enabled: true
telemetry:
  enabled: true
database:
  pool:
    maxPoolSize: 20

Worker deployment profile

runtime:
  enabled: true
  workerCount: 8
  bufferSize: 500
  maxStepsPerExecution: 25
redis:
  consumer:
    batchSize: 100
    processingTimeoutMillis: 60000
rateLimit:
  enabled: true
metrics:
  enabled: true
telemetry:
  enabled: true

Worker deployment profile with Redis Cluster

runtime:
  enabled: true
  workerCount: 8
  bufferSize: 500
redis:
  topology: "CLUSTER"
  cluster:
    nodes:
      - "redis://redis-cluster-0.redis:6379"
      - "redis://redis-cluster-1.redis:6379"
      - "redis://redis-cluster-2.redis:6379"
  consumer:
    batchSize: 100
    processingTimeoutMillis: 60000
    requeueIntervalMillis: 5000
  sharding:
    podId: "${HOSTNAME}"
    virtualShardCount: 1024
    membershipKey: "saga:runtime:pods"
    membershipTtlMillis: 10000
    heartbeatIntervalMillis: 3000
    refreshIntervalMillis: 2000
    claimerCount: 4
metrics:
  enabled: true
telemetry:
  enabled: true

Scale workers horizontally by running multiple worker deployments/replicas with this same worker profile.