## Intro Capacity planning for Apache NiFi aligns your dataflow design with compute, memory, disk, and network resources so pipelines run predictably under growth and failure. This guide walks through a repeatable process to size NiFi, validate assumptions with numbers, set safety margins, and identify scaling triggers. You will get: - A repeatable inventory to understand your starting point - Safe configuration steps that control throughput, memory use, and disk footprint - Constructed examples with numbers you can adapt - Verification checks, expected results, and how to diagnose issues - Recovery and rollback paths to keep data safe while tuning - An operations checklist you can re-run as volume and complexity change ## Version and Environment Inventory Before changing anything, capture what you are running and how it is connected. This inventory anchors your plan and will explain 80% of observed performance and limits. Record the following: - Software - NiFi version, Java runtime version - Operating system, kernel, and filesystem type - Topology - Single node or clustered; number of nodes - ZooKeeper ensemble details if clustered - Network links to sources (e.g., Kafka) and sinks (e.g., HDFS, S3) - Hardware - CPU cores and clock per node - RAM per node; JVM heap size (Xmx) - Storage layout: number of disks, SSD/HDD, RAID; mount points for FlowFile, Content, and Provenance repositories - Network bandwidth and latency to key systems - Dataflow characteristics (current and 90-day forecast) - Average and p95 event size (bytes) - Events per second (mean, peak 5-min) - Number of processors and their heavy hitters (e.g., MergeRecord, PutHDFS, PutKafka) - Batch sizes and concurrency on hot processors - Expected retention windows (Content and Provenance) Prerequisites for safe changes: - Access to NiFi UI and the node(s) - Permission to edit nifi.properties and bootstrap.conf - Ability to restart during a safe window - Monitoring of CPU, memory, disk, and NiFi bulletins/logs - Recent backups of configuration files and critical state ## Safe Configuration Path This section shows how to select tunable limits and set safety margins before large changes. The goal is controlled throughput and predictable resource use. Key capacity dimensions to manage:

Dimension	How to measure	Watch signals
Throughput (events/s, MB/s)	NiFi UI component status and connection stats	Sustained rise in queued flowfiles or backpressure engaged
Memory (heap, off-heap)	JVM heap usage, GC pauses	Long GC, OutOfMemoryError, thread yields
Disk I/O and space	iostat, df, repository growth	Repo write latency, >80% space used
Network	iftop/sar, NiFi provenance latencies	Saturation, timeouts, retries

Constructed Example A: workload sizing - Assumptions: 10,000 events/s, 2 KB average size, burst p95 20,000 events/s for 10 min each hour. - Instantaneous bandwidth: 10,000 * 2 KB = 20 MB/s steady; bursts up to 40 MB/s. - Daily volume: 20 MB/s * 86,400 s = 1.728 TB/day steady-state equivalent. ### Set repository layouts and retention - Content Repository - Use multiple disks if available. In nifi.properties , set: nifi.content.repository.directory.default=/data/content1 nifi.content.repository.directory.content2=/data/content2 - Safety margin: keep peak-day volume × flow duration × 2. For the example, if the longest-running flow keeps content for 30 minutes end-to-end, plan for 40 MB/s * 30 min = ~72 GB peak in-flight. With 2x headroom => 144 GB for content repos. Add OS/application free space margin (20-30%). - Provenance Repository - Keep as little as needed for operations/audit. Configure with size-based and time-based retention; example: nifi.provenance.repository.max.storage.time=24 hours nifi.provenance.repository.max.storage.size=200 GB - Constructed estimate: 10,000 events/s at ~700 bytes/event (compressed average) => ~7 MB/s => ~604 GB/day. If you only need 24 hours and can compress more, set size accordingly or reduce retention window. If storage is constrained, raise sampling on high-volume processors or shorten retention. - FlowFile Repository - Keep on fast durable storage; it is small but latency sensitive. Default configuration is typically fine; ensure it is not on the same slow disk as OS if you have SSDs available. ### Backpressure and queuing limits - Set per-connection backpressure to constrain memory and disk use. For the example: - Back pressure object threshold: 300,000 flowfiles - Back pressure data size threshold: 30 GB - These are guardrails; start lower and increase carefully while monitoring GC and repo latency. Prefer controlling upstream rate (e.g., using Max Batch Size and Poll Interval on ConsumeKafka) to endlessly raising backpressure. ### Concurrency and scheduling - Start with total concurrent tasks across hot processors 30% and GC is healthy. - Use Run Duration to prevent excessive context switching on fast processors (e.g., 0 ms to 100 ms as appropriate). - For batch capable processors (e.g., PutKafkaRecord, PutHDFS), prefer larger batch sizes over more threads to reduce overhead. ### JVM heap and GC - In conf/bootstrap.conf , set heap with headroom for content claims and attribute maps. Example for a 64 GB RAM node: java.arg.2=-Xms16g java.arg.3=-Xmx16g - Use G1GC on modern Java (default in recent versions). Monitor GC pause times; aim for p99 ### Networking - If using a cluster, enable connection load balancing where fan-out is needed. Partition by an attribute that preserves locality when necessary (e.g., customerId modulo N) or round-robin when order is unimportant. Constructed Example B: translating growth into nodes - Current: 1 node, 16 cores, 16 GB heap, steady 20 MB/s, 30% CPU idle, low GC pauses. - Growth: plan for 2x volume over 90 days to 40 MB/s steady and 80 MB/s bursts. - Approach: keep the same headroom policy (>=30% idle CPU, repos <=70% used). Add 1 more node with similar specs and enable load-balanced connections for ingress. Re-test; if still near limits, add a third node or raise batch sizes on sinks. ### Configuration snippets to make changes safely - Backup configs: cp conf/nifi.properties conf/nifi.properties.bak.$(date +%F) cp conf/bootstrap.conf conf/bootstrap.conf.bak.$(date +%F) - Apply changes during a maintenance window. Stop, edit, start. bin/nifi.sh status bin/nifi.sh stop # edit configs bin/nifi.sh start - Expected: NiFi starts cleanly; queues resume from prior state; no new error bulletins. ## Verification and Diagnostics After applying configuration changes or adding nodes, verify capacity and stability under representative load. ### What to verify - Flow health - NiFi UI: Are backpressure triangles absent or only brief during bursts? - Connection queue trends: Is the queued count stable around a set point rather than growing unbounded? - CPU and GC - CPU: Keep average <70% during steady-state. Short, higher spikes are fine. - GC: Check nifi-app.log for long pauses; aim for p99 <200 ms. No OutOfMemoryError. - Repositories - df -h on repo mounts: Keep <70% full after a full day of steady-state. - iostat -x 5 3 : Service times should be low; high await suggests disk contention. - Throughput and latency - Component status history: Verify processors meet target events/s and transfer latency is acceptable. - Provenance queries: Spot-check end-to-end lineage times. ### Useful commands and expected outcomes - Check disk space and inode pressure: df -h df -i # Expect repos <70% full, inodes not exhausted - Check disk I/O latency: iostat -x 5 3 # Expect await generally <10-20 ms on SSDs; watch for long tails - Tail logs for bulletins and GC: tail -n 200 -f logs/nifi-app.log # Expect INFO/DEBUG with occasional WARN during restarts; no repeated ERRORs Constructed Example C: expected results for Example A after adding a second node - Target steady throughput: 20 MB/s per cluster (10 MB/s per node on average) - CPU: 40-60% per node steady, peaks to 80% during bursts - Repos: Content <50% used after one day; Provenance within configured 24h/200 GB window - Queues: Short-lived backpressure during 10-minute hourly bursts; drains within 5 minutes after burst ### Diagnostics if expectations are not met - If queues grow despite added nodes: Confirm connection load-balancing is enabled and distributing fairly; examine hotspots (e.g., a single MergeRecord) and parallelize or partition upstream. - If GC pauses rise: Reduce concurrent tasks on attribute-heavy processors; increase heap moderately (e.g., +2 GB) if RAM is available; verify batch sizes to reduce object churn. - If repository latency is high: Spread content repository across more disks; separate FlowFile and Provenance onto different spindles; avoid co-locating with OS on slow disks. ## Failure Modes and Recovery Plan for the most common stress and failure modes so you can recover without data loss. ### Common failure modes, signals, and first actions (constructed thresholds)

Signal	Threshold (example)	First action	If persists
Backpressure engaged	>15 min continuous	Pause upstream ingress; add parallelism on sinks	Add node(s) and enable load-balanced connections
Repo disk usage high	>80% for Content/Provenance	Stop nonessential flows; increase age-off on Provenance	Add disks or expand LVM; rebalance repo directories
GC pauses long	p99 >500 ms	Reduce concurrent tasks; increase batch sizes	Increase heap within RAM limits; profile hotspots
CPU saturation	>90% for 10+ min	Lower concurrency on CPU-bound processors	Scale out cluster nodes
Slow sinks (e.g., HDFS/S3)	Latency up 2x baseline	Reduce batch size to find sweet spot; retry tuning	Throttle inputs; work with sink owners on capacity

### Rollback and recovery procedures - Mis-sized backpressure thresholds - Symptom: Processing stalls, or repos fill too quickly. - Rollback: Revert connection thresholds to prior values noted during change. Drain queues before raising again. - Over-aggressive provenance retention - Symptom: Provenance repo fills up and evicts events needed for audit. - Rollback: Restore prior max.storage.size/time. If emergency space is needed, temporarily raise sampling for the noisiest processors, then revert when storage is expanded. - Heap too small or too large - Symptom: OutOfMemoryError or long GC. - Rollback: Reset Xmx to last known stable value in bootstrap.conf and restart during maintenance window. Investigate object churn (e.g., too many concurrent tasks, small batch sizes) before increasing heap again. - Cluster imbalance - Symptom: One node shows high queues, others idle. - Rollback: Change load-balanced connection strategy from partitioning to round-robin to confirm distribution. If certain processors must be single-threaded, subdivide flows earlier by attribute to spread work. - Repository corruption after abrupt power loss - Symptom: NiFi slow to start or errors about repos. - Recovery: Follow NiFi guidance to allow recovery to replay claims; do not delete repos unless directed and you understand data loss implications. Ensure backups of conf and flow.xml.gz exist. If you must start cleanly, export queued data first via Site-to-Site or by draining to safe storage. ## Operations Checklist Use this repeatable checklist when onboarding a new flow or reviewing capacity each quarter. ### Before changes - Take configuration backups: nifi.properties, bootstrap.conf, authorizers/users if relevant - Note current NiFi version, Java version, node count, repo layout - Capture 24 hours of baseline metrics: throughput, CPU, GC, repo usage ### Sizing and configuration - Estimate event size and rate (avg, p95) and compute daily volume - Set Content repo directories across available disks; keep >30% free space after a day - Set Provenance retention to the minimum needed for operations/audit - Set per-connection backpressure thresholds based on safe in-flight volume - Tune concurrency: total hot processor tasks <= 2 x CPU cores per node - Set heap (Xmx) to leave RAM for OS page cache and NiFi native usage ### Verification after changes - Confirm NiFi starts with no new ERROR logs - Observe queues for 60 minutes at steady load and at least one burst window - Check CPU (<70% steady), GC (p99 <200 ms), repo space (<70%) - Validate end-to-end latency and correctness with provenance spot checks ### Scaling decisions - If any capacity signal is red for >1 review cycle, plan vertical tuning (batch sizes, concurrency, heap) and/or horizontal scaling (additional node(s)) - Document the change, expected effect, and rollback ### Ongoing hygiene - Revisit limits quarterly or after a 25% load change - Keep at least 20-30% headroom across CPU, memory, and repos - Regularly test node restart and cluster failover during maintenance windows ## Conclusion Capacity planning for NiFi is a continuous, observable practice: start with a narrow pilot, size conservatively, verify under realistic load, and scale with clear signals. The constructed examples show how to translate event rates and sizes into disk, memory, and node counts with explicit safety margins. By setting backpressure thoughtfully, tuning concurrency and batch sizes, and separating repositories across appropriate disks, you create predictable behavior and easier operations. ### Your next steps - Build a small, measurable pilot flow that reflects your heaviest pattern - Apply the safe configuration path and record your expected metrics - Run the verification checks and adjust batch sizes and concurrency - Decide on vertical or horizontal scaling based on sustained signals - Institutionalize the checklist so each new flow comes with an explicit capacity plan With these steps, your NiFi deployments will scale smoothly while protecting data integrity and operator time.