@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.primary-storage-disk-space.md

@@ -0,0 +1,76 @@
+# Self-Managed resource planning — Primary storage — Disk space
+
+All brokers in a partition use disk space to store:
+
+- The event log for each partition in which they participate. By default, the event log has a minimum size of 128 MB per partition and grows in 128 MB segments. It is truncated once its data has been processed and successfully exported by all loaded exporters.
+- A periodic snapshot of the running state (in-flight data) of each partition. Its size is unbounded and depends on the amount of in-flight work.
+
+Every partition instance hosted by a broker, whether a leader or follower, also uses disk space to store a projection of the partition’s running state in RocksDB. Its size is unbounded and depends on the amount of in-flight work. See [RocksDB](#rocksdb) below to learn how leaders and followers build this state differently.
+
+Use the following formula as a starting point for estimating the required disk space:
+
+```
+neededDiskSpace = replicatedState + localState
+
+replicatedState = totalEventLogSize + totalSnapshotSize
+
+totalEventLogSize = followerPartitionsPerNode * eventLogSize * reserveForPartialSystemFailure
+
+totalSnapshotSize = partitionsPerNode * singleSnapshotSize * 2
+// singleSnapshotSize * 2:
+//   the last snapshot (already replicated) +
+//   the next snapshot (in transit, while it is being replicated)
+
+partitionsPerNode = leaderPartitionsPerNode + followerPartitionsPerNode
+
+leaderPartitionsPerNode = partitionsCount / numberOfNodes
+followerPartitionsPerNode = partitionsCount * replicationFactor / numberOfNodes
+
+clusterSize = [number of broker nodes]
+partitionsCount = [number of partitions]
+replicationFactor = [number of replicas per partition]
+reserveForPartialSystemFailure = [factor to account for partial system failure]
+singleSnapshotSize = [size of a single RocksDB snapshot]
+eventLogSize = [event log size for duration of snapshotPeriod]
+```
+
+- `eventLogSize` scales with the throughput of your system.
+- `totalSnapshotSize` scales with the number of in-flight process instances.
+- `reserveForPartialSystemFailure` is a reserve to account for partial system failure, such as loss of quorum inside the cluster or loss of connection to an external system. See [effects on disk growth](#effects-on-disk-growth) below.
+
+The relevant configuration settings are:
+
+```yaml
+camunda:
+  cluster:
+    partition-count: 1
+    replication-factor: 1
+    size: 1
+  data:
+    snapshot-period: 5m
+    primary-storage:
+      log-stream:
+        log-segment-size: 128MB
+```
+
+| Environment variable                                   | Default |
+| ------------------------------------------------------ | ------- |
+| `CAMUNDA_DATA_PRIMARYSTORAGE_LOGSTREAM_LOGSEGMENTSIZE` | `128MB` |
+| `CAMUNDA_DATA_SNAPSHOTPERIOD`                          | `5m`    |
+| `CAMUNDA_CLUSTER_PARTITIONCOUNT`                       | `1`     |
+| `CAMUNDA_CLUSTER_REPLICATIONFACTOR`                    | `1`     |
+| `CAMUNDA_CLUSTER_SIZE`                                 | `1`     |
+
+Other factors are best observed in a production-like system under representative throughput.
+
+By default, this data is stored in the following directories:
+
+- `segments`: The append-only log, split into segments. Data can be deleted once it becomes part of a new snapshot.
+- `state`: The active state (deployed processes, active process instances, and so on). Completed process instances or jobs are removed.
+- `snapshot`: A state at a certain point in time.
+
+**Caution: Avoid unbounded log growth**
+Do not configure an exporter that does not advance its record position, such as the Debug Exporter. If you configure an exporter, monitor its availability and the health of its dependencies. An exporter that stops advancing prevents log truncation, causing data to accumulate on disk until the issue is resolved. See [effects on disk growth](#effects-on-disk-growth).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.primary-storage-effects-on-disk-growth.md

@@ -0,0 +1,12 @@
+# Self-Managed resource planning — Primary storage — Effects on disk growth
+
+**Exporter or external system failure.** If a system an exporter depends on fails (for example, a lost connection to Elasticsearch), the exporter stops advancing its position and brokers can't truncate their logs. The log grows until the connection is restored. Size broker disks with enough headroom to keep operating through an outage.
+
+During a [hot backup (soft-pause window)](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/operations/management-api#soft-pause-exports), log compaction is intentionally blocked for the backup's duration. This adds a predictable, temporary disk requirement: roughly `throughput × backup_window_duration` of extra log data per partition, replicated across followers. Size disks with headroom for at least one full backup window on top of steady-state estimates.
+
+**Node failure.** Only the leader exports events, and only committed (replicated) events are passed to exporters. An exporter's read position is only captured in snapshots, never in the event log itself; it can't be reconstructed from the log alone. When a partition fails over to a new leader, the new leader reconstructs state by projecting the log from the last snapshot, but the exporter position resets to that snapshot too. This means an exporter can see the same events twice after a failover. Assign idempotent IDs in your exporter (the combination of record position and partition ID is a reliable unique key) if this matters for your system.
+
+**Quorum loss.** If a partition drops below quorum (for example, two nodes down in a three-node cluster), the leader keeps accepting requests, but they aren't replicated or committed, so they can't be truncated, and the event log grows. The disk space needed to ride this out is a function of broker throughput and how long it takes to restore quorum; size nodes with enough headroom to absorb this failure mode.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.primary-storage-event-log.md

@@ -0,0 +1,19 @@
+# Self-Managed resource planning — Primary storage — Event log
+
+The event log for each partition is segmented. By default, the segment size is 128 MB. The event log grows over time unless and until individual segments are deleted.
+
+An event log segment can be deleted once:
+
+- All the events it contains have been processed by exporters.
+- All the events it contains have been replicated to other brokers.
+- All the events it contains have been processed.
+
+The following conditions inhibit automatic deletion:
+
+- The cluster loses quorum. Events are queued but not processed until quorum is reestablished.
+- An exporter does not advance its read position. The event log grows without bound.
+
+Exporting occurs only on the partition leader. Followers do not delete their replicas of a segment until the leader marks the segment as no longer needed by exporters. A segment is not deleted until a snapshot that includes it has been taken, and only log entries up to that snapshot can be deleted.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.primary-storage-rocksdb.md

@@ -0,0 +1,8 @@
+# Self-Managed resource planning — Primary storage — RocksDB
+
+The leader of a partition processes commands and applies committed events to its RocksDB state. Followers continuously replay the same committed events into their local RocksDB state without processing commands, keeping them warm and ready for fast failover if the leader changes.
+
+In practice, the RocksDB state of a partition grows to around 2 GB under heavy load with long-running processes. Snapshot replication brings new or lagging followers fully up to date; it is not how followers normally maintain their state.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.primary-storage-snapshots.md

@@ -0,0 +1,9 @@
+# Self-Managed resource planning — Primary storage — Snapshots
+
+The running state of a partition is captured periodically on the leader. By default, a snapshot is taken every five minutes, as configured by `snapshot-period`. A snapshot is a projection of all events that represent the current running state, including deployed processes, active process instances, and jobs that have not yet been completed. Writing a new snapshot deletes all log data written before the snapshot.
+
+**Note**
+The snapshot interval was tested in a Zeebe Chaos experiment. Learn more in the [Zeebe Chaos blog](https://camunda.github.io/zeebe-chaos/2022/02/01/High-Snapshot-Frequency/#snapshot-interval).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.primary-storage.md

@@ -0,0 +1,8 @@
+# Self-Managed resource planning — Primary storage
+
+Primary storage must use low-latency **SSDs**, as HDD-backed volumes are not supported. Disk **latency**, rather than throughput, is the critical metric. Cloud providers often report similar throughput figures for HDD and SSD volumes, but the difference in latency is what matters for Camunda. In testing, HDD-backed primary storage reduced throughput by approximately 50% compared with SSDs, increased commit latency, and triggered additional Raft snapshot replication between brokers.
+
+See [Command processing path](https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow#command-processing-path) for the architectural context on why disk latency sits on the critical path, the [reference architecture minimum cluster requirements](https://docs.camunda.io/docs/next/self-managed/reference-architecture/kubernetes#minimum-cluster-requirements) for concrete per-platform disk recommendations, and the [slow disk chaos day experiment](https://camunda.github.io/zeebe-chaos/2026/06/19/Using-slow-disk-with-Camunda) for the detailed findings.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.scale-your-cluster.md

@@ -0,0 +1,24 @@
+# Self-Managed resource planning — Scale your cluster
+
+Once you have a baseline configuration running, you can scale in several ways:
+
+### Horizontal scaling
+
+Add more brokers and partitions to increase throughput capacity. Partitions can be [scaled up](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/operations/cluster-scaling) but not down, so avoid over-provisioning.
+
+When scaling horizontally, **secondary storage often becomes the limiting factor**. Adding brokers increases export volume to Elasticsearch/OpenSearch. If secondary storage isn't scaled accordingly, it will bottleneck overall throughput. See [Elasticsearch scaling](#elasticsearch-scaling) for guidance.
+
+### Vertical scaling
+
+Increase CPU and memory per broker. Note that there are **diminishing returns** due to component interdependencies. For example, Elasticsearch indexing speed can bottleneck broker throughput.
+
+### Elasticsearch scaling
+
+- **Memory:** Increase Elasticsearch memory to store more historical data without performance degradation.
+- **Nodes:** Add Elasticsearch statefulset replicas for more IOPS and query throughput.
+- **Disk size:** Increase disk size based on your data retention requirements. With Optimize enabled and a realistic payload (~11 KB), Elasticsearch disk can fill rapidly (for example, 128 Gi in under 12 hours at 1 PI/s with 30-day retention).
+- **Disk type:** Use SSDs for Elasticsearch storage. Disk latency, not throughput, is the critical factor. HDD-backed Elasticsearch has been observed to cause 8–10s flush durations, a growing export backlog, increased broker memory from in-flight records, and up to ~70% throughput degradation versus an equivalent SSD setup. See the [slow disk chaos day experiment](https://camunda.github.io/zeebe-chaos/2026/06/19/Using-slow-disk-with-Camunda) for details, and [Export pipeline](https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow#export-pipeline) for background on how slow secondary storage affects overall throughput.
+- **Index replicas:** The disk estimates in the baseline tables above do not account for index-level replicas. In multi-node clusters, configure at least one replica per index for fault tolerance. Each replica stores a full copy of the primary shard data, approximately doubling total disk usage. See [managing replicas](https://docs.camunda.io/docs/next/self-managed/concepts/secondary-storage/managing-secondary-storage#replicas).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.secondary-storage-considerations.md

@@ -0,0 +1,14 @@
+# Self-Managed resource planning — Secondary storage considerations
+
+The resource tables above assume Elasticsearch as the secondary storage backend. If you are using a different backend:
+
+- **OpenSearch:** Similar resource profile to Elasticsearch. The tables above generally apply.
+- **RDBMS (PostgreSQL, available from 8.9):** Replace the Elasticsearch resource block with appropriately sized PostgreSQL resources. Adjust throughput expectations **downward by approximately 30%** compared to the Elasticsearch-based tables. Unlike Elasticsearch, RDBMS scales primarily **vertically** (a larger instance) rather than horizontally, so plan your initial sizing with more headroom, as adding capacity later is more disruptive.
+
+**Note**
+Optimize is not supported with RDBMS. If you need Optimize, you must also run Elasticsearch alongside your RDBMS.
+
+See [Secondary storage](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment#secondary-storage) for more details.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.md

@@ -0,0 +1,13 @@
+# Size your environment
+
+Understand the aspects relevant to Camunda 8 sizing. Once you do, use the sizing recommendations for [SaaS](sizing-saas.md) or [Self-Managed](sizing-self-managed.md) to select your appropriate configuration.
+
+Understand the aspects relevant to Camunda 8 sizing. Once you do, use the sizing recommendations for [SaaS](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas) or [Self-Managed](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed) to select your appropriate configuration.
+
+**Tip: Before you size**
+See [Data flow](https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow) first to understand the factors that drive the recommendations on this page.
+
+<!-- Anchors for backward compatibility with old single-page URLs -->
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.next-steps.md

@@ -0,0 +1,12 @@
+# Size your environment — Next steps
+
+Now that you understand the factors that influence sizing:
+
+- **SaaS customers:** [Size your SaaS cluster](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas) to select the right cluster size.
+- **Self-Managed admins:** Provision your Kubernetes cluster using these [baseline resource settings](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed).
+- **Validate sizing:** [Run your own benchmarks](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks) to test your specific workload.
+
+For current secondary storage benchmarks, see [RDBMS benchmark results](https://docs.camunda.io/docs/next/self-managed/concepts/secondary-storage/rdbms-benchmark-results).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.plan-non-production-environments.md

@@ -0,0 +1,17 @@
+# Size your environment — Plan non-production environments
+
+All clusters can be used for development, testing, integration, Q&A, and production.
+
+For typical integration or functional test environments, you can usually deploy a small cluster even if your production environment is sized larger. This is typically sufficient, as functional tests run much smaller workloads.
+
+Load or performance tests should ideally run on the same sizing configuration as your production cluster to yield reliable results.
+
+A typical customer setup consists of:
+
+- A production cluster.
+- An integration or pre-production cluster (equal in size to your anticipated production cluster if you want to run load tests or benchmarks).
+- A test cluster.
+- Development clusters.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-data-availability-latency.md

@@ -0,0 +1,12 @@
+# Size your environment — Sizing requirements and influencing factors — Data availability latency
+
+Data availability latency is the time between an event occurring in the engine and it being queryable in Operate, Tasklist, or Optimize. Under heavy load or with Optimize enabled, this can lag from seconds to minutes.
+
+Data availability latency is influenced by:
+
+- **Exporter throughput:** The rate at which the Camunda Exporter can write events to Elasticsearch (ES).
+- **Elasticsearch indexing speed:** How quickly ES can index incoming documents.
+- **Elasticsearch disk usage:** High disk utilization (above ~70%) significantly increases indexing latency. Monitor ES disk usage and scale storage before hitting this threshold.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-disk-space.md

@@ -0,0 +1,11 @@
+# Size your environment — Sizing requirements and influencing factors — Disk space
+
+The workflow engine stores data for each process instance, especially to persist the current state.
+In addition, it sends data to secondary storage (Elasticsearch, OpenSearch, or an RDBMS) for indexing, search, analytics, and long-term retention.
+
+You can configure retention times for data stored in secondary storage.
+
+For Self-Managed, see [Disk space](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed#disk-space) for the formula and mechanics behind Zeebe's primary storage disk usage.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-impact-of-optimize-2.md

@@ -0,0 +1,46 @@
+# Size your environment — Sizing requirements and influencing factors — Impact of Optimize (2)
+
+#### Mitigations
+
+##### Keep variables out of Optimize (highest impact, lowest risk)
+
+Variables account for most of Optimize's storage and CPU usage in the secondary storage layer. In benchmarks, disabling Optimize's variable storage reduced its disk usage by a factor of **approximately 14** relative to the raw export. Isolating a group of customer-related variables showed an even larger difference, a factor of **approximately 29**, driven primarily by object variable flattening, described below, rather than by the variable values themselves. See [Optimize data flow](https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow#optimize-data-flow) for an explanation of the underlying storage mechanism.
+
+Almost all of this cost comes from Optimize's indices. The following three levers are listed from most to least aggressive:
+
+- **Stop exporting variables entirely.** Set `camunda.data.exporters.elasticsearch.args.index.variable: false` (OpenSearch: `camunda.data.exporters.opensearch.args.index.variable: false`) at the exporter to drop all variable records. This is the only lever that also recovers throughput because the exporter write path is the bottleneck at maximum load.
+- **Export only the variables you need (name and prefix filters).** Keep a subset with name or prefix filters, for example only `customer`-prefixed variables. Use this when some variables drive Optimize reports, but most are noise. On SaaS, configure variable name filters in [cluster settings](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/settings#data-filters). On Self-Managed, see [Optimize export filtering](https://docs.camunda.io/docs/next/self-managed/components/optimize/configuration/optimize-export-filtering).
+- **[Disable variable import](https://docs.camunda.io/docs/next/self-managed/components/optimize/configuration/variable-import) in Optimize.** Available on all supported versions; achieves the storage savings but does not recover throughput, because the records are still written by the exporter.
+
+**Trade-off:** Filtered variables are unavailable in Optimize reports, including variable filters, variable-based grouping, and raw-data variable columns. These levers affect **Optimize only**; Operate and Tasklist read through the Camunda Exporter, so their variables stay intact.
+
+##### Disable object variable flattening (high impact for object-heavy processes)
+
+By default, Optimize [flattens each object variable](https://docs.camunda.io/docs/next/self-managed/components/optimize/configuration/object-variables) into a separate variable for each property and stores the full raw object as another variable. Each generated variable incurs its own storage cost, so an object variable with several properties can require several times more storage than a single scalar variable.
+
+If you don't rely on flattened object-variable filtering, grouping, or raw-data columns in Optimize reports, disable it by setting:
+
+- Environment variable: `CAMUNDA_OPTIMIZE_ZEEBE_INCLUDE_OBJECT_VARIABLE=false`
+- Configuration property: `zeebe.includeObjectVariableValue: false`
+
+**Note**
+This behavior is enabled by default in Self-Managed and disabled in Camunda 8 SaaS.
+
+In an isolated benchmark that changed only this setting for the same workload:
+
+- Optimize's share of total Elasticsearch disk usage dropped from 62.8% to 7.6%, a reduction by a factor of 8.3.
+- Total secondary storage per created process instance dropped from 6.34 MB to 2.97 MB, a reduction by a factor of 2.13. This reduction was smaller because the setting does not affect Zeebe or Camunda Exporter storage.
+
+See [Confirming Optimize's object variable flattening cost with a controlled A/B test](https://camunda.github.io/zeebe-chaos/2026/07/09/Optimize-Object-Variable-Flattening/) for the complete methodology and additional measurements.
+
+**Warning**
+These ratios are specific to the benchmark's payload and process models; they are not universal constants. Object variable flattening processes nested JSON recursively without a depth limit, so payloads with deeper nesting or more object fields can require considerably more storage than measured here. Measure your workload before using these numbers for capacity planning.
+
+##### Other mitigations
+
+- **Run Optimize on a separate Elasticsearch/OpenSearch instance.** Contention is bidirectional: Optimize's write spikes degrade Operate, Tasklist, and the Camunda Exporter, while heavy exporter activity degrades Optimize import. Isolation removes this mutual interference.
+- **Tune retention periods.** Shorter retention means less data in Elasticsearch/OpenSearch and better performance.
+- **Increase import throughput if Optimize lags.** If you notice a significant lag between the rate of exported Zeebe records and imported Optimize data, raise `CAMUNDA_OPTIMIZE_ZEEBE_MAX_IMPORT_PAGE_SIZE` so each import cycle fetches more exported records. This helps Optimize keep pace under high load, but increases memory use per fetch and can negatively impact individual record latency, as Optimize must wait to fill larger batches before processing.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-impact-of-optimize-3.md

@@ -0,0 +1,30 @@
+# Size your environment — Sizing requirements and influencing factors — Impact of Optimize (3)
+
+#### Elasticsearch/OpenSearch shard budget
+
+**Warning**
+Optimize creates a dedicated index per deployed process definition, each using at least one shard. Elasticsearch and OpenSearch cap the number of shards per node (1,000 by default), so a cluster's total shard budget is `nodes × per-node limit` (for example, 3,000 on a three-node cluster). A large or growing number of deployed process definitions consumes this budget and can approach the ceiling; small development or test clusters with few nodes reach it quickly. Once the ceiling is hit, new index creation is rejected, which cascades into exporter backpressure and stalled processing.
+
+Account for shard budget when sizing the Elasticsearch/OpenSearch cluster, not just CPU, memory, and disk. See [impact of high process deployments on Elasticsearch](https://camunda.github.io/zeebe-chaos/2026/05/28/Impact-of-High-Process-Deployments-on-Elasticsearch).
+
+#### Zeebe record ILM retention
+
+When the [Elasticsearch exporter retention policy](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/exporters/elasticsearch-exporter#retention) is enabled, Zeebe record indices are deleted after the configured `minimum-age`. Optimize reads from these same indices, so the retention window must be long enough to cover Optimize's worst-case import lag. If the exporter deletes records before Optimize imports them, process instance completion events are permanently lost: Optimize records the instance as `ACTIVE` with no `endDate`, and history cleanup can never remove it.
+
+**Minimum recommended retention:** Set `minimum-age` to at least **3 days** when running Optimize; **7 or more days** is recommended. This provides headroom for:
+
+- Import lag that grows as the Optimize process instance index grows larger.
+- Recovery time after Elasticsearch cluster events such as node restarts, rolling upgrades, and shard rebalancing.
+
+The default `minimum-age` of `30d` provides sufficient headroom. If you reduced it to limit disk usage, verify that the new value still exceeds your observed Optimize import lag before applying it to production.
+
+**Disk sizing:** A longer ILM retention window means Zeebe record indices are kept on disk longer before deletion. Factor the additional raw exporter index volume into your Elasticsearch disk budget when increasing `minimum-age` beyond the default.
+
+**Self-reinforcing failure mode:** As Optimize's process instance index grows, Elasticsearch write latency increases, which raises per-batch import lag. Higher import lag increases the probability of an ILM race on the next cluster event. This cycle compounds on long-lived clusters running at sustained load. To break it, increase ILM retention and reduce the Optimize index size through history cleanup or variable filtering.
+
+**Symptom:** If Optimize history cleanup runs on schedule but consistently completes in zero seconds against a large dataset, orphaned `ACTIVE` documents are likely accumulating. See [diagnosing stalled cleanup](https://docs.camunda.io/docs/next/self-managed/components/optimize/configuration/history-cleanup#diagnosing-stalled-cleanup).
+
+The sizing guidance for [Self-Managed](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed#baseline-resource-configuration) provides configurations with and without Optimize to help you plan accordingly.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-impact-of-optimize.md

@@ -0,0 +1,46 @@
+# Size your environment — Sizing requirements and influencing factors — Impact of Optimize
+
+Optimize is an optional component that provides process analytics and reporting. When enabled, it has significant implications for sizing.
+
+**Note**
+The data below comes from Camunda 8.9 load tests. Because 8.8 and 8.9 share the same exporter architecture, it applies to 8.8+ as well.
+
+#### In short
+
+- Enabling Optimize roughly **triples to quadruples Elasticsearch CPU and disk usage** at a [realistic workload](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks#reference-benchmark-scenario) (around 3.4x CPU and 3.6x disk), largely independent of throughput.
+- It lowers achievable **processing throughput by 25-50% at maximum load** on the same hardware.
+- The single most effective mitigation is to **keep variables out of Optimize**. This recovers around 60% of the storage and 65% of the CPU, plus most of the lost throughput, at the cost of variable-based analytics.
+- Size Elasticsearch/OpenSearch accordingly (CPU, disk, **and shard budget**), or run Optimize on a **dedicated Elasticsearch/OpenSearch instance**.
+
+For how Optimize fits into the export pipeline, see [Optimize data flow](https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow#optimize-data-flow). The full studies behind these numbers are [Impact of Optimize on Camunda](https://camunda.github.io/zeebe-chaos/2026/06/10/Impact-of-Optimize-on-Camunda) and [Reducing Optimize's Elasticsearch overhead](https://camunda.github.io/zeebe-chaos/2026/06/25/Impact-of-Optimize-Variable-Filtering).
+
+#### Why Optimize matters for sizing
+
+- Optimize is a second-tier consumer of the export pipeline: the Elasticsearch/OpenSearch exporter writes raw engine events, Optimize's importer reads them and writes its own analytics indices back to Elasticsearch/OpenSearch, so data is written to secondary storage twice. See [Optimize data flow](https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow#optimize-data-flow).
+- In Camunda 8.8+, the Camunda Exporter and the Elasticsearch exporter run in the same thread within the broker, so Optimize data-pipeline competes directly with core platform exporting for throughput.
+- The overhead is **not proportional to throughput.** It scales with process model complexity (multi-instance and call activities) and variable volume. At a realistic workload where Optimize-enabled and Optimize-disabled clusters reached identical throughput with zero backpressure, the Optimize-enabled cluster still consumed **around 3.4x more Elasticsearch CPU.** Budget for this even at comfortable throughput.
+
+#### What Optimize affects
+
+At a [realistic workload](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks#reference-benchmark-scenario), with Optimize enabled vs. disabled:
+
+- **Elasticsearch CPU:** around 3.4x higher.
+- **Elasticsearch disk:** around 3.6x more total data.
+- **Throughput:** unaffected at a realistic workload, but 25-50% lower at maximum load on the same hardware.
+- **Write-to-exporting latency:** around 2.6x higher.
+- **Backpressure at maximum load:** around 45% with Optimize vs. 35% without.
+- **Individual import latency:** increases approximately linearly with payload size.
+- **Report loading times:** increase approximately linearly with the data complexity (such as process instances and variables) and as historical data accumulates.
+
+Secondary storage memory is not a meaningful differentiator for improving performance.
+
+**Tip**
+**Watch Optimize import lag.** When Optimize's importer falls behind the export rate, two problems can appear:
+
+- **Optimize's analytics indices grow.** Optimize keeps one document per process instance and can only apply retention-based cleanup once its importer has processed the instance's completion. While the importer lags, completions are recorded late, cleanup is deferred, and Optimize's own indices grow beyond their steady-state size.
+- **Data can be missed.** The raw exporter indices are cleaned up on the Elasticsearch/OpenSearch retention schedule. If the importer falls far enough behind, those records are deleted before Optimize imports them, and that data never reaches Optimize. This Exporter-Importer hazard is exactly what the 8.8 Camunda Exporter architecture removed for Operate and Tasklist.
+
+Track import progress with the [Optimize metrics and bundled Grafana dashboards](https://docs.camunda.io/docs/next/self-managed/operational-guides/monitoring/metrics). If you see persistent import lag, raise the import throughput (see [mitigations](#mitigations) for details).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-job-worker-capacity.md

@@ -0,0 +1,15 @@
+# Size your environment — Sizing requirements and influencing factors — Job worker capacity
+
+Even when your cluster has spare throughput capacity, an undersized job worker can still allow jobs to accumulate in the backlog. Worker capacity requires its own sizing exercise, separate from cluster sizing.
+
+The workflow engine delivers jobs to workers through two paths that share a worker's capacity but behave differently: [Job streaming pushes a job as soon as it becomes available for activation](https://docs.camunda.io/docs/next/components/concepts/job-workers#how-job-streaming-and-polling-deliver-jobs), while polling is the only path that drains jobs already queued in the backlog.
+
+Therefore, healthy throughput does not indicate whether the backlog is draining; they are independent signals. The backlog can continue to grow after workers recover from an outage, even when throughput appears to have fully recovered. See [impact of worker downtime on a realistic load test](https://camunda.github.io/zeebe-chaos/2026/08/06/worker-downtime-throughput-recovery) for more details.
+
+**Note**
+There is currently no built-in metric that directly reports the size of this backlog.
+
+Size the worker’s capacity according to its concurrency model and the job timeout. For the Java client’s fixed-thread-pool model, see [sizing `maxJobsActive` against execution threads](https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers#size-maxjobsactive-against-execution-threads). Other client SDKs implement worker capacity differently and are not covered by this formula.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-latency-and-cycle-time.md

@@ -0,0 +1,34 @@
+# Size your environment — Sizing requirements and influencing factors — Latency and cycle time
+
+In some use cases, process cycle time (or even individual task cycle time) matters. For example, you might expose a REST endpoint that starts a process instance to calculate a customer score. The process runs four service tasks, and the REST request must return synchronously within 250 ms.
+
+While service-task duration depends on the work performed, you can measure the workflow engine’s own overhead.
+
+<!-- TODO: Replace the following latency measurements with current 8.8/8.9 benchmark data. The old measurements (Camunda 8 1.2.4: ~10 ms/node, ~50 ms remote worker latency) are outdated. -->
+
+**Note**
+The latency measurements below are approximate and were last validated against an earlier version of Camunda 8. Updated measurements for 8.8/8.9 are pending. With the 8.8 streamlined architecture and properly aligned resources (3.5 CPU cores per broker), latency is expected to improve by approximately 2x compared to the previous distributed deployment.
+
+Actual latency is highly environment-dependent — factors like network latency between workers and the cluster, disk I/O speed (commit latency), and cloud region placement significantly affect these numbers.
+
+As a rough estimate, you can expect:
+
+- Single-digit millisecond processing time per process node.
+- Approximately 50 ms latency to process service tasks in remote workers when running worker code in the same cloud region as the Camunda cluster.
+
+Hence, executing four service tasks results in roughly 200-250 ms workflow engine overhead.
+
+As you push throughput toward the cluster’s limits, latency increases because requests compete for resources, especially disk writes. If cycle time and latency matter, leave enough headroom and avoid running the cluster near full utilization to prevent resource contention.
+
+**Tip**
+A good rule of thumb is to size for about **20x your average load**. This gives you capacity for peaks and keeps latency low during normal operation.
+
+| Indicator                                                      |    Number | Calculation method | Notes                                                                                      |
+| :------------------------------------------------------------- | --------: | :----------------: | :----------------------------------------------------------------------------------------- |
+| Onboarding instances per year                                  | 5,000,000 |                    | Business input.                                                                            |
+| Expected process instances on peak day                         |   150,000 |                    | Business input.                                                                            |
+| Process instances per second within business hours on peak day |      5.20 |   / (8\*60\*60)    | Only looking at the seconds within the eight business hours of a day.                      |
+| Process instances per second including buffer                  |    104.16 |       \* 20        | Adding some buffer is recommended for critical, high-performance or low-latency use cases. |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-payload-size.md

@@ -0,0 +1,24 @@
+# Size your environment — Sizing requirements and influencing factors — Payload size
+
+Each process instance can hold a payload, known as [process variables](https://docs.camunda.io/docs/next/components/concepts/variables). The workflow engine must manage the variables for all running instances, and data from both running and completed process instances is forwarded to Operate and Tasklist.
+
+Process variable size affects resource requirements. For example, there’s a big difference between storing a few strings (around 1 KB) and storing a full 1 MB JSON document. That’s why payload size is a key sizing factor.
+
+Camunda's official benchmarks use two reference payloads:
+
+- [**Typical payload**](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/typical_payload.json): Used for baseline measurements (~0.5 KB, 15 simple variables).
+- [**Realistic payload**](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/realisticPayload.json): Used for the reference sizing benchmarks. This better represents real-world payloads (~11 KB).
+
+**Note**
+Payload size has a multiplicative effect, affecting Zeebe storage, Elasticsearch export volume, Optimize import time, and query/report performance. An 11 KB payload vs. a 0.5 KB payload can change disk consumption by **10-20x**.
+
+Consider these general rules for payload size:
+
+- The maximum [variable size per process instance is limited](https://docs.camunda.io/docs/next/components/concepts/variables#variable-size-limitation), currently to roughly three MB.
+- Camunda does not recommend storing large amounts of data in your process context. Refer to our [best practices on handling data in processes](https://docs.camunda.io/docs/next/components/best-practices/development/handling-data-in-processes) for more details.
+- An AI agent's [agent context](https://docs.camunda.io/docs/next/components/agentic-orchestration/agent-definitions-and-instances#agent-context-and-memory) is a process variable that grows with each loop iteration, so it counts toward this limit. Switch the agent's memory to [Camunda document storage](https://docs.camunda.io/docs/next/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess#choose-a-memory-storage-backend) when a long conversation would outgrow it.
+- Each [partition](https://docs.camunda.io/docs/next/components/zeebe/technical-concepts/partitions) of the Zeebe installation can typically handle up to one GB of payload in total. Larger payloads can lead to slower processing. For example,
+  one million process instances with four KB each is about 3.9 GB, so you need at least four partitions. In practice, you’d typically use six partitions, since the number of partitions is usually a multiple of the replication factor (three by default).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-peak-loads.md

@@ -0,0 +1,10 @@
+# Size your environment — Sizing requirements and influencing factors — Peak loads
+
+In most scenarios, your load will be volatile rather than constant. For example, your company might start 90% of its monthly process instances on a single day of the month. The **ability to handle those peaks is the more crucial requirement and should drive your decision**, rather than the average load.
+
+In this example, that single peak day defines your overall throughput requirements.
+
+In addition, sizing for peaks may mean you shouldn’t assume a full 24-hour day. Instead, you might size for just the eight business hours, or even the busiest two hours—depending on your workload.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-secondary-storage.md

@@ -0,0 +1,32 @@
+# Size your environment — Sizing requirements and influencing factors — Secondary storage
+
+Starting with Camunda 8.9, the platform supports three secondary storage backends, each with different sizing implications.
+
+#### Elasticsearch (default)
+
+- The **most mature and most benchmarked** option.
+- Required if you use Optimize.
+- Provides full-text search capabilities used by Operate and Tasklist.
+
+**Important**
+Sizing data provided throughout this guide assumes Elasticsearch unless stated otherwise.
+
+#### OpenSearch
+
+- A drop-in alternative to Elasticsearch with a similar resource profile.
+- Supported for all components including Optimize. See [supported environments](https://docs.camunda.io/docs/next/reference/supported-environments) for more details.
+- Sizing recommendations for Elasticsearch generally apply to OpenSearch as well.
+
+#### RDBMS
+
+- A different storage paradigm: a relational database instead of a document store. See the full list of [supported databases](https://docs.camunda.io/docs/next/self-managed/concepts/databases/relational-db/rdbms-support-policy#supported-rdbms).
+- A different resource profile: CPU/memory-oriented rather than disk/IOPS-oriented.
+- Write throughput is approximately **70% of Elasticsearch** on equivalent hardware.
+- **No Optimize support**: If you need Optimize, you must run Elasticsearch alongside RDBMS.
+- **Scales primarily vertically** rather than horizontally like Elasticsearch. Plan initial sizing with more headroom, as adding capacity is more disruptive.
+- Ideal for organizations that already operate a supported RDBMS at scale and want to avoid adding Elasticsearch to their infrastructure.
+  <!-- To be validated - Potentially lower total disk space required for the same data volume (preliminary benchmarks suggest this, but detailed results are still being validated). -->
+  <!-- TODO: Link to RDBMS benchmark results page once PR #8159 is merged -->
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors-throughput.md

@@ -0,0 +1,31 @@
+# Size your environment — Sizing requirements and influencing factors — Throughput
+
+Throughput defines how many process instances can be executed within a certain timeframe.
+
+It is typically easy to estimate the number of process instances per day you need to execute.
+However, hardware sizing depends more on the **number of BPMN tasks** in a process model. If you already know your future process model, you can use it to count the number of tasks in the process. For example, the following onboarding process contains five service tasks in a typical execution:
+
+Diagram (BPMN):
+  start "Application received" → service task "Get credit score" → business rule task "Check application automatically" → exclusive gateway "Risk?"
+    — [green (no risk): = riskLevel = "green"] exclusive gateway → service task "Deliver confirmation" → send task "Send confirmation" → end "Application issued"
+    — [yellow (moderate risk): = riskLevel = "yellow"] user task "Decide on application" → exclusive gateway "Decision?"
+      — [application accepted: = approved] (back to exclusive gateway)
+      — [application declined: = not(approved)] exclusive gateway → service task "Reject application" → send task "Send rejection" → end "Application rejected"
+    — [red (high risk): =risklevel = "red"] (back to exclusive gateway)
+
+**Tip**
+If you don't yet know the number of service tasks, Camunda recommends assuming **10 service tasks** as a rule of thumb.
+
+The number of tasks per process allows you to calculate the number of tasks per day. You can also convert this to tasks per second. For example:
+
+| Indicator                          |    Number | Calculation method | Notes                                        |
+| :--------------------------------- | --------: | :----------------: | :------------------------------------------- |
+| Onboarding instances per year      | 5,000,000 |                    | Business input.                              |
+| Process instances per business day |    20,000 |       / 250        | Average number of working days in a year.    |
+| Tasks per day                      |   100,000 |        \* 5        | Tasks in the process model as counted above. |
+| Tasks per second                   |      1.16 |   / (24\*60\*60)   | Seconds per day.                             |
+
+In most cases, Camunda defines throughput per day, as this time frame is easier to understand. However, in high-performance use cases, you might need to define the throughput per second.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.sizing-your-environment.sizing-requirements-and-influencing-factors.md

@@ -0,0 +1,6 @@
+# Size your environment — Sizing requirements and influencing factors
+
+Consider the following aspects when planning and sizing Camunda SaaS or Self-Managed.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment

package/.llms/chunks/components.best-practices.architecture.understanding-human-tasks-management.deciding-about-your-task-list-frontend-considerations-for-developing-custom-task-lists.md

@@ -0,0 +1,12 @@
+# Understanding human task management — Deciding about your task list frontend — Considerations for developing custom task lists
+
+When building a custom tasklist/application, you must plan for the following aspects. You will need to
+
+- _Query_ for user tasks and _generate lists_ of those tasks.
+- _Filter the list_ along specific attributes like current assignee, candidate groups, etc.
+- _Select_ and _display_ the right forms for starting processes and completing tasks.
+- Use _custom/business value_ data in order to _filter_ with those values and _display_ them correlated with the task list and within forms.
+- _Authorize_ users to access those lists, filters, and forms.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/understanding-human-tasks-management