How Tuning Parameters Affect celld Performance: Complete Environment Variable Guide

celld performance is controlled entirely through environment variables that govern memory pressure, concurrency limits, operation timeouts, durability guarantees, and background compaction—each parameter creates explicit trade-offs between throughput, latency, and stability.

The celld runtime, maintained by the Deno team at denoland/celld, exposes its operational behavior through a set of tuning knobs defined as environment variables. These parameters directly configure resource allocation, execution limits, and durability semantics. Understanding how each parameter affects celld performance allows operators to optimize deployments for their specific workload characteristics.

Memory Pressure and Resident Cell Limits

CELLD_MAX_RSS_MB: Memory High-Water Mark

CELLD_MAX_RSS_MB sets the upper bound for in-use memory that cells may occupy, functioning as the high-water mark for memory-pressure shedding. The value is parsed by PressureConfig::from_limits in crates/logic/pressure.rs.

• Lower values force earlier shedding, reducing OOM risk but limiting work kept in memory, which lowers throughput
• Higher values allow more cells to remain alive, increasing throughput at the cost of elevated memory pressure

CELLD_MAX_RESIDENT_CELLS: Hard Concurrency Cap

CELLD_MAX_RESIDENT_CELLS imposes a hard limit on resident cells admitted simultaneously. The check occurs in State::has_capacity within crates/logic/cell.rs.

• Tightening the cap throttles active cell concurrency, reducing CPU and I/O load but limiting parallelism
• Loosening the cap raises concurrency, improving latency under load but potentially increasing contention and memory consumption

Cold-Start and Activation Behavior

CELLD_ACTIVATIONS: Concurrent Cold-Start Limit

CELLD_ACTIVATIONS controls the maximum number of concurrent cold-cell activations, defaulting to min(CPU, 128). This semaphore is implemented in runtime::activation_semaphore in crates/celld/runtime.rs.

• Reducing the limit smooths CPU/IO spikes during mass cell starts, at the expense of slower cold-start latency
• Raising the limit enables parallel cell spin-up, improving cold-start latency but risking CPU oversubscription

Operation Timeout and Responsiveness

CELLD_OPERATION_DEADLINE_MS: Global Operation Timeout

CELLD_OPERATION_DEADLINE_MS sets the global timeout for non-restore operations, defaulting to 15 seconds. Enforcement happens in runtime::run_operation in crates/celld/runtime.rs.

• Shorter deadlines abort long-running work sooner, maintaining node responsiveness under heavy load, but may fail legitimate long operations
• Longer deadlines allow heavy jobs to complete, at the risk of hung nodes under overload conditions

Durability and Write Performance

CELLD_OUTPUT_GATE: Write Durability Barrier

CELLD_OUTPUT_GATE (default 1) controls whether each write is acknowledged only after becoming durable in the replication log. The implementation resides in replication::write in crates/celld/replication.rs.

• Enabled (1): Guarantees strong durability but adds write latency
• Disabled (0): Reduces latency and improves write throughput, with the risk of losing recent writes on crash

Worker Pool and Sandbox Memory

CELLD_MAX_LOADED_WORKERS: Loaded Worker Cache Size

CELLD_MAX_LOADED_WORKERS limits workers kept loaded in the sandbox, defaulting to 256. The check occurs in worker_loader::load_worker in crates/celld/worker_loader.rs.

• Lower limits reduce memory pressure from loaded workers, improving overall memory availability
• Higher limits enable more concurrent workers, increasing parallelism but raising memory consumption

LTX Compaction and Storage Optimization

CELLD_LTX_COMPACTION Family

The compaction parameters control additive L1 object creation and L1 compaction concurrency:

• CELLD_LTX_COMPACTION: Master enable/disable flag
• CELLD_LTX_COMPACTION_MIN_TXIDS: Minimum transaction ID threshold before compaction triggers
• CELLD_LTX_COMPACTIONS: Concurrency of compaction attempts

These are implemented in ltx::compaction within crates/ltx/lib.rs.

• Disabling compaction (0) reduces background CPU/I/O but increases read-amplification over time
• Adjusting min-TXID and concurrency balances L1 creation rate against write latency and storage churn

Observability Overhead

CELLD_OTEL and Related Variables

The telemetry system exports internal events via OpenTelemetry:

• CELLD_OTEL: Master enable flag
• CELLD_OTEL_SINK: Export destination (e.g., otlp)
• CELLD_OTEL_FLUSH_MS: Flush interval in milliseconds
• CELLD_OTEL_FLUSH_BYTES: Flush threshold by byte size

Implementation is in crates/celld/telemetry.rs.

• Enabling telemetry adds CPU and network overhead proportional to event volume
• Tuning flush intervals and sizes trades observability data freshness for resource consumption

Practical Configuration Examples

Low-Memory, High-Throughput Profile

export CELLD_MAX_RSS_MB=4096
export CELLD_MAX_RESIDENT_CELLS=2000
export CELLD_ACTIVATIONS=64
export CELLD_OUTPUT_GATE=0
export CELLD_MAX_LOADED_WORKERS=64

Production Durability Profile

export CELLD_MAX_RSS_MB=16384
export CELLD_MAX_RESIDENT_CELLS=8000
export CELLD_ACTIVATIONS=128
export CELLD_OPERATION_DEADLINE_MS=30000
export CELLD_OUTPUT_GATE=1
export CELLD_MAX_LOADED_WORKERS=256

Development Telemetry Profile

export CELLD_OTEL=1
export CELLD_OTEL_SINK=otlp
export CELLD_OTEL_FLUSH_MS=10000
export CELLD_OTEL_FLUSH_BYTES=1048576

Store configurations in a .env file for loading before startup:

# .env

CELLD_MAX_RSS_MB=8192
CELLD_MAX_RESIDENT_CELLS=3000
CELLD_ACTIVATIONS=128

Key Implementation Files

File	Purpose
crates/logic/pressure.rs	Memory-pressure classification and shedding via PressureConfig::classify
crates/celld/runtime.rs	Activation limits, operation deadlines, request routing
crates/celld/replication.rs	Output gate durability control
crates/ltx/lib.rs	LTX compaction parameter handling
crates/celld/telemetry.rs	OpenTelemetry export implementation
crates/celld/worker_loader.rs	Dynamic worker loading and cache limits

Summary

• Memory pressure parameters (CELLD_MAX_RSS_MB, CELLD_MAX_RESIDENT_CELLS) protect against OOM at the cost of potential throughput reduction when limits are tight
• Concurrency controls (CELLD_ACTIVATIONS, CELLD_MAX_LOADED_WORKERS) balance resource saturation against latency under load
• Durability semantics (CELLD_OUTPUT_GATE) offer a direct latency-versus-safety trade-off
• Timeouts and deadlines (CELLD_OPERATION_DEADLINE_MS) ensure responsiveness but may terminate legitimate work
• Background processes (LTX compaction) and observability (OpenTelemetry) consume resources proportionally to their configuration aggressiveness

Frequently Asked Questions

What happens when celld exceeds CELLD_MAX_RSS_MB?

When the in-use memory crosses the CELLD_MAX_RSS_MB threshold, PressureConfig::classify triggers shedding. The node removes cells until memory drops to approximately 80% of the crossing point. This protects the process from OOM kills while maintaining partial availability.

Should I disable CELLD_OUTPUT_GATE for better performance?

Disabling CELLD_OUTPUT_GATE improves write throughput and reduces latency by removing the durability wait. Only disable it when potential data loss on crash is acceptable—typically in development environments or for non-critical caching workloads.

How do I choose the right CELLD_ACTIVATIONS value?

Start with the default min(CPU, 128). Reduce it if you observe CPU throttling or I/O saturation during cold-start spikes. Increase it only on high-core-count machines where parallel cell initialization outweighs oversubscription risks.

Does enabling OpenTelemetry significantly impact celld performance?

OpenTelemetry export adds CPU overhead for event serialization and network overhead for transmission. The impact scales with event volume and flush frequency. Use CELLD_OTEL_FLUSH_MS and CELLD_OTEL_FLUSH_BYTES to batch exports and reduce per-event overhead in production.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}