From b0adc211fd1a146b9a9f32de829ae821d6693149 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Fri, 26 Dec 2025 19:02:32 +0530 Subject: [PATCH 01/93] eventing_memory_quota_first_cut_for_my_reference --- .../install/pages/eventing-memory-quota.adoc | 157 ++++++++++++++++++ modules/install/pages/sizing-general.adoc | 9 +- 2 files changed, 164 insertions(+), 2 deletions(-) create mode 100644 modules/install/pages/eventing-memory-quota.adoc diff --git a/modules/install/pages/eventing-memory-quota.adoc b/modules/install/pages/eventing-memory-quota.adoc new file mode 100644 index 0000000000..2426b83ec8 --- /dev/null +++ b/modules/install/pages/eventing-memory-quota.adoc @@ -0,0 +1,157 @@ += Eventing Memory Quota + +:description: The Eventing Service memory quota does not enforce a hard memory limit on the Eventing subsystem, including producer and worker processes. + +This page explains how the memory quota actually works, how Eventing distributes it across workers, and its limitations in non-containerized environments. + +[abstract] +{description} + +== Overview + +The Couchbase Eventing Service memory quota does not enforce a hard memory limit on the entire Eventing subsystem, including producer and worker processes. +The service uses the quota for queue sizing and JavaScript (JS) runtime memory heap, not as an absolute memory cap. +In VM or bare-metal deployments, Eventing functions can exceed the configured quota at runtime. +Understanding this behavior helps you to appropriately size and monitor Eventing functions in production environments. + +== How Memory Quota Works +The Eventing Service memory quota controls specific aspects of memory management but does not act as an absolute ceiling on memory usage. +The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and garbage collection, but does not act as an absolute ceiling on memory usage. + +=== Minimum Size +The memory quota must be a minimum of 256 MB. +Couchbase does not support values lesser than 256 MB. + +=== Purpose of the Quota + +The memory quota serves 2 primary purposes: + +* `Producer-to-worker queue sizing`: controls the maximum size of each worker's input queue. +* `Garbage Collection (GC) triggering`: determines when Eventing invokes JavaScript environment (JSE) GC to reclaim memory. +The quota does not restrict the total memory consumed by JSE heaps or Eventing processes. + +== Per-Worker Distribution + +The Eventing Service divides the total memory quota uniformly across all workers in all deployed functions. + +=== Calculation +Eventing calculates the per-worker quota as follows: +`Per-Worker quota = Total memory quota ÷ Total number of workers` + +=== Example + +Consider the following configuration: + +* Total memory quota: 256 MB +* Total workers (across all deployed functions): 4 +* Per-worker budget: 64 MB (256 MB ÷ 4 workers) + +Each worker receives an equal share of the total quota, regardless of the actual memory usage of individual functions. + +=== Impact of Worker Count + +As you deploy more functions or add workers per function, the per-worker quota decreases proportionally. +A smaller per-worker quota can affect performance if individual functions require substantial memory for processing. + +== Queue Sizing and GC Behavior + +The per-worker quota directly influences 2 key aspects of Eventing runtime behavior. + +=== Producer-to-Worker Queue Sizing + +Each worker has a bounded input queue that receives changes to documents from the Database Change Protocol (DCP) stream. + +* The per-worker quota determines the maximum size of this queue. +* When the queue exceeds this size, Eventing throttles the DCP stream to prevent unbounded memory growth. +* Throttling temporarily pauses mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. + +=== Garbage Collection (GC) Triggering + +NOTE: When memory usage approaches the per-worker quota limit, the JavaScript runtime may trigger garbage collection to reclaim memory. +However, the garbage collector may delay the stop-the-world collection because it's optimized for throughput. +As a result, the runtime may not reclaim memory without delay, which can temporarily affect Eventing memory consumption. +The service invokes a stop-the-world JSE GC to reduce memory inside the JSE isolate running each function. + +* GC frees memory occupied by unreachable objects that are no longer in use. +* GC reclaims memory only from objects that are no longer in use. +Memory held by live objects in the JSE heap remains allocated, so total usage may exceed the per-worker quota. + +== Limitations and Considerations +The Eventing Service memory quota has important limitations that users must understand to prevent operational issues: + +* Not a hard limit: The quota does not cap total memory usage. +Live objects in JSE heaps may persist, so memory usage can exceed the quota. +* No OS-level enforcement outside cgroups: In VM or bare-metal deployments, the operating system does not enforce memory limits. +* Worker sizing impacts memory: Configuring an excessive number of workers or running memory-intensive functions can increase memory pressure and affect node stability. +* Quota applies per worker, not per function: Each worker receives an equal share of the total quota, regardless of individual function memory requirements. + +=== Not a Hard Limit + +The Eventing Service memory quota does not restrict total memory usage. + +JSE heaps may still contain live (non-garbage) objects that: +* GC cannot reclaim. +* The quota does not account. +* Continue to consume memory beyond the configured limit. + +As a result, setting a memory quota does not guarantee that Eventing functions remain within that limit. + +=== No OS-Level Enforcement Outside cgroups + +In non-containerized environments, the operating system does not enforce the memory quota. + +* Users must monitor Eventing memory usage using system tools. +* Configuring an excessive number of workers can lead to memory exhaustion. +* High-memory-consuming functions can affect overall system stability. +* Eventing does not automatically stop or throttle execution when total memory exceeds the quota. + +=== Memory Isolation + +The memory quota does not isolate memory usage between Eventing functions. + +* All workers draw from the same total memory quota. +* A memory-intensive function can reduce the memory available to other functions. +* Eventing does not support per-function memory limits or reservations. + +== Best Practices +Follow these recommendations to effectively manage Eventing memory usage effectively and avoid operational issues. + +=== Monitor Memory Usage + +* Use system-level monitoring tools to track actual memory consumption. +* Monitor memory usage for the Eventing process and individual workers. +* Configure alerts for memory thresholds well below system limits. + +=== Configure Worker Count Appropriately + +* Consider the per-worker quota when determining the number of workers. +* Avoid over-provisioning workers when Eventing functions require substantial memory. +* Balance the worker count against available system memory. + +=== Test in Representative Environments + +* Test Eventing functions under production-like load conditions. +* Measure actual memory consumption during peak processing. +* Validate that memory usage remains within acceptable limits. + +=== Use cgroups for Enforcement + +* Consider containerized deployments or cgroup-based memory limits in production environments. +* Container platforms such as Docker and Kubernetes provide hard memory limits. +* cgroups enforce OS-level memory restrictions. +* This approach adds a safety layer beyond the Eventing Service memory quota. + +=== Size the Memory Quota Appropriately + +* Set the Eventing memory quota based on expected worker count and function complexity. +* Allow headroom above the minimum 256 MB for production workloads. +* Account for peak processing scenarios, not just average load. + +=== Review Function Memory Efficiency + +* Optimize JavaScript code to minimize memory allocation. +* Avoid accumulating large data structures in function scope. +* Release object references when data is no longer needed. +* Profile functions to identify memory-intensive operations. + +// Learn how to provide links to other doc pages and provide references to pages like Eventing Service Overview, Eventing Service Settings, and Eventing Function Examples. \ No newline at end of file diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 1358382b0d..9fd4a521cf 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -420,9 +420,14 @@ Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/ === RAM -In general, the Eventing memory quota of 256 MB is sufficient for almost all workloads. -When scaling up vertically by adding more workers (in the handler’s settings), you see a stall in processing when the number exceeds 48 workers. In this case, the memory quota can be increased to 384 MB or 512 MB. Do not add memory to the Eventing Service’s memory quota without a justified need as it can create resource issues. +The Eventing memory quota is discussed in detail in the xref:manage/manage-eventing/eventing-memory-quota.adoc[Eventing Memory Quota] doc. +Refer this document to learn: +* What is Eventing Service memory quota +* How the Eventing Service memory quota works +* The distribution of the total memory quota across workers +* The limitations and considerations +* Best practices and recommendations === Eventing Storage Collection (previously Metadata Bucket) From 42f98a48caf5e410c16f583f8f12938a0d57b7d3 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Fri, 26 Dec 2025 19:13:09 +0530 Subject: [PATCH 02/93] eventing_memory_quota_first_cut_for_my_reference --- modules/install/pages/sizing-general.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 9fd4a521cf..a080717010 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -420,14 +420,14 @@ Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/ === RAM - -The Eventing memory quota is discussed in detail in the xref:manage/manage-eventing/eventing-memory-quota.adoc[Eventing Memory Quota] doc. -Refer this document to learn: -* What is Eventing Service memory quota -* How the Eventing Service memory quota works -* The distribution of the total memory quota across workers -* The limitations and considerations -* Best practices and recommendations +The xref:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. + +Refer this document to learn about: +. Eventing Service memory quota +. How Eventing Service memory quota works +. The distribution of the total memory quota across workers +. The limitations and considerations +. Best practices and recommendations === Eventing Storage Collection (previously Metadata Bucket) From 06328cab1f8fe60b00f56bfeb7cea018e5688e6b Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 29 Dec 2025 15:01:28 +0530 Subject: [PATCH 03/93] eventing_memory_quota_first_cut_for_my_reference_1 --- .../install/pages/eventing-memory-quota.adoc | 21 ++++++++++++++----- modules/install/pages/sizing-general.adoc | 18 +++++++++------- 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/modules/install/pages/eventing-memory-quota.adoc b/modules/install/pages/eventing-memory-quota.adoc index 2426b83ec8..4c5b54840d 100644 --- a/modules/install/pages/eventing-memory-quota.adoc +++ b/modules/install/pages/eventing-memory-quota.adoc @@ -15,10 +15,14 @@ In VM or bare-metal deployments, Eventing functions can exceed the configured qu Understanding this behavior helps you to appropriately size and monitor Eventing functions in production environments. == How Memory Quota Works + The Eventing Service memory quota controls specific aspects of memory management but does not act as an absolute ceiling on memory usage. -The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and garbage collection, but does not act as an absolute ceiling on memory usage. + +The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and garbage collection. +However, it does not act as an absolute ceiling on memory usage. === Minimum Size + The memory quota must be a minimum of 256 MB. Couchbase does not support values lesser than 256 MB. @@ -26,8 +30,8 @@ Couchbase does not support values lesser than 256 MB. The memory quota serves 2 primary purposes: -* `Producer-to-worker queue sizing`: controls the maximum size of each worker's input queue. -* `Garbage Collection (GC) triggering`: determines when Eventing invokes JavaScript environment (JSE) GC to reclaim memory. +* **Producer-to-worker queue sizing**: controls the maximum size of each worker's input queue. +* **Garbage Collection (GC) triggering**: determines when Eventing invokes JavaScript environment (JSE) GC to reclaim memory. The quota does not restrict the total memory consumed by JSE heaps or Eventing processes. == Per-Worker Distribution @@ -36,7 +40,10 @@ The Eventing Service divides the total memory quota uniformly across all workers === Calculation Eventing calculates the per-worker quota as follows: -`Per-Worker quota = Total memory quota ÷ Total number of workers` ++ +.... +Per-Worker quota = Total memory quota ÷ Total number of workers +.... === Example @@ -154,4 +161,8 @@ Follow these recommendations to effectively manage Eventing memory usage effecti * Release object references when data is no longer needed. * Profile functions to identify memory-intensive operations. -// Learn how to provide links to other doc pages and provide references to pages like Eventing Service Overview, Eventing Service Settings, and Eventing Function Examples. \ No newline at end of file +// Learn how to provide links to other doc pages and provide references to pages like Eventing Service Overview, Eventing Service Settings, and Eventing Function Examples. +// == Related Links +// * xref:eventing-service-overview.adoc[Eventing Service Overview] +// * xref:eventing-service-settings.adoc[Eventing Service Settings] +// * \ No newline at end of file diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index a080717010..dc5a15d7f2 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -234,14 +234,16 @@ You should allocate additional CPU cores for these workloads. A node running the Index Service must be sized properly to create and maintain secondary indexes and to perform index scan for {sqlpp} queries. Similar to the nodes that run the Data Service, answer the following questions to take care of your application needs: - -. What is the length oƒ the document key? -. Which fields need to be indexed? -. Will you be using simple or compound indexes? -. What is the minimum, maximum, or average value size of the index field? -. How many indexes do you need? -. How many documents need to be indexed? -. What is the working set percentage of index required memory? ++ +-- +* What is the length oƒ the document key? +* Which fields need to be indexed? +* Will you be using simple or compound indexes? +* What is the minimum, maximum, or average value size of the index field? +* How many indexes do you need? +* How many documents need to be indexed? +* What is the working set percentage of index required memory? +-- Answers to these questions can help you better understand the capacity requirement of your cluster, and provide a better estimation for sizing. From 3b4cd9be3c1abc9fd882d01732abe91c256d65dd Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 29 Dec 2025 19:41:21 +0530 Subject: [PATCH 04/93] eventing_memory_quota_first_cut_for_my_reference_2_sizing_general --- modules/install/pages/sizing-general.adoc | 155 +++++++++++++--------- 1 file changed, 90 insertions(+), 65 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index dc5a15d7f2..82fc1121d0 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -4,7 +4,7 @@ [abstract] {description} -When you plan to deploy a Couchbase Server cluster, the most common and important question that comes up is: how many nodes do I need and what size do they need to be? +The most common and important question that comes up when you plan to deploy a Couchbase Server cluster is: how many nodes do I need and what size do they need to be? With the increasing number of Couchbase services and the flexibility of the Couchbase Data Platform, the answer to this question can be challenging. This guide aims to help you better size your deployment. @@ -23,27 +23,29 @@ There needs to be enough capacity in all areas to support everything the system === Multi-Dimensional Scaling -Couchbase Services are what allow you to access and maintain your data. -These services can be deployed, maintained, and provisioned independently of one another. -This independent service model allows you to take advantage of _Multi-Dimensional Scaling_, whereby a cluster can be fine-tuned for optimal handling of emergent workload-requirements, on a service-by-service basis. +Couchbase Services are what allow you to use and maintain your data. +Deploy, maintain, and provision these services independently of each other. +This independent service model allows you to take advantage of `Multi-Dimensional Scaling`, whereby a cluster can be fine-tuned for optimal handling of emergent workload-requirements, on a service-by-service basis. -Since each service has different demands on hardware resources, Multi-Dimensional Scaling plays an important role when sizing your Couchbase cluster, both pre and post-deployment. -For example, core Data Service operations can often benefit greatly from the _scale out_ of smaller commodity nodes, whereas low latency operations with the Query Service may see a greater benefit from the _scale up_ of hardware resources on a given node. +Every service has different demands on hardware resources. +Multi-Dimensional Scaling plays an important role when sizing your Couchbase cluster, both pre and post-deployment. +For example, core Data Service operations can often benefit greatly from the `scale out` of smaller commodity nodes, whereas low latency operations with the Query Service may see a greater benefit from the `scale up` of hardware resources on a given node. -For more information about the nature and resource demands of each Couchbase Service, refer to xref:learn:services-and-indexes/services/services.adoc[Services]. +For more information about the nature and resource demands of each Couchbase Service, see xref:learn:services-and-indexes/services/services.adoc[Services]. == About Couchbase Server Resources This guide discusses four types of resources that you should consider when sizing a Couchbase Server cluster node: CPU:: -CPU refers to the number of cores and clock speed that are required to run your workload. +CPU specifies the number of cores and clock speed required to run your workload. RAM:: -RAM is frequently one of the most crucial areas to size correctly. -Cached documents allow the reads to be served at low latency and consistently high throughput. +RAM is often the most crucial areas to size accurately. +Cached documents provide low-latency reads and consistently high throughput. + -This resource represents the main memory that you allocate to Couchbase Server and must be determined by the following factors: +This resource represents the main memory you allocate to Couchbase Server. +Determine the allocation based on the following factors: + -- * How much free RAM is available beyond OS and other applications @@ -75,7 +77,7 @@ Some components that require RAM are: | 256 MB minimum; 2048 MB and above recommended | Query Service -| No RAM-allocation is required for this service. +| This service does not require any RAM allocation. | Eventing Service | 256 MB @@ -88,8 +90,8 @@ Storage (disk space):: Requirements for your disk subsystem are: + -- -* [.term]_Disk size_ — Refers to the amount of the disk storage space that is needed to hold your entire data set. -* [.term]_Disk I/O_ — Is a combination of your sustained read/write rate, the need for compacting the database files, and anything else that requires disk access. +* [.term]`Disk size` — Specifies the disk storage space needed to hold your entire dataset. +* [.term]`Disk I/O` — Combines your sustained read/write rate, database file compaction, and any other operations that requires disk access. -- + To better support Couchbase Server, keep in mind the following: @@ -97,9 +99,9 @@ To better support Couchbase Server, keep in mind the following: -- * Disk space continues to grow if fragmentation ratio keeps climbing. To mitigate this, add enough buffer in your disk space to store all of the data. -Also, keep an eye on the fragmentation ratio in the Couchbase user interfaces and trigger compaction processes when needed. -* Solid State Drives (SSDs) are desired, but not required. -An SSD will give much better performance than a Hard Disk Drive (HDD) when it comes to disk throughput and latency. +Monitor the fragmentation ratio in the Couchbase user interfaces and trigger compaction processes when needed. +* Prefer Solid State Drives(SSD), but is not required. +An SSD gives much better performance than a Hard Disk Drive(HDD) when it comes to disk throughput and latency. -- Network:: @@ -110,19 +112,20 @@ Most deployments can achieve optimal performance with 1 Gbps interconnects, but == Sizing Data Service Nodes -Data Service nodes handle data service operations, such as create/read/update/delete (CRUD). -The sizing information provided below applies both to the _Couchstore_ and _Magma_ storage engines: however, the _differences_ between these storage engines should also be reviewed, before sizing is attempted. +Data Service nodes handle data service operations, such as create/read/update/delete(CRUD). +The sizing information provided below applies to both the `Couchstore` and `Magma` storage engines. +Review the differences between these storage engines before attempting sizing. For information, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines]. It's important to keep use-cases and application workloads in mind since different application workloads have different resource requirements. -For example, if your working set needs to be fully in memory, you might need large RAM size. -On the other hand, if your application requires only 10% of data in memory, you will need disks with enough space to store all of the data, and that are fast enough for your read/write operations. +For example, if your working set needs to be fully in-memory, you might need large RAM size. +On the other hand, if your application requires only 10% of data in-memory, you'll need disks with enough space to store all of the data, and that are fast enough for your read/write operations. You can start sizing the Data Service nodes by answering the following questions: -. Is the application primarily (or even exclusively) using individual document access? -. Do you plan to use XDCR? -. What’s your working set size and what are your data operation throughput and latency requirements? +* Is the application primarily using individual document access? +* Do you plan to use XDCR? +* What's your working set size and what are your data operation throughput and latency requirements? Answers to the above questions can help you better understand the capacity requirement of your cluster and provide a better estimation for sizing. @@ -214,7 +217,7 @@ Based on the above formula, these are the suggested sizing guidelines: | = (312,000,000 + 4,000,000,000) * (1+0.25)/(0.85) = 6,341,176,470 bytes |=== -This tells you that the RAM requirement for the whole cluster is 7 GB. +This tells you that the RAM requirement for the whole cluster is 7{nbsp}GB. NOTE: This amount is in addition to the RAM requirements for the operating system and any other software that runs on the cluster nodes. @@ -227,11 +230,11 @@ When sizing, you must account for raw CPU overhead when using a high number of b This overhead does not account for any front-end workloads. You should allocate additional CPU cores for these workloads. -* xref:manage:monitor/monitor-intro.adoc[Monitoring] is recommended for CPU usage and System Limits. +* Refer xref:manage:monitor/monitor-intro.adoc[Monitoring] to monitor CPU usage and System Limits. == Sizing Index Service Nodes -A node running the Index Service must be sized properly to create and maintain secondary indexes and to perform index scan for {sqlpp} queries. +Size a node running the Index Service properly to create and maintain secondary indexes and perform index scans for {sqlpp} queries. Similar to the nodes that run the Data Service, answer the following questions to take care of your application needs: + @@ -249,7 +252,7 @@ Answers to these questions can help you better understand the capacity requireme *The following is an example use-case for sizing RAM for the Index service:* -The following sizing guide can be used to compute the memory requirement for each individual index and can be used to determine the total RAM quota required for the Index service. +Use the following sizing guide to compute the memory requirement for each individual index and to determine the total RAM quota required for the Index service. .Input Variables for Sizing RAM |=== @@ -334,7 +337,8 @@ Based on the above formula, these are the suggested sizing guidelines: | (3200000000) * (1 + 0.25) * 0.2 = 800000000 bytes |=== -The above example shows the memory requirement of a secondary index with 10M index entries, each with 50 bytes size of secondary key and 30 bytes size of documentID. The memory usage requirements are 2.5GB(Nitro, 100% resident), 1GB(plasma, 20% resident), 800MB(Forestdb, 20% resident). +The above example shows the memory requirement of a secondary index with 10M index entries, each with 50 bytes size of secondary key and 30 bytes size of documentID. +The memory usage requirements are 2.5{nbsp}GB(Nitro, 100% resident), 1{nbsp}GB(plasma, 20% resident), 800{nbsp}MB(ForestDB, 20% resident). NOTE: The storage engine used in the sizing calculation corresponds to the storage mode chosen for Index Service as explained in the table below. @@ -356,22 +360,22 @@ NOTE: The storage engine used in the sizing calculation corresponds to the stora A node that runs the Query Service executes queries for your application needs. -Since the Query Service doesn’t need to persist data to disk, there are very minimal resource requirements for disk space and disk I/O. +Since the Query Service doesn’t need to persist data to disk, there are minimal resource requirements for disk space and disk I/O. You only need to consider CPU and memory. -There are a few questions that will help size the cluster: +Questions that help in sizing the cluster: -. What types of queries do you need to run? -. Do you need to run `stale=ok` or `stale=false` queries? -. Are the queries simple or complex (requiring JOINs, for example)? -. What are the throughput and latency requirements for your queries? +* What types of queries do you need to run? +* Do you need to run `stale=ok` or `stale=false` queries? +* Are the queries simple or complex (requiring JOINs, for example)? +* What are the throughput and latency requirements for your queries? Different queries have different resource requirements. A simple query might return results within milliseconds while a complex query may require several seconds. -The number of queries that may be processed simultaneously may be approximated with the formula _CPU_cores * 4_. -The maximum queue-length for queries may be approximated with the formula _CPU_cores * 256_. -If either limit is reached, additional queries are rejected with a `503` error. +The formula used to calculate the number of queries that's processed simultaneously is `CPU_cores * 4`. +The formula used to calculate the maximum queue-length for queries is`CPU_cores * 256`. +The system rejects additional queries with a 503 error once it reaches the limits. == Sizing Analytics Service Nodes @@ -381,67 +385,86 @@ The Analytics Service is dependent on the Data Service and requires the Data ser === Data space -* Ensure that the data space for Analytics node takes into account metadata replicas. The Analytics Service currently only replicates metadata and not the actual data. There is a small overhead for metadata replicas as metadata is usually small. +* Make sure that the data space for Analytics node takes into account metadata replicas. +The Analytics Service only replicates the metadata and not the actual data. +There's a small overhead for metadata replicas as metadata is generally small. -* When evaluating a query, the Analytics engine uses temporary disk space. The type of query being executed can impact the amount of temporary disk space required. For example, a query with heavy JOINs, aggregates, windowing, or more predicates will require more temporary disk space. Typically, the temporary disk space can be 2x the data space. +* When evaluating a query, the Analytics engine uses temporary disk space. +The query type the required amount of temporary disk space. +For example, queries with heavy JOINs, aggregates, windowing, or additional predicates require more temporary disk space. +Typically, the temporary disk space can be 2x the data space. * The percent of data shadowed, which is dependent on your use case. -* When ingesting data from the the Data Service into the Analytics Service a filter can be provided that reduces the size of the data that is ingested and also the storage size for the Analytics Service proportionally. +* When you load data from the Data Service into the Analytics Service, you can apply a filter to reduce both the loaded data size and the Analytics Service storage requirements proportionally. === Disk types and partioning -During query execution, Analytics’s query engine attempts to concurrently read and process data from all data partitions. Because of that, the Input/Output Operations per Second (IOPS) of the actual physical disk in which each data partition resides plays a major role in determining the query execution time. -Modern storage devices such as SSDs have much higher IOPS and can deal better with concurrent reads than HDDs. Therefore, having a single data partition on devices with high IOPS will not fully utilize their capabilities. +During query execution, the Analytics query engine concurrently reads and processes data from all partitions. +The Input/Output Operations per Second(IOPS) of the physical disk that hosts the data partitions plays a major role in determining the query execution time. +Modern storage devices such as SSDs have much higher IOPS and can deal better with concurrent reads than HDDs. +Therefore, a single data partition under-utilizes high-IOPS devices. -To simplify the setup of the typical case of a node having a single modern storage device, the Analytics service automatically creates multiple data partitions within the same storage device if and only if a single “Analytics Disk Path” is specified during the node initialization. The number of automatically created data partitions is based on this formula: +To simplify setup for nodes with a single modern storage device, the Analytics Service creates multiple data partitions on the same storage device. +It does this only when you specify a single Analytics disk path during node initialization. +The service determines the number of partitions using the following formula: * `Maximum partitions to create = Min((Analytics Memory in MB / 1024), 16)` * `Actual created partitions = Min(node virtual cores, Maximum partitions to create)` -For example, if a node has 8 virtual cores and the Analytics service was configured with memory >= 8GB, 8 data partitions will be created on that node. -Similarly, if a node has 32 virtual cores and was configured with memory >= 16GB, only 16 partitions will be created as 16 is the upper bound for automatic partitioning. +For example, if a node has 8 virtual cores and the Analytics Service has at least 8{nbsp}GB of memory, the system creates 8 data partitions on that node. +Similarly, for a node with 32 virtual cores and 16{nbsp}GB memory, the system creates 16 partitions, the maximum for automatic partitioning. === Index considerations -The size of a secondary index is approximately the total size of indexed fields in the Analytics collection. For example, if a collection has 20 fields and only 1 of those fields appears in the secondary index, the secondary index size will be ~1/20 of the collection size. +The size of a secondary index is around the total size of indexed fields in the Analytics collection. +For example, if a collection has 20 fields and only 1 of those fields appears in the secondary index, the secondary index size is ~1/20 of the collection size. == Sizing Eventing Service Nodes -Eventing is a compute oriented service. By default, Eventing service has one worker and each worker has two threads of execution. You can scale eventing both vertically by adding more workers or horizontally by adding more nodes. The Eventing service will partition vBuckets across the number of available nodes. +Eventing is a compute oriented service. +By default, Eventing service has 1 worker and each worker has 2 threads of execution. +You can scale eventing both vertically by adding more workers or horizontally by adding more nodes. +The Eventing service partitions the vBuckets across the number of available nodes. === CPU -Because Eventing allows arbitrary code, JavaScript, to be written and run, it is difficult to come up with a perfect sizing formula unless all Functions have been designed and their KV ops, Query ops, and cURLops are known along with the expected mutation rate. +Eventing runs arbitrary JavaScript code. +This flexibility makes it difficult to define a precise sizing formula. +You cannot define a precise formula unless you know the function designs, their KV operations, query operations, cURL operations, and the expected mutation rate. For example, if you process 100K mutations per second and only match 1 out of 1000 patterns, then perform some intense computation on the matched 100 items in your Eventing Function, you need 100X less compute than if you performed the intense computation on each mutation. -Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/S cURL call. In this case, Eventing typically blocks on I/O and doesn’t need much CPU. However. if you want high throughput to overcome bandwidth, you will need more workers and thus more cores. +Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/S cURL call. +Eventing typically blocks on I/O and requires little CPU. +Achieving high throughput to overcome bandwidth requires additional workers and cores. -8 vCPUs or 4 physical cores should be considered a good start for running a few Eventing Functions. +Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM The xref:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. - -Refer this document to learn about: -. Eventing Service memory quota -. How Eventing Service memory quota works -. The distribution of the total memory quota across workers -. The limitations and considerations -. Best practices and recommendations +Refer this document to learn more about: +* Eventing Service memory quota +* How Eventing Service memory quota works +* The distribution of the total memory quota across workers +* The limitations and considerations +* Best practices and recommendations === Eventing Storage Collection (previously Metadata Bucket) -Eventing functions store less than 2048 docs per Function. If timers are not used or if you have less than a few thousand active timers, then the size of the Eventing storage collection can simply be in a bucket with a minimum size 100 MB. +Each Eventing function stores fewer than 2048 documents in its Eventing storage collection. +If timers are not used or if the active timers count does not exceed the per-function document limit, store the Eventing storage collection in a 100 MB bucket. -However, if you use timers you will have to allocate an additional space of about 800 bytes + the size of the passed context (which is the state passed to the function when it is called in the future) per active timer. +Using timers requires additional storage for each active timer. +Each active timer requires 800 bytes, plus the size of the passed context, which represents the state supplied to the function at future execution. -If you have a context of 200 bytes (total 1K/timer), then for 100,000 active timers you'll need 100 MB of additional space in this bucket. +A 200-byte context results in 1 KB of storage per active timer. +100,000 active timers require 100 MB of additional bucket space. -As a best practice, it's recommended to keep this collection 100% resident, so that it's always available in-memory. +As a best practice, keep this collection fully resident in-memory to make sure constant availability. -NOTE: This collection is shared across all your Eventing Functions. +NOTE: All Eventing functions use this collection. == Sizing Backup Service Nodes @@ -470,6 +493,8 @@ Before setting up a replication, you must make sure your cluster is appropriatel Your cluster must be properly sized to be able to handle new XDCR streams. -For example, XDCR needs 1-2 additional CPU cores per stream. In some cases, it also requires additional RAM and network resources. If a cluster is not sized to handle _both_ the existing workload _and_ the new XDCR streams, the performance of both XDCR and the cluster overall may be negatively impacted. +For example, XDCR needs 1-2 additional CPU cores per stream. +In some cases, it also requires additional RAM and network resources. +If a cluster is not sized to handle `both` the existing workload `and` the new XDCR streams, the performance of both XDCR and the cluster overall may be negatively impacted. -For information on preparing your cluster for replication, see xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR]. +For information about preparing your cluster for replication, see xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR]. From eebb46f5e761e8cb5efbe60abd7ab431615e2dec Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 29 Dec 2025 20:38:30 +0530 Subject: [PATCH 05/93] eventing_memory_quota_first_cut_for_my_reference_3_sizing_general --- modules/install/pages/sizing-general.adoc | 25 ++++++++++++++--------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 82fc1121d0..3a85a16f9f 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -48,11 +48,12 @@ This resource represents the main memory you allocate to Couchbase Server. Determine the allocation based on the following factors: + -- -* How much free RAM is available beyond OS and other applications -* How much data do you want to store in main memory -* How much latency you expect from KV/indexing/query performance +* How much free RAM is available beyond OS and other applications? +* How much data do you want to store in main memory? +* How much latency you expect from KV/indexing/query performance? -- + + Some components that require RAM are: + -- @@ -237,7 +238,7 @@ You should allocate additional CPU cores for these workloads. Size a node running the Index Service properly to create and maintain secondary indexes and perform index scans for {sqlpp} queries. Similar to the nodes that run the Data Service, answer the following questions to take care of your application needs: -+ + -- * What is the length oƒ the document key? * Which fields need to be indexed? @@ -360,7 +361,7 @@ NOTE: The storage engine used in the sizing calculation corresponds to the stora A node that runs the Query Service executes queries for your application needs. -Since the Query Service doesn’t need to persist data to disk, there are minimal resource requirements for disk space and disk I/O. +Since the Query Service doesn't need to persist data to disk, there are minimal resource requirements for disk space and disk I/O. You only need to consider CPU and memory. Questions that help in sizing the cluster: @@ -374,7 +375,7 @@ Different queries have different resource requirements. A simple query might return results within milliseconds while a complex query may require several seconds. The formula used to calculate the number of queries that's processed simultaneously is `CPU_cores * 4`. -The formula used to calculate the maximum queue-length for queries is`CPU_cores * 256`. +The formula used to calculate the maximum queue-length for queries is `CPU_cores * 256`. The system rejects additional queries with a 503 error once it reaches the limits. == Sizing Analytics Service Nodes @@ -443,13 +444,19 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -The xref:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. -Refer this document to learn more about: +The xref:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. + +Refer to this document to learn more about: + ++ +-- * Eventing Service memory quota * How Eventing Service memory quota works * The distribution of the total memory quota across workers * The limitations and considerations * Best practices and recommendations +-- ++ === Eventing Storage Collection (previously Metadata Bucket) @@ -470,7 +477,6 @@ NOTE: All Eventing functions use this collection. The hardware requirements for running a backup cluster are as follows: - .Hardware requirements |=== ||Minimum |Recommended @@ -486,7 +492,6 @@ The hardware requirements for running a backup cluster are as follows: |=== - == Sizing for Replication (XDCR) Before setting up a replication, you must make sure your cluster is appropriately configured and provisioned. From 882f1d17e0e258e9d6b5ac19c6e365e3e1e26ab5 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 29 Dec 2025 21:08:49 +0530 Subject: [PATCH 06/93] eventing_memory_quota_adding_&_Modifying_sizing_guidelines --- modules/install/pages/eventing-memory-quota.adoc | 12 ++++++------ modules/install/pages/sizing-general.adoc | 4 +--- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/modules/install/pages/eventing-memory-quota.adoc b/modules/install/pages/eventing-memory-quota.adoc index 4c5b54840d..7451f4fdeb 100644 --- a/modules/install/pages/eventing-memory-quota.adoc +++ b/modules/install/pages/eventing-memory-quota.adoc @@ -40,7 +40,6 @@ The Eventing Service divides the total memory quota uniformly across all workers === Calculation Eventing calculates the per-worker quota as follows: -+ .... Per-Worker quota = Total memory quota ÷ Total number of workers .... @@ -74,15 +73,15 @@ Each worker has a bounded input queue that receives changes to documents from th === Garbage Collection (GC) Triggering +* GC frees memory occupied by unreachable objects that are no longer in use. +* GC reclaims memory only from objects that are no longer in use. +Memory held by live objects in the JSE heap remains allocated, so total usage may exceed the per-worker quota. + NOTE: When memory usage approaches the per-worker quota limit, the JavaScript runtime may trigger garbage collection to reclaim memory. However, the garbage collector may delay the stop-the-world collection because it's optimized for throughput. As a result, the runtime may not reclaim memory without delay, which can temporarily affect Eventing memory consumption. The service invokes a stop-the-world JSE GC to reduce memory inside the JSE isolate running each function. -* GC frees memory occupied by unreachable objects that are no longer in use. -* GC reclaims memory only from objects that are no longer in use. -Memory held by live objects in the JSE heap remains allocated, so total usage may exceed the per-worker quota. - == Limitations and Considerations The Eventing Service memory quota has important limitations that users must understand to prevent operational issues: @@ -97,6 +96,7 @@ Live objects in JSE heaps may persist, so memory usage can exceed the quota. The Eventing Service memory quota does not restrict total memory usage. JSE heaps may still contain live (non-garbage) objects that: + * GC cannot reclaim. * The quota does not account. * Continue to consume memory beyond the configured limit. @@ -151,7 +151,7 @@ Follow these recommendations to effectively manage Eventing memory usage effecti === Size the Memory Quota Appropriately * Set the Eventing memory quota based on expected worker count and function complexity. -* Allow headroom above the minimum 256 MB for production workloads. +* Allow additional headroom on top of the 256 MB default for production workloads. * Account for peak processing scenarios, not just average load. === Review Function Memory Efficiency diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 3a85a16f9f..c44753926d 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -58,7 +58,7 @@ Some components that require RAM are: + -- ** All index storage types which need sufficient memory quota allocation for proper functioning. -** Full Text Search (FTS) +** Full Text Search (FTS). -- + .Minimum RAM Quota for Couchbase Server Components @@ -448,7 +448,6 @@ The xref:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eve Refer to this document to learn more about: -+ -- * Eventing Service memory quota * How Eventing Service memory quota works @@ -456,7 +455,6 @@ Refer to this document to learn more about: * The limitations and considerations * Best practices and recommendations -- -+ === Eventing Storage Collection (previously Metadata Bucket) From 263d9c85a42ed35681582bf28cf8e02ffb9d97a8 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 30 Dec 2025 16:16:58 +0530 Subject: [PATCH 07/93] DOC-13422_incorporating_technical_comments --- .../install/pages/eventing-memory-quota.adoc | 30 +++++++++---------- .../database-change-protocol.adoc | 0 2 files changed, 14 insertions(+), 16 deletions(-) create mode 100644 modules/install/pages/modules/architecture/database-change-protocol.adoc diff --git a/modules/install/pages/eventing-memory-quota.adoc b/modules/install/pages/eventing-memory-quota.adoc index 7451f4fdeb..606afeb0d8 100644 --- a/modules/install/pages/eventing-memory-quota.adoc +++ b/modules/install/pages/eventing-memory-quota.adoc @@ -1,6 +1,6 @@ = Eventing Memory Quota -:description: The Eventing Service memory quota does not enforce a hard memory limit on the Eventing subsystem, including producer and worker processes. +:description: The Eventing Service memory quota does not enforce a hard memory limit on the Eventing subsystem, including worker processes. This page explains how the memory quota actually works, how Eventing distributes it across workers, and its limitations in non-containerized environments. @@ -9,16 +9,14 @@ This page explains how the memory quota actually works, how Eventing distributes == Overview -The Couchbase Eventing Service memory quota does not enforce a hard memory limit on the entire Eventing subsystem, including producer and worker processes. +The Couchbase Eventing Service memory quota does not enforce a hard memory limit on the entire Eventing subsystem, including worker processes. The service uses the quota for queue sizing and JavaScript (JS) runtime memory heap, not as an absolute memory cap. In VM or bare-metal deployments, Eventing functions can exceed the configured quota at runtime. Understanding this behavior helps you to appropriately size and monitor Eventing functions in production environments. == How Memory Quota Works -The Eventing Service memory quota controls specific aspects of memory management but does not act as an absolute ceiling on memory usage. - -The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and garbage collection. +The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and frequency of garbage collection. However, it does not act as an absolute ceiling on memory usage. === Minimum Size @@ -30,9 +28,9 @@ Couchbase does not support values lesser than 256 MB. The memory quota serves 2 primary purposes: -* **Producer-to-worker queue sizing**: controls the maximum size of each worker's input queue. -* **Garbage Collection (GC) triggering**: determines when Eventing invokes JavaScript environment (JSE) GC to reclaim memory. -The quota does not restrict the total memory consumed by JSE heaps or Eventing processes. +* **Worker queue sizing**: controls the maximum size of each worker's input queue. +* **Garbage Collection (GC) triggering**: determines when Eventing invokes JavaScript environment GC to reclaim memory. +The quota does not restrict the total memory consumed by JavaScript runtime heaps or Eventing processes. == Per-Worker Distribution @@ -63,30 +61,30 @@ A smaller per-worker quota can affect performance if individual functions requir The per-worker quota directly influences 2 key aspects of Eventing runtime behavior. -=== Producer-to-Worker Queue Sizing +=== Worker Queue Sizing -Each worker has a bounded input queue that receives changes to documents from the Database Change Protocol (DCP) stream. +Each worker maintains a bounded input queue that receives changes to documents from the Database Change Protocol (xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[DCP]) stream. * The per-worker quota determines the maximum size of this queue. -* When the queue exceeds this size, Eventing throttles the DCP stream to prevent unbounded memory growth. -* Throttling temporarily pauses mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. +* When the queue exceeds this size, Eventing throttles the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[DCP] stream to prevent unbounded memory growth. +* Throttling temporarily pauses mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. === Garbage Collection (GC) Triggering * GC frees memory occupied by unreachable objects that are no longer in use. * GC reclaims memory only from objects that are no longer in use. -Memory held by live objects in the JSE heap remains allocated, so total usage may exceed the per-worker quota. +Memory held by live objects in the JavaScript runtime heap remains allocated, so total usage may exceed the per-worker quota. NOTE: When memory usage approaches the per-worker quota limit, the JavaScript runtime may trigger garbage collection to reclaim memory. However, the garbage collector may delay the stop-the-world collection because it's optimized for throughput. As a result, the runtime may not reclaim memory without delay, which can temporarily affect Eventing memory consumption. -The service invokes a stop-the-world JSE GC to reduce memory inside the JSE isolate running each function. +The service invokes a stop-the-world JavaScript runtime GC to reduce memory inside the JavaScript runtime isolate running each function. == Limitations and Considerations The Eventing Service memory quota has important limitations that users must understand to prevent operational issues: * Not a hard limit: The quota does not cap total memory usage. -Live objects in JSE heaps may persist, so memory usage can exceed the quota. +Live objects in JavaScript runtime heaps may persist, so memory usage can exceed the quota. * No OS-level enforcement outside cgroups: In VM or bare-metal deployments, the operating system does not enforce memory limits. * Worker sizing impacts memory: Configuring an excessive number of workers or running memory-intensive functions can increase memory pressure and affect node stability. * Quota applies per worker, not per function: Each worker receives an equal share of the total quota, regardless of individual function memory requirements. @@ -95,7 +93,7 @@ Live objects in JSE heaps may persist, so memory usage can exceed the quota. The Eventing Service memory quota does not restrict total memory usage. -JSE heaps may still contain live (non-garbage) objects that: +JavaScript runtime heaps may still contain live (non-garbage) objects that: * GC cannot reclaim. * The quota does not account. diff --git a/modules/install/pages/modules/architecture/database-change-protocol.adoc b/modules/install/pages/modules/architecture/database-change-protocol.adoc new file mode 100644 index 0000000000..e69de29bb2 From 2560f04b4f29eca42959bf2b15b75684d53c25ae Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Wed, 7 Jan 2026 14:21:45 +0530 Subject: [PATCH 08/93] removing a page that was added by mistake --- .../pages/modules/architecture/database-change-protocol.adoc | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 modules/install/pages/modules/architecture/database-change-protocol.adoc diff --git a/modules/install/pages/modules/architecture/database-change-protocol.adoc b/modules/install/pages/modules/architecture/database-change-protocol.adoc deleted file mode 100644 index e69de29bb2..0000000000 From 76c32d738d50d40b9b9d828244dad07538fadb5b Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Wed, 7 Jan 2026 16:48:42 +0530 Subject: [PATCH 09/93] moved the eventing memory quota file to the required section and corrected the xref --- modules/install/pages/sizing-general.adoc | 2 +- .../buckets-memory-and-storage}/eventing-memory-quota.adoc | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename modules/{install/pages => learn/pages/buckets-memory-and-storage}/eventing-memory-quota.adoc (100%) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index c44753926d..e382bf7a96 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -444,7 +444,7 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -The xref:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. +The xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. Refer to this document to learn more about: diff --git a/modules/install/pages/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc similarity index 100% rename from modules/install/pages/eventing-memory-quota.adoc rename to modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc From 9995e173d3e44c1258ae23d0e25c175d36109a16 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Wed, 7 Jan 2026 16:54:28 +0530 Subject: [PATCH 10/93] added the eventing memory quota file to the nav.adoc file --- modules/ROOT/nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9e1a0063cb..a48b3b60ae 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -51,6 +51,7 @@ include::third-party:partial$nav.adoc[] *** xref:learn:buckets-memory-and-storage/compression.adoc[Compression] ** xref:learn:buckets-memory-and-storage/memory-and-storage.adoc[Memory and Storage] *** xref:learn:buckets-memory-and-storage/memory.adoc[Memory] + *** xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[Eventing Memory Quota] *** xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines] *** xref:learn:buckets-memory-and-storage/storage-settings.adoc[Storage Properties] * xref:learn:services-and-indexes/services/services.adoc[Services] From 05ac722f46c38fc7a9996d81f8e016e24d243097 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 16:44:08 +0530 Subject: [PATCH 11/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 733c50902a..c77d103247 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -5,7 +5,7 @@ [abstract] {description} -The most common and important question that comes up when you plan to deploy a Couchbase Server cluster is: how many nodes do I need and what size do they need to be? +The most common and important questions you need to ask when deploying a new Couchbase Server cluster are how many nodes you need, and what size they need to be. With the increasing number of Couchbase services and the flexibility of the Couchbase Data Platform, the answer to this question can be challenging. This guide aims to help you better size your deployment. From 01cc9b29597736915a073de66d97a8b852fa912d Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 17:41:54 +0530 Subject: [PATCH 12/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index c77d103247..05398a9ea4 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -42,7 +42,7 @@ CPU:: CPU specifies the number of cores and clock speed required to run your workload. RAM:: -RAM is often the most crucial areas to size accurately. +RAM is often the most crucial area to size. Cached documents provide low-latency reads and consistently high throughput. + This resource represents the main memory you allocate to Couchbase Server. From 16ce176c41d7abf7f8a02a5ce52b8556a307d437 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 17:44:47 +0530 Subject: [PATCH 13/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 05398a9ea4..c67280710f 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -45,8 +45,8 @@ RAM:: RAM is often the most crucial area to size. Cached documents provide low-latency reads and consistently high throughput. + -This resource represents the main memory you allocate to Couchbase Server. -Determine the allocation based on the following factors: +Your RAM represents the main memory you allocate to Couchbase Server. +Determine your allocation based on the following factors: + -- * How much free RAM is available beyond OS and other applications? From a4f9f9c6a7859bcf485dd6a66ee35e10ab56f16a Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 17:47:02 +0530 Subject: [PATCH 14/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index c67280710f..6e0995acd0 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -49,9 +49,9 @@ Your RAM represents the main memory you allocate to Couchbase Server. Determine your allocation based on the following factors: + -- -* How much free RAM is available beyond OS and other applications? -* How much data do you want to store in main memory? -* How much latency you expect from KV/indexing/query performance? +* How much free RAM is available beyond your OS and other applications. +* How much data you want to store in main memory. +* How much latency you expect from your Data, Indexing, and Query Service performance. -- + From f383458e15d6fa1c30f9ec6246a73a3bc384c384 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 17:48:22 +0530 Subject: [PATCH 15/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 6e0995acd0..c7c2041cdb 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -59,7 +59,7 @@ Some components that require RAM are: + -- ** All index storage types which need sufficient memory quota allocation for proper functioning. -** Full Text Search (FTS). +** The Search Service. -- + .Minimum RAM Quota for Couchbase Server Components From 1fafddb6ae0ca282d1d231124cf48a66ce0825ba Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 19:24:08 +0530 Subject: [PATCH 16/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index c7c2041cdb..01df0cf7ab 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -92,8 +92,8 @@ Storage (disk space):: Requirements for your disk subsystem are: + -- -* [.term]`Disk size` — Specifies the disk storage space needed to hold your entire dataset. -* [.term]`Disk I/O` — Combines your sustained read/write rate, database file compaction, and any other operations that requires disk access. +* *Disk size* — Specifies the disk storage space needed to hold your entire dataset. +* *Disk I/O* — Combines your sustained read/write rate, database file compaction, and any other operations that requires disk access. -- + To better support Couchbase Server, keep in mind the following: From ae65e37078ea254bd39a66626a2fe10b61b77d7a Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 19:27:01 +0530 Subject: [PATCH 17/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 01df0cf7ab..beeb4c5639 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -101,9 +101,9 @@ To better support Couchbase Server, keep in mind the following: -- * Disk space continues to grow if fragmentation ratio keeps climbing. To mitigate this, add enough buffer in your disk space to store all of the data. -Monitor the fragmentation ratio in the Couchbase user interfaces and trigger compaction processes when needed. -* Prefer Solid State Drives(SSD), but is not required. -An SSD gives much better performance than a Hard Disk Drive(HDD) when it comes to disk throughput and latency. +Monitor your cluster's fragmentation ratio in the Couchbase Server Web Console and trigger compaction processes as needed. +* Couchbase recommends using Solid State Drives (SSD) when possible. +An SSD gives much better performance than a Hard Disk Drive (HDD) when it comes to disk throughput and latency. -- Network:: From 63f64ef636d9942c6504421699cf405295caed23 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 19:34:19 +0530 Subject: [PATCH 18/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index beeb4c5639..1ff03cf42d 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -114,10 +114,11 @@ Most deployments can achieve optimal performance with 1 Gbps interconnects, but == Sizing Data Service Nodes -Data Service nodes handle data service operations, such as create/read/update/delete(CRUD). -The sizing information provided below applies to both the `Couchstore` and `Magma` storage engines. -Review the differences between these storage engines before attempting sizing. -For information, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines]. +Data Service nodes handle data service operations, such as create/read/update/delete (CRUD). +The following sizing information applies to both the Couchstore and Magma storage engines. + +Couchbase recommends reviewing the differences between the available storage engines before attempting to size the Data Service nodes in your cluster. +For information, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[]. It's important to keep use-cases and application workloads in mind since different application workloads have different resource requirements. For example, if your working set needs to be fully in-memory, you might need large RAM size. From 189b055aab5f8130d4018ed75b67e96624e17fc7 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 19:42:15 +0530 Subject: [PATCH 19/93] adding the deleted heading RAM Sizing for Data Services Nodes --- modules/install/pages/sizing-general.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 01df0cf7ab..5059652798 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -123,6 +123,8 @@ It's important to keep use-cases and application workloads in mind since differe For example, if your working set needs to be fully in-memory, you might need large RAM size. On the other hand, if your application requires only 10% of data in-memory, you'll need disks with enough space to store all of the data, and that are fast enough for your read/write operations. +=== RAM Sizing for Data Service Nodes + You can start sizing the Data Service nodes by answering the following questions: * Is the application primarily using individual document access? From 26f12411fdb1710834ba7c234643ab2bb3388d86 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:01:53 +0530 Subject: [PATCH 20/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 9f84acf94b..d2fa43fcbe 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -121,8 +121,8 @@ Couchbase recommends reviewing the differences between the available storage eng For information, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[]. It's important to keep use-cases and application workloads in mind since different application workloads have different resource requirements. -For example, if your working set needs to be fully in-memory, you might need large RAM size. -On the other hand, if your application requires only 10% of data in-memory, you'll need disks with enough space to store all of the data, and that are fast enough for your read/write operations. +For example, if your working set needs to be fully in-memory, your cluster might need more RAM. +If your application requires only 10% of data in-memory, you need disks with enough space to store all of the data, and that are fast enough for your read/write operations. === RAM Sizing for Data Service Nodes From 4237e490c4e41c1136a66b0de68333509687949a Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:11:55 +0530 Subject: [PATCH 21/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index d2fa43fcbe..440681dd84 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -405,7 +405,7 @@ When sizing, you must account for raw CPU overhead when using a high number of b This overhead does not account for any front-end workloads. You should allocate additional CPU cores for these workloads. -* Refer xref:manage:monitor/monitor-intro.adoc[Monitoring] to monitor CPU usage and System Limits. +* For more information about monitoring CPU usage and System Limits, see xref:manage:monitor/monitor-intro.adoc[]. == Sizing Index Service Nodes From f959c2dc429528b6e65408d55bb3636c143730f4 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:15:09 +0530 Subject: [PATCH 22/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 440681dd84..13a66c04c2 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -409,7 +409,7 @@ You should allocate additional CPU cores for these workloads. == Sizing Index Service Nodes -Size a node running the Index Service properly to create and maintain secondary indexes and perform index scans for {sqlpp} queries. +To create and maintain secondary indexes and perform index scans for {sqlpp} queries, you need to size your Index Service nodes. Similar to the nodes that run the Data Service, answer the following questions to take care of your application needs: From 3b53051e1639bb3ada92899bd64c551f1629fc0e Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:22:40 +0530 Subject: [PATCH 23/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 13a66c04c2..64fbe54e0a 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -414,10 +414,10 @@ To create and maintain secondary indexes and perform index scans for {sqlpp} que Similar to the nodes that run the Data Service, answer the following questions to take care of your application needs: -- -* What is the length oƒ the document key? +* What is the length of your document keys? * Which fields need to be indexed? * Will you be using simple or compound indexes? -* What is the minimum, maximum, or average value size of the index field? +* What is the minimum, maximum, or average value size of the indexed fields? * How many indexes do you need? * How many documents need to be indexed? * What is the working set percentage of index required memory? From 73215bb5e02ad022e9f866370582305da4ca4b4f Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:25:43 +0530 Subject: [PATCH 24/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 64fbe54e0a..b6820c5305 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -427,7 +427,7 @@ Answers to these questions can help you better understand the capacity requireme *The following is an example use-case for sizing RAM for the Index service:* -Use the following sizing guide to compute the memory requirement for each individual index and to determine the total RAM quota required for the Index service. +Use the following sizing guide to compute the memory requirement for each individual index and to determine the total RAM quota required for the Index Service. .Input Variables for Sizing RAM |=== From cd0a7555ad2402d9256b8835fceb0c76fb5635f9 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:27:31 +0530 Subject: [PATCH 25/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index b6820c5305..3a877cc8ca 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -513,7 +513,7 @@ Based on the above formula, these are the suggested sizing guidelines: |=== The above example shows the memory requirement of a secondary index with 10M index entries, each with 50 bytes size of secondary key and 30 bytes size of documentID. -The memory usage requirements are 2.5{nbsp}GB(Nitro, 100% resident), 1{nbsp}GB(plasma, 20% resident), 800{nbsp}MB(ForestDB, 20% resident). +The memory usage requirements are 2.5{nbsp}GB (Nitro, 100% resident), 1{nbsp}GB (plasma, 20% resident), 800{nbsp}MB (ForestDB, 20% resident). NOTE: The storage engine used in the sizing calculation corresponds to the storage mode chosen for Index Service as explained in the table below. From 4ebcef0cf3d625100d487ef74a0d2b95d8b21c73 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:29:53 +0530 Subject: [PATCH 26/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 3a877cc8ca..b4420819d4 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -535,7 +535,7 @@ NOTE: The storage engine used in the sizing calculation corresponds to the stora A node that runs the Query Service executes queries for your application needs. -Since the Query Service doesn't need to persist data to disk, there are minimal resource requirements for disk space and disk I/O. +Since the Query Service does not need to persist data to disk, there are minimal resource requirements for disk space and disk I/O. You only need to consider CPU and memory. Questions that help in sizing the cluster: From 0a92077c2cc1b280d850fd43d65d33ef7732b9d8 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:35:30 +0530 Subject: [PATCH 27/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index b4420819d4..d43ffd57fd 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -538,7 +538,7 @@ A node that runs the Query Service executes queries for your application needs. Since the Query Service does not need to persist data to disk, there are minimal resource requirements for disk space and disk I/O. You only need to consider CPU and memory. -Questions that help in sizing the cluster: +Answer the following questions to help size the Query Service nodes on your cluster: * What types of queries do you need to run? * Do you need to run `stale=ok` or `stale=false` queries? From bcfadfc8cd0486f7565b977595e5475af3e2bb97 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:38:01 +0530 Subject: [PATCH 28/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index d43ffd57fd..289ced6345 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -542,7 +542,7 @@ Answer the following questions to help size the Query Service nodes on your clus * What types of queries do you need to run? * Do you need to run `stale=ok` or `stale=false` queries? -* Are the queries simple or complex (requiring JOINs, for example)? +* Are the queries simple or complex? For example, do you need to use JOINs? * What are the throughput and latency requirements for your queries? Different queries have different resource requirements. From 64cd66339c876514e8def9951701ddea2a178592 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:43:00 +0530 Subject: [PATCH 29/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 289ced6345..fb8a5f86ec 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -550,7 +550,7 @@ A simple query might return results within milliseconds while a complex query ma The formula used to calculate the number of queries that's processed simultaneously is `CPU_cores * 4`. The formula used to calculate the maximum queue-length for queries is `CPU_cores * 256`. -The system rejects additional queries with a 503 error once it reaches the limits. +If you reach either limit, the system rejects additional queries with a 503 error. == Sizing Analytics Service Nodes From 32bb6ca7df05ae50ed2a548a93e4230d81575298 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:45:39 +0530 Subject: [PATCH 30/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index fb8a5f86ec..69398a9827 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -560,7 +560,7 @@ The Analytics Service is dependent on the Data Service and requires the Data ser === Data space -* Make sure that the data space for Analytics node takes into account metadata replicas. +* Make sure that the data space for your Analytics Service nodes takes into account metadata replicas. The Analytics Service only replicates the metadata and not the actual data. There's a small overhead for metadata replicas as metadata is generally small. From 3cb47c6a8e0e45b3970c6e91bb34c9541ad0b0a3 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:48:57 +0530 Subject: [PATCH 31/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 69398a9827..9e03538b1a 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -565,7 +565,8 @@ The Analytics Service only replicates the metadata and not the actual data. There's a small overhead for metadata replicas as metadata is generally small. * When evaluating a query, the Analytics engine uses temporary disk space. -The query type the required amount of temporary disk space. +The type of query you want to run determines the required amount of temporary disk space. ++ For example, queries with heavy JOINs, aggregates, windowing, or additional predicates require more temporary disk space. Typically, the temporary disk space can be 2x the data space. From 53036ad1673312be3534b0a22c1ce6555a9fcf7d Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:52:57 +0530 Subject: [PATCH 32/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 9e03538b1a..7d4528a299 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -574,7 +574,7 @@ Typically, the temporary disk space can be 2x the data space. * When you load data from the Data Service into the Analytics Service, you can apply a filter to reduce both the loaded data size and the Analytics Service storage requirements proportionally. -=== Disk types and partioning +=== Disk Types and Partitioning During query execution, the Analytics query engine concurrently reads and processes data from all partitions. The Input/Output Operations per Second(IOPS) of the physical disk that hosts the data partitions plays a major role in determining the query execution time. From 6cf0e3c79f1e0592c04243dbea44543845a316ef Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:55:14 +0530 Subject: [PATCH 33/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 7d4528a299..79347f0860 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -577,7 +577,7 @@ Typically, the temporary disk space can be 2x the data space. === Disk Types and Partitioning During query execution, the Analytics query engine concurrently reads and processes data from all partitions. -The Input/Output Operations per Second(IOPS) of the physical disk that hosts the data partitions plays a major role in determining the query execution time. +The Input/Output Operations per Second (IOPS) of the physical disk that hosts the data partitions plays a major role in determining the query execution time. Modern storage devices such as SSDs have much higher IOPS and can deal better with concurrent reads than HDDs. Therefore, a single data partition under-utilizes high-IOPS devices. From ed7176a3022fad6210f423097c44e04fc8469558 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 21:57:07 +0530 Subject: [PATCH 34/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 79347f0860..9a594c0e96 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -579,7 +579,7 @@ Typically, the temporary disk space can be 2x the data space. During query execution, the Analytics query engine concurrently reads and processes data from all partitions. The Input/Output Operations per Second (IOPS) of the physical disk that hosts the data partitions plays a major role in determining the query execution time. Modern storage devices such as SSDs have much higher IOPS and can deal better with concurrent reads than HDDs. -Therefore, a single data partition under-utilizes high-IOPS devices. +A single data partition underutilizes high IOPS devices. To simplify setup for nodes with a single modern storage device, the Analytics Service creates multiple data partitions on the same storage device. It does this only when you specify a single Analytics disk path during node initialization. From 6fb368459e73549929c7903356bdf23855484b22 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 22:00:17 +0530 Subject: [PATCH 35/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 9a594c0e96..a85ed5796a 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -583,7 +583,7 @@ A single data partition underutilizes high IOPS devices. To simplify setup for nodes with a single modern storage device, the Analytics Service creates multiple data partitions on the same storage device. It does this only when you specify a single Analytics disk path during node initialization. -The service determines the number of partitions using the following formula: +The Analytics Service determines the number of partitions using the following formula: * `Maximum partitions to create = Min((Analytics Memory in MB / 1024), 16)` * `Actual created partitions = Min(node virtual cores, Maximum partitions to create)` From c4b4abbfd213de001dfa389e70b69998c9c0293e Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 22:04:55 +0530 Subject: [PATCH 36/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index a85ed5796a..af9926b4ff 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -591,7 +591,7 @@ The Analytics Service determines the number of partitions using the following fo For example, if a node has 8 virtual cores and the Analytics Service has at least 8{nbsp}GB of memory, the system creates 8 data partitions on that node. Similarly, for a node with 32 virtual cores and 16{nbsp}GB memory, the system creates 16 partitions, the maximum for automatic partitioning. -=== Index considerations +=== Index Considerations The size of a secondary index is around the total size of indexed fields in the Analytics collection. For example, if a collection has 20 fields and only 1 of those fields appears in the secondary index, the secondary index size is ~1/20 of the collection size. From 484cdf65de621f9c020d69fae4a063534cdd8d86 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 22:05:56 +0530 Subject: [PATCH 37/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index af9926b4ff..53171ae1d3 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -598,7 +598,7 @@ For example, if a collection has 20 fields and only 1 of those fields appears in == Sizing Eventing Service Nodes -Eventing is a compute oriented service. +Eventing is a compute-oriented service. By default, Eventing service has 1 worker and each worker has 2 threads of execution. You can scale eventing both vertically by adding more workers or horizontally by adding more nodes. The Eventing service partitions the vBuckets across the number of available nodes. From c2f21d199e79fc9b7025bfeda756e11b053ab2a3 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:02:03 +0530 Subject: [PATCH 38/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 53171ae1d3..9d01e69f0c 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -599,9 +599,9 @@ For example, if a collection has 20 fields and only 1 of those fields appears in == Sizing Eventing Service Nodes Eventing is a compute-oriented service. -By default, Eventing service has 1 worker and each worker has 2 threads of execution. -You can scale eventing both vertically by adding more workers or horizontally by adding more nodes. -The Eventing service partitions the vBuckets across the number of available nodes. +By default, the Eventing Service has 1 worker and each worker has 2 threads of execution. +You can scale the Eventing Service both vertically by adding more workers or horizontally by adding more nodes. +The Eventing Service partitions the vBuckets across the number of available nodes. === CPU From c62ae67a7eaa9582b235d4552fd5a917fc43e895 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:04:47 +0530 Subject: [PATCH 39/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 9d01e69f0c..00b1249492 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -605,7 +605,7 @@ The Eventing Service partitions the vBuckets across the number of available node === CPU -Eventing runs arbitrary JavaScript code. +The Eventing Service allows you to write and run arbitrary JavaScript code. This flexibility makes it difficult to define a precise sizing formula. You cannot define a precise formula unless you know the function designs, their KV operations, query operations, cURL operations, and the expected mutation rate. From dde62678a907cd7f10a1a9029905df67191a7880 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:09:31 +0530 Subject: [PATCH 40/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 00b1249492..7bfa55d49d 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -611,7 +611,7 @@ You cannot define a precise formula unless you know the function designs, their For example, if you process 100K mutations per second and only match 1 out of 1000 patterns, then perform some intense computation on the matched 100 items in your Eventing Function, you need 100X less compute than if you performed the intense computation on each mutation. -Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/S cURL call. +The Eventing Service also can perform I/O to external REST endpoints through a synchronous HTTP/S cURL call. Eventing typically blocks on I/O and requires little CPU. Achieving high throughput to overcome bandwidth requires additional workers and cores. From 6eabc89b10dc01de7141d31fd225adcfa34313ea Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:10:55 +0530 Subject: [PATCH 41/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 7bfa55d49d..f1d151e0bb 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -612,7 +612,7 @@ You cannot define a precise formula unless you know the function designs, their For example, if you process 100K mutations per second and only match 1 out of 1000 patterns, then perform some intense computation on the matched 100 items in your Eventing Function, you need 100X less compute than if you performed the intense computation on each mutation. The Eventing Service also can perform I/O to external REST endpoints through a synchronous HTTP/S cURL call. -Eventing typically blocks on I/O and requires little CPU. +The Eventing Service typically blocks on I/O and does not need much CPU. Achieving high throughput to overcome bandwidth requires additional workers and cores. Use 8 vCPUs or 4 physical cores to run Eventing Functions. From 6c0c0417ed385162e36d3abe8957c30724465962 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:13:42 +0530 Subject: [PATCH 42/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index f1d151e0bb..c594eb450d 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -615,7 +615,7 @@ The Eventing Service also can perform I/O to external REST endpoints through a s The Eventing Service typically blocks on I/O and does not need much CPU. Achieving high throughput to overcome bandwidth requires additional workers and cores. -Use 8 vCPUs or 4 physical cores to run Eventing Functions. +For a starting size for your Eventing Service nodes and running Eventing Functions, use 8 vCPUs or 4 physical cores. === RAM From 9b721c162fcd5a01782c7016a2e8020270b8cf3b Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:15:19 +0530 Subject: [PATCH 43/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index c594eb450d..a973d2c445 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -619,7 +619,8 @@ For a starting size for your Eventing Service nodes and running Eventing Functio === RAM -The xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. +Couchbase recommends a memory quota of 256{nbsp}MB for the Eventing Service. +For more information about the Eventing Service's memory quota, see xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[]. Refer to this document to learn more about: From 52b518d14a28a987d2fed6d8a1edbd9a79394392 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:18:00 +0530 Subject: [PATCH 44/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index a973d2c445..1355a951e1 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -622,15 +622,6 @@ For a starting size for your Eventing Service nodes and running Eventing Functio Couchbase recommends a memory quota of 256{nbsp}MB for the Eventing Service. For more information about the Eventing Service's memory quota, see xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[]. -Refer to this document to learn more about: - --- -* Eventing Service memory quota -* How Eventing Service memory quota works -* The distribution of the total memory quota across workers -* The limitations and considerations -* Best practices and recommendations --- === Eventing Storage Collection (previously Metadata Bucket) From c6de7163a7b20dbf490d142db2de77365b725f7f Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:19:42 +0530 Subject: [PATCH 45/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 1355a951e1..26b53204b3 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -625,8 +625,8 @@ For more information about the Eventing Service's memory quota, see xref:learn:b === Eventing Storage Collection (previously Metadata Bucket) -Each Eventing function stores fewer than 2048 documents in its Eventing storage collection. -If timers are not used or if the active timers count does not exceed the per-function document limit, store the Eventing storage collection in a 100 MB bucket. +Each Eventing Function stores fewer than 2048 documents in its Eventing storage collection. +If timers are not used or if your number of active timers does not exceed the per-function document limit, store the Eventing storage collection in a 100{nbsp}MB bucket. Using timers requires additional storage for each active timer. Each active timer requires 800 bytes, plus the size of the passed context, which represents the state supplied to the function at future execution. From 506e08fd27a9523646cff0ff9dd98882ad7cb3b3 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:22:33 +0530 Subject: [PATCH 46/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 26b53204b3..d3e18b4f9c 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -631,8 +631,8 @@ If timers are not used or if your number of active timers does not exceed the pe Using timers requires additional storage for each active timer. Each active timer requires 800 bytes, plus the size of the passed context, which represents the state supplied to the function at future execution. -A 200-byte context results in 1 KB of storage per active timer. -100,000 active timers require 100 MB of additional bucket space. +A 200-byte context results in 1{nbsp}KB of storage per active timer. +100,000 active timers require 100{nbsp}MB of additional bucket space. As a best practice, keep this collection fully resident in-memory to make sure constant availability. From cb18e6abd7324b719460a75d7488fccb41b2a2f9 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:23:31 +0530 Subject: [PATCH 47/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index d3e18b4f9c..e0ce687b6a 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -634,7 +634,7 @@ Each active timer requires 800 bytes, plus the size of the passed context, which A 200-byte context results in 1{nbsp}KB of storage per active timer. 100,000 active timers require 100{nbsp}MB of additional bucket space. -As a best practice, keep this collection fully resident in-memory to make sure constant availability. +As a best practice, keep this collection fully resident in-memory. NOTE: All Eventing functions use this collection. From 1c5504443134f236f3943f4edbbbe49c5f78bd83 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:25:22 +0530 Subject: [PATCH 48/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index e0ce687b6a..d3fabdd771 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -636,7 +636,7 @@ A 200-byte context results in 1{nbsp}KB of storage per active timer. As a best practice, keep this collection fully resident in-memory. -NOTE: All Eventing functions use this collection. +NOTE: All your Eventing Functions share this collection. == Sizing Backup Service Nodes From 3d76163f93377129110da618180e5aaad166df2d Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:28:50 +0530 Subject: [PATCH 49/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index d3fabdd771..b597de5568 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -665,6 +665,6 @@ Your cluster must be properly sized to be able to handle new XDCR streams. For example, XDCR needs 1-2 additional CPU cores per stream. In some cases, it also requires additional RAM and network resources. -If a cluster is not sized to handle `both` the existing workload `and` the new XDCR streams, the performance of both XDCR and the cluster overall may be negatively impacted. +If your cluster is not sized to handle both the existing workload and the new XDCR streams, the performance of both XDCR and your cluster might be negatively impacted. For information about preparing your cluster for replication, see xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR]. From a16d5e40f4b183d44da34ae4abd23563f2720b6f Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:44:31 +0530 Subject: [PATCH 50/93] incorporating editorial review comments --- modules/install/pages/sizing-general.adoc | 42 ++++++++++++++--------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index b597de5568..252f0293a1 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -24,9 +24,11 @@ There needs to be enough capacity in all areas to support everything the system === Multi-Dimensional Scaling -Couchbase Services are what allow you to use and maintain your data. -Deploy, maintain, and provision these services independently of each other. -This independent service model allows you to take advantage of `Multi-Dimensional Scaling`, whereby a cluster can be fine-tuned for optimal handling of emergent workload-requirements, on a service-by-service basis. +Couchbase Services allow you to access and maintain your data. +You can deploy, maintain, and provision these services independently of each other. +This independent service model allows you to take advantage of Multi-Dimensional Scaling. + +Multi-Dimensional Scaling lets you fine-tune your cluster for optimal handling of changing workload-requirements, for each individual Couchbase Service. Every service has different demands on hardware resources. Multi-Dimensional Scaling plays an important role when sizing your Couchbase cluster, both pre and post-deployment. @@ -605,38 +607,46 @@ The Eventing Service partitions the vBuckets across the number of available node === CPU -The Eventing Service allows you to write and run arbitrary JavaScript code. +Eventing runs arbitrary JavaScript code. This flexibility makes it difficult to define a precise sizing formula. You cannot define a precise formula unless you know the function designs, their KV operations, query operations, cURL operations, and the expected mutation rate. For example, if you process 100K mutations per second and only match 1 out of 1000 patterns, then perform some intense computation on the matched 100 items in your Eventing Function, you need 100X less compute than if you performed the intense computation on each mutation. -The Eventing Service also can perform I/O to external REST endpoints through a synchronous HTTP/S cURL call. -The Eventing Service typically blocks on I/O and does not need much CPU. +Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/S cURL call. +Eventing typically blocks on I/O and requires little CPU. Achieving high throughput to overcome bandwidth requires additional workers and cores. -For a starting size for your Eventing Service nodes and running Eventing Functions, use 8 vCPUs or 4 physical cores. +Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -Couchbase recommends a memory quota of 256{nbsp}MB for the Eventing Service. -For more information about the Eventing Service's memory quota, see xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[]. +The xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. + +Refer to this document to learn more about: +-- +* Eventing Service memory quota +* How Eventing Service memory quota works +* The distribution of the total memory quota across workers +* The limitations and considerations +* Best practices and recommendations +-- === Eventing Storage Collection (previously Metadata Bucket) -Each Eventing Function stores fewer than 2048 documents in its Eventing storage collection. -If timers are not used or if your number of active timers does not exceed the per-function document limit, store the Eventing storage collection in a 100{nbsp}MB bucket. +Each Eventing function stores fewer than 2048 documents in its Eventing storage collection. +If timers are not used or if the active timers count does not exceed the per-function document limit, store the Eventing storage collection in a 100 MB bucket. Using timers requires additional storage for each active timer. Each active timer requires 800 bytes, plus the size of the passed context, which represents the state supplied to the function at future execution. -A 200-byte context results in 1{nbsp}KB of storage per active timer. -100,000 active timers require 100{nbsp}MB of additional bucket space. +A 200-byte context results in 1 KB of storage per active timer. +100,000 active timers require 100 MB of additional bucket space. -As a best practice, keep this collection fully resident in-memory. +As a best practice, keep this collection fully resident in-memory to make sure constant availability. -NOTE: All your Eventing Functions share this collection. +NOTE: All Eventing functions use this collection. == Sizing Backup Service Nodes @@ -665,6 +675,6 @@ Your cluster must be properly sized to be able to handle new XDCR streams. For example, XDCR needs 1-2 additional CPU cores per stream. In some cases, it also requires additional RAM and network resources. -If your cluster is not sized to handle both the existing workload and the new XDCR streams, the performance of both XDCR and your cluster might be negatively impacted. +If a cluster is not sized to handle `both` the existing workload `and` the new XDCR streams, the performance of both XDCR and the cluster overall may be negatively impacted. For information about preparing your cluster for replication, see xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR]. From 7152bd3ef9b3fc81a25abeea756202f7649a889f Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 12 Jan 2026 23:49:00 +0530 Subject: [PATCH 51/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 252f0293a1..e2ca1afcc3 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -30,9 +30,10 @@ This independent service model allows you to take advantage of Multi-Dimensional Multi-Dimensional Scaling lets you fine-tune your cluster for optimal handling of changing workload-requirements, for each individual Couchbase Service. -Every service has different demands on hardware resources. +Every Service has different demands on hardware resources. Multi-Dimensional Scaling plays an important role when sizing your Couchbase cluster, both pre and post-deployment. -For example, core Data Service operations can often benefit greatly from the `scale out` of smaller commodity nodes, whereas low latency operations with the Query Service may see a greater benefit from the `scale up` of hardware resources on a given node. +For example, core Data Service operations can often benefit from scaling out smaller commodity nodes. +Low latency operations with the Query Service might see a greater benefit from scaling up hardware resources on a given node. For more information about the nature and resource demands of each Couchbase Service, see xref:learn:services-and-indexes/services/services.adoc[Services]. From c7b77e8c7975dc01929307c9ce4930b29d0658d5 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:22:25 +0530 Subject: [PATCH 52/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 606afeb0d8..38b619f767 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -1,4 +1,4 @@ -= Eventing Memory Quota += Eventing Service Memory Quota :description: The Eventing Service memory quota does not enforce a hard memory limit on the Eventing subsystem, including worker processes. From a79aa4e20a6d6eff763ff07958021fcae57a5810 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:23:25 +0530 Subject: [PATCH 53/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 38b619f767..f9455165bb 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -2,7 +2,7 @@ :description: The Eventing Service memory quota does not enforce a hard memory limit on the Eventing subsystem, including worker processes. -This page explains how the memory quota actually works, how Eventing distributes it across workers, and its limitations in non-containerized environments. +This page explains how the memory quota actually works, how the Eventing Service distributes it across workers, and its limitations in non-containerized environments. [abstract] {description} From 7199dc2202abb03b27fcd4acd869963094a097e6 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:24:15 +0530 Subject: [PATCH 54/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index f9455165bb..51a1039959 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -7,7 +7,7 @@ This page explains how the memory quota actually works, how the Eventing Service [abstract] {description} -== Overview +== About the Eventing Service Memory Quota The Couchbase Eventing Service memory quota does not enforce a hard memory limit on the entire Eventing subsystem, including worker processes. The service uses the quota for queue sizing and JavaScript (JS) runtime memory heap, not as an absolute memory cap. From 4bfd4355659eb8e63f37ed726442cf7579353161 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:24:46 +0530 Subject: [PATCH 55/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 51a1039959..1b57030f7e 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -9,7 +9,6 @@ This page explains how the memory quota actually works, how the Eventing Service == About the Eventing Service Memory Quota -The Couchbase Eventing Service memory quota does not enforce a hard memory limit on the entire Eventing subsystem, including worker processes. The service uses the quota for queue sizing and JavaScript (JS) runtime memory heap, not as an absolute memory cap. In VM or bare-metal deployments, Eventing functions can exceed the configured quota at runtime. Understanding this behavior helps you to appropriately size and monitor Eventing functions in production environments. From 240fc4fd06bb1a739c59db1a9e633b4cb5ce4999 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:25:27 +0530 Subject: [PATCH 56/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 25 ++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 1b57030f7e..d416395662 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -9,9 +9,28 @@ This page explains how the memory quota actually works, how the Eventing Service == About the Eventing Service Memory Quota -The service uses the quota for queue sizing and JavaScript (JS) runtime memory heap, not as an absolute memory cap. -In VM or bare-metal deployments, Eventing functions can exceed the configured quota at runtime. -Understanding this behavior helps you to appropriately size and monitor Eventing functions in production environments. +The Eventing Service uses the quota for: + +* <>: Controls the maximum size of each worker's input queue. +* <>: Determines when the Eventing Service invokes the JavaScript environment's GC to reclaim memory. + +The memory quota is not an absolute memory cap. +The quota does not restrict the total memory consumed by JavaScript runtime heaps or Eventing processes. + +The Eventing Service divides its total memory quota uniformly across all workers in all deployed functions: +.... +Per-Worker quota = Total memory quota ÷ Total number of workers +.... + +For example, if you had a memory quota of 256{nbsp}MB, with 4 total workers, each worker would use 64{nbsp}MB of memory, or 256 MB ÷ 4 workers. + +Each worker receives an equal share of the total quota, regardless of the actual memory usage of individual functions. + +As you deploy more functions or add workers per function, the per-worker quota decreases proportionally. +A smaller per-worker quota can affect performance if individual functions require substantial memory for processing. + +In VM or bare-metal deployments, Eventing Functions can exceed the configured quota at runtime. +Understanding this behavior helps you to appropriately size and monitor your Eventing Functions in production environments. == How Memory Quota Works From 330074f00244d8640ce876eb556ff4a13861af74 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:26:21 +0530 Subject: [PATCH 57/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index d416395662..387d8ece82 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -32,7 +32,6 @@ A smaller per-worker quota can affect performance if individual functions requir In VM or bare-metal deployments, Eventing Functions can exceed the configured quota at runtime. Understanding this behavior helps you to appropriately size and monitor your Eventing Functions in production environments. -== How Memory Quota Works The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and frequency of garbage collection. However, it does not act as an absolute ceiling on memory usage. From 9e3a284709a298048896425d453f8bca78ca9566 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:27:25 +0530 Subject: [PATCH 58/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 387d8ece82..42387e6704 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -33,7 +33,6 @@ In VM or bare-metal deployments, Eventing Functions can exceed the configured qu Understanding this behavior helps you to appropriately size and monitor your Eventing Functions in production environments. -The Eventing Service memory quota controls specific aspects of memory management, such as queue sizing and frequency of garbage collection. However, it does not act as an absolute ceiling on memory usage. === Minimum Size From d6ca13f4f34bdd7b4680b8558755bc6359c07745 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:28:20 +0530 Subject: [PATCH 59/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 42387e6704..2c9f6312cf 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -33,7 +33,6 @@ In VM or bare-metal deployments, Eventing Functions can exceed the configured qu Understanding this behavior helps you to appropriately size and monitor your Eventing Functions in production environments. -However, it does not act as an absolute ceiling on memory usage. === Minimum Size From 373fb07d1530841876d8e8b31f5270655701a9af Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:29:09 +0530 Subject: [PATCH 60/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 2c9f6312cf..f8c3309617 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -36,8 +36,8 @@ Understanding this behavior helps you to appropriately size and monitor your Eve === Minimum Size -The memory quota must be a minimum of 256 MB. -Couchbase does not support values lesser than 256 MB. +The memory quota for the Eventing Service must be a minimum of 256{nbsp}MB. +Couchbase does not support memory quota values smaller than 256{nbsp}MB. === Purpose of the Quota From a01f0110af462a875f5e69ec43e2548de6de8f03 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:29:24 +0530 Subject: [PATCH 61/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index f8c3309617..4689f82097 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -39,13 +39,6 @@ Understanding this behavior helps you to appropriately size and monitor your Eve The memory quota for the Eventing Service must be a minimum of 256{nbsp}MB. Couchbase does not support memory quota values smaller than 256{nbsp}MB. -=== Purpose of the Quota - -The memory quota serves 2 primary purposes: - -* **Worker queue sizing**: controls the maximum size of each worker's input queue. -* **Garbage Collection (GC) triggering**: determines when Eventing invokes JavaScript environment GC to reclaim memory. -The quota does not restrict the total memory consumed by JavaScript runtime heaps or Eventing processes. == Per-Worker Distribution From bc9b5916ed5ea484699d123813eb5da22c302c7b Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:29:47 +0530 Subject: [PATCH 62/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 4689f82097..88fc4182e1 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -40,7 +40,6 @@ The memory quota for the Eventing Service must be a minimum of 256{nbsp}MB. Couchbase does not support memory quota values smaller than 256{nbsp}MB. -== Per-Worker Distribution The Eventing Service divides the total memory quota uniformly across all workers in all deployed functions. From 9120dc2dde1556444418893e3375811b451d241e Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:30:03 +0530 Subject: [PATCH 63/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 88fc4182e1..938c6590ec 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -41,7 +41,6 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. -The Eventing Service divides the total memory quota uniformly across all workers in all deployed functions. === Calculation Eventing calculates the per-worker quota as follows: From 08969f230d83aff1a7eb4178d15ee4dc49e59edb Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:30:21 +0530 Subject: [PATCH 64/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 938c6590ec..44b12cf4a5 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -42,11 +42,6 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. -=== Calculation -Eventing calculates the per-worker quota as follows: -.... -Per-Worker quota = Total memory quota ÷ Total number of workers -.... === Example From d5fe615438cbf28342d206ed26d11b03387a5608 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:32:09 +0530 Subject: [PATCH 65/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 44b12cf4a5..57f092eb85 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -43,15 +43,6 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. -=== Example - -Consider the following configuration: - -* Total memory quota: 256 MB -* Total workers (across all deployed functions): 4 -* Per-worker budget: 64 MB (256 MB ÷ 4 workers) - -Each worker receives an equal share of the total quota, regardless of the actual memory usage of individual functions. === Impact of Worker Count From d2f5b168b5ef35a8623143afd58ed8f7512a9baf Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:32:28 +0530 Subject: [PATCH 66/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 57f092eb85..f2bf7a36af 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -44,10 +44,6 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. -=== Impact of Worker Count - -As you deploy more functions or add workers per function, the per-worker quota decreases proportionally. -A smaller per-worker quota can affect performance if individual functions require substantial memory for processing. == Queue Sizing and GC Behavior From c4aafaf00707c740b61c0f97c64dd39cd47ff3b4 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:32:44 +0530 Subject: [PATCH 67/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 3 --- 1 file changed, 3 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index f2bf7a36af..6a59b25566 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -45,9 +45,6 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. -== Queue Sizing and GC Behavior - -The per-worker quota directly influences 2 key aspects of Eventing runtime behavior. === Worker Queue Sizing From 2ff83c6bddf5c15d1cf739bdb49b63f8e986d87f Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:33:02 +0530 Subject: [PATCH 68/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 6a59b25566..552cd2b134 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -46,7 +46,7 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. -=== Worker Queue Sizing +== Worker Queue Sizing Each worker maintains a bounded input queue that receives changes to documents from the Database Change Protocol (xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[DCP]) stream. From ac8baec2e9ff1a735e09e867ead851bdaf93e342 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:34:02 +0530 Subject: [PATCH 69/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 552cd2b134..c4527d4f2b 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -48,7 +48,7 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. == Worker Queue Sizing -Each worker maintains a bounded input queue that receives changes to documents from the Database Change Protocol (xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[DCP]) stream. +Each worker maintains a bounded input queue that receives changes to documents from the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[Database Change Protocol (DCP)] stream. * The per-worker quota determines the maximum size of this queue. * When the queue exceeds this size, Eventing throttles the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[DCP] stream to prevent unbounded memory growth. From 827c5b57e89433ae91e78d860ac2c48385e7c711 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:34:49 +0530 Subject: [PATCH 70/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index c4527d4f2b..ac251cc009 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -50,9 +50,11 @@ Couchbase does not support memory quota values smaller than 256{nbsp}MB. Each worker maintains a bounded input queue that receives changes to documents from the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[Database Change Protocol (DCP)] stream. -* The per-worker quota determines the maximum size of this queue. -* When the queue exceeds this size, Eventing throttles the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[DCP] stream to prevent unbounded memory growth. -* Throttling temporarily pauses mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. +The per-worker quota determines the maximum size of this queue. + +When the queue exceeds this size, the Eventing Service throttles the DCP stream to prevent unbounded memory growth. + +Throttling temporarily pauses the mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. === Garbage Collection (GC) Triggering From 666307bd829cf4ad6620f94c67ac49994280a6e4 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:35:11 +0530 Subject: [PATCH 71/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index ac251cc009..e7c9ad1d1c 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -58,14 +58,18 @@ Throttling temporarily pauses the mutation flow, ensuring workers do not become === Garbage Collection (GC) Triggering -* GC frees memory occupied by unreachable objects that are no longer in use. -* GC reclaims memory only from objects that are no longer in use. +The Eventing Service's garbage collection (GC) frees memory occupied by unreachable objects that are no longer in use by Eventing Functions. + +Garbage collection reclaims memory only from objects that are no longer in use. Memory held by live objects in the JavaScript runtime heap remains allocated, so total usage may exceed the per-worker quota. -NOTE: When memory usage approaches the per-worker quota limit, the JavaScript runtime may trigger garbage collection to reclaim memory. -However, the garbage collector may delay the stop-the-world collection because it's optimized for throughput. -As a result, the runtime may not reclaim memory without delay, which can temporarily affect Eventing memory consumption. -The service invokes a stop-the-world JavaScript runtime GC to reduce memory inside the JavaScript runtime isolate running each function. +When memory usage approaches the per-worker quota limit, the JavaScript runtime may trigger garbage collection to reclaim memory. + +The garbage collector may delay the stop-the-world collection because it's optimized for throughput. + +The runtime might not reclaim memory without a delay, which can temporarily affect the Eventing Service's memory consumption. + +The Eventing Service invokes a stop-the-world JavaScript runtime garbage collection to reduce memory inside the JavaScript runtime isolate running each Eventing Function. == Limitations and Considerations The Eventing Service memory quota has important limitations that users must understand to prevent operational issues: From d83b5f66b15dec1b38f32fafad31c61246eeb636 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:36:38 +0530 Subject: [PATCH 72/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index e7c9ad1d1c..d02b2d3b1f 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -56,7 +56,8 @@ When the queue exceeds this size, the Eventing Service throttles the DCP stream Throttling temporarily pauses the mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. -=== Garbage Collection (GC) Triggering +[#gc-trigger] +== Garbage Collection (GC) Triggering The Eventing Service's garbage collection (GC) frees memory occupied by unreachable objects that are no longer in use by Eventing Functions. From 0afb8c9ca78724e6bcbd5ed01af34934b68533ec Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:38:46 +0530 Subject: [PATCH 73/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index d02b2d3b1f..5a351ff19e 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -73,13 +73,13 @@ The runtime might not reclaim memory without a delay, which can temporarily affe The Eventing Service invokes a stop-the-world JavaScript runtime garbage collection to reduce memory inside the JavaScript runtime isolate running each Eventing Function. == Limitations and Considerations -The Eventing Service memory quota has important limitations that users must understand to prevent operational issues: -* Not a hard limit: The quota does not cap total memory usage. -Live objects in JavaScript runtime heaps may persist, so memory usage can exceed the quota. -* No OS-level enforcement outside cgroups: In VM or bare-metal deployments, the operating system does not enforce memory limits. -* Worker sizing impacts memory: Configuring an excessive number of workers or running memory-intensive functions can increase memory pressure and affect node stability. -* Quota applies per worker, not per function: Each worker receives an equal share of the total quota, regardless of individual function memory requirements. +To prevent operational issues while using the Eventing Service, keep the following in mind while configuring the memory quota: + +* <> +* <> +* <> +* <> === Not a Hard Limit From 724e3e53edb96040c03896ead9e375531cd9b1bd Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:39:31 +0530 Subject: [PATCH 74/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 5a351ff19e..d59bd0a601 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -81,6 +81,7 @@ To prevent operational issues while using the Eventing Service, keep the followi * <> * <> +[#no-hard-limit] === Not a Hard Limit The Eventing Service memory quota does not restrict total memory usage. From ada3e00860c1fb975ce7b959770280bc61d55b5e Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:40:50 +0530 Subject: [PATCH 75/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 36 ++++++++++++------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index d59bd0a601..81678b8379 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -103,29 +103,41 @@ In non-containerized environments, the operating system does not enforce the mem * High-memory-consuming functions can affect overall system stability. * Eventing does not automatically stop or throttle execution when total memory exceeds the quota. -=== Memory Isolation +[#worker-sizing-memory] +=== Worker Sizing Impacts Memory -The memory quota does not isolate memory usage between Eventing functions. +When configuring the memory quota for the Eventing Service, consider the per-worker quota when determining the number of workers. +Avoid over-provisioning workers when Eventing Functions require substantial memory. -* All workers draw from the same total memory quota. -* A memory-intensive function can reduce the memory available to other functions. -* Eventing does not support per-function memory limits or reservations. +For best results, try to balance your worker count against your available memory. + +[#quota-per-worker] +=== Quota Applies Per Worker + +The memory quota does not isolate memory usage between Eventing Functions. +All workers draw from the same total memory quota. + +A memory-intensive function can reduce the memory available to other Eventing Functions. + +Eventing does not support per-function memory limits or reservations. == Best Practices -Follow these recommendations to effectively manage Eventing memory usage effectively and avoid operational issues. +Follow these recommendations to effectively manage Eventing memory usage: + +* <> +* <> +* <> +* <> +* <> + +[#monitor] === Monitor Memory Usage * Use system-level monitoring tools to track actual memory consumption. * Monitor memory usage for the Eventing process and individual workers. * Configure alerts for memory thresholds well below system limits. -=== Configure Worker Count Appropriately - -* Consider the per-worker quota when determining the number of workers. -* Avoid over-provisioning workers when Eventing functions require substantial memory. -* Balance the worker count against available system memory. - === Test in Representative Environments * Test Eventing functions under production-like load conditions. From a9b3726ea4fcb6fc0d25f57859750aa5f1dcea6a Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:42:04 +0530 Subject: [PATCH 76/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../buckets-memory-and-storage/eventing-memory-quota.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 81678b8379..21decf8880 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -88,11 +88,11 @@ The Eventing Service memory quota does not restrict total memory usage. JavaScript runtime heaps may still contain live (non-garbage) objects that: -* GC cannot reclaim. -* The quota does not account. +* Garbage collection cannot reclaim. +* The quota does not include. * Continue to consume memory beyond the configured limit. -As a result, setting a memory quota does not guarantee that Eventing functions remain within that limit. +As a result, setting a memory quota does not guarantee that Eventing Functions remain within that limit. === No OS-Level Enforcement Outside cgroups From 5d37f4c0064d52cfef1eaa6650102a653edbe775 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:42:23 +0530 Subject: [PATCH 77/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../pages/buckets-memory-and-storage/eventing-memory-quota.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 21decf8880..3f3395b3af 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -94,6 +94,7 @@ JavaScript runtime heaps may still contain live (non-garbage) objects that: As a result, setting a memory quota does not guarantee that Eventing Functions remain within that limit. +[#no-enforce-c-groups] === No OS-Level Enforcement Outside cgroups In non-containerized environments, the operating system does not enforce the memory quota. From f896f4c323244577bc232fdf8ac2496ec701e46b Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:45:46 +0530 Subject: [PATCH 78/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 3f3395b3af..eb55a2d119 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -99,10 +99,12 @@ As a result, setting a memory quota does not guarantee that Eventing Functions r In non-containerized environments, the operating system does not enforce the memory quota. -* Users must monitor Eventing memory usage using system tools. -* Configuring an excessive number of workers can lead to memory exhaustion. -* High-memory-consuming functions can affect overall system stability. -* Eventing does not automatically stop or throttle execution when total memory exceeds the quota. +You must monitor the Eventing Service's memory usage using system tools. + +If you configure too many workers for your Eventing Functions, you can cause memory exhaustion in your cluster. +High memory-consuming Eventing Functions can affect your overall system stability. + +Again, the Eventing Service does not automatically stop or throttle execution when total memory exceeds the quota. [#worker-sizing-memory] === Worker Sizing Impacts Memory From 9edf568f3180c21b3dd13de902e48358b5cfe336 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:46:25 +0530 Subject: [PATCH 79/93] Update modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- .../eventing-memory-quota.adoc | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index eb55a2d119..16b7af94eb 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -141,31 +141,35 @@ Follow these recommendations to effectively manage Eventing memory usage: * Monitor memory usage for the Eventing process and individual workers. * Configure alerts for memory thresholds well below system limits. +[#test] === Test in Representative Environments -* Test Eventing functions under production-like load conditions. +* Test Eventing Functions under production-like load conditions. * Measure actual memory consumption during peak processing. * Validate that memory usage remains within acceptable limits. +[#use-cgroups] === Use cgroups for Enforcement * Consider containerized deployments or cgroup-based memory limits in production environments. * Container platforms such as Docker and Kubernetes provide hard memory limits. * cgroups enforce OS-level memory restrictions. -* This approach adds a safety layer beyond the Eventing Service memory quota. +This approach adds a safety layer beyond the Eventing Service memory quota. +[#size] === Size the Memory Quota Appropriately -* Set the Eventing memory quota based on expected worker count and function complexity. -* Allow additional headroom on top of the 256 MB default for production workloads. +* Set the Eventing Service memory quota based on expected worker count and Eventing Function complexity. +* Allow additional headroom on top of the 256{nbsp}MB default for production workloads. * Account for peak processing scenarios, not just average load. +[#review] === Review Function Memory Efficiency * Optimize JavaScript code to minimize memory allocation. -* Avoid accumulating large data structures in function scope. +* Avoid accumulating large data structures in the function scope. * Release object references when data is no longer needed. -* Profile functions to identify memory-intensive operations. +* Profile Eventing Functions to identify memory-intensive operations. // Learn how to provide links to other doc pages and provide references to pages like Eventing Service Overview, Eventing Service Settings, and Eventing Function Examples. // == Related Links From 7b4ac1b553241ae4e1b65c219bf4f048ffa941c9 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 00:49:53 +0530 Subject: [PATCH 80/93] incorporating editorial review comments --- .../eventing-memory-quota.adoc | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc index 16b7af94eb..f1b9df5bf1 100644 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc @@ -33,19 +33,12 @@ In VM or bare-metal deployments, Eventing Functions can exceed the configured qu Understanding this behavior helps you to appropriately size and monitor your Eventing Functions in production environments. - === Minimum Size The memory quota for the Eventing Service must be a minimum of 256{nbsp}MB. Couchbase does not support memory quota values smaller than 256{nbsp}MB. - - - - - - == Worker Queue Sizing Each worker maintains a bounded input queue that receives changes to documents from the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[Database Change Protocol (DCP)] stream. @@ -171,8 +164,8 @@ This approach adds a safety layer beyond the Eventing Service memory quota. * Release object references when data is no longer needed. * Profile Eventing Functions to identify memory-intensive operations. -// Learn how to provide links to other doc pages and provide references to pages like Eventing Service Overview, Eventing Service Settings, and Eventing Function Examples. -// == Related Links -// * xref:eventing-service-overview.adoc[Eventing Service Overview] -// * xref:eventing-service-settings.adoc[Eventing Service Settings] -// * \ No newline at end of file +== Related Links +* xref:eventing-service-overview.adoc[Eventing Service Overview] +* xref:eventing-service-settings.adoc[Eventing Service Settings] +* xref:manage:eventing/manage-eventing.adoc[Managing the Eventing Service] +* xref:troubleshooting/eventing-troubleshooting.adoc[Eventing Service Troubleshooting] From 067bb727bc7676d30a46abf1d5ef4e716660b129 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 01:07:47 +0530 Subject: [PATCH 81/93] adding path to the Eventing memory quota file in eventing directory --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index e2ca1afcc3..31261c5486 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -622,7 +622,7 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -The xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service memory quota in detail. +The xref:learn:eventing/eventing-memory-quota.adoc[Eventing Service Memory Quota] doc discusses the Eventing Service memory quota in detail. Refer to this document to learn more about: From 57723ce8465f048f283e045eda1414536fef6b6c Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 11:44:18 +0530 Subject: [PATCH 82/93] fixing typo and link in the sizing-genera file --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 31261c5486..9f887d4a60 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -622,7 +622,7 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -The xref:learn:eventing/eventing-memory-quota.adoc[Eventing Service Memory Quota] doc discusses the Eventing Service memory quota in detail. +The xref:eventing:eventing-memory-quota.adoc[Eventing Service Memory Quota] doc discusses the Eventing Service Memory quota in detail. Refer to this document to learn more about: From b9982fd151317727bb2663d0813b4afd0f847aef Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 14:06:23 +0530 Subject: [PATCH 83/93] deleting eventing-memory-quota.adoc file from the docs-server repo --- .../eventing-memory-quota.adoc | 171 ------------------ 1 file changed, 171 deletions(-) delete mode 100644 modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc diff --git a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc b/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc deleted file mode 100644 index f1b9df5bf1..0000000000 --- a/modules/learn/pages/buckets-memory-and-storage/eventing-memory-quota.adoc +++ /dev/null @@ -1,171 +0,0 @@ -= Eventing Service Memory Quota - -:description: The Eventing Service memory quota does not enforce a hard memory limit on the Eventing subsystem, including worker processes. - -This page explains how the memory quota actually works, how the Eventing Service distributes it across workers, and its limitations in non-containerized environments. - -[abstract] -{description} - -== About the Eventing Service Memory Quota - -The Eventing Service uses the quota for: - -* <>: Controls the maximum size of each worker's input queue. -* <>: Determines when the Eventing Service invokes the JavaScript environment's GC to reclaim memory. - -The memory quota is not an absolute memory cap. -The quota does not restrict the total memory consumed by JavaScript runtime heaps or Eventing processes. - -The Eventing Service divides its total memory quota uniformly across all workers in all deployed functions: -.... -Per-Worker quota = Total memory quota ÷ Total number of workers -.... - -For example, if you had a memory quota of 256{nbsp}MB, with 4 total workers, each worker would use 64{nbsp}MB of memory, or 256 MB ÷ 4 workers. - -Each worker receives an equal share of the total quota, regardless of the actual memory usage of individual functions. - -As you deploy more functions or add workers per function, the per-worker quota decreases proportionally. -A smaller per-worker quota can affect performance if individual functions require substantial memory for processing. - -In VM or bare-metal deployments, Eventing Functions can exceed the configured quota at runtime. -Understanding this behavior helps you to appropriately size and monitor your Eventing Functions in production environments. - - -=== Minimum Size - -The memory quota for the Eventing Service must be a minimum of 256{nbsp}MB. -Couchbase does not support memory quota values smaller than 256{nbsp}MB. - - -== Worker Queue Sizing - -Each worker maintains a bounded input queue that receives changes to documents from the xref:server:learn:clusters-and-availability/intra-cluster-replication.adoc#database-change-protocol[Database Change Protocol (DCP)] stream. - -The per-worker quota determines the maximum size of this queue. - -When the queue exceeds this size, the Eventing Service throttles the DCP stream to prevent unbounded memory growth. - -Throttling temporarily pauses the mutation flow, ensuring workers do not become overwhelmed when processing lags behind the mutation rate. - -[#gc-trigger] -== Garbage Collection (GC) Triggering - -The Eventing Service's garbage collection (GC) frees memory occupied by unreachable objects that are no longer in use by Eventing Functions. - -Garbage collection reclaims memory only from objects that are no longer in use. -Memory held by live objects in the JavaScript runtime heap remains allocated, so total usage may exceed the per-worker quota. - -When memory usage approaches the per-worker quota limit, the JavaScript runtime may trigger garbage collection to reclaim memory. - -The garbage collector may delay the stop-the-world collection because it's optimized for throughput. - -The runtime might not reclaim memory without a delay, which can temporarily affect the Eventing Service's memory consumption. - -The Eventing Service invokes a stop-the-world JavaScript runtime garbage collection to reduce memory inside the JavaScript runtime isolate running each Eventing Function. - -== Limitations and Considerations - -To prevent operational issues while using the Eventing Service, keep the following in mind while configuring the memory quota: - -* <> -* <> -* <> -* <> - -[#no-hard-limit] -=== Not a Hard Limit - -The Eventing Service memory quota does not restrict total memory usage. - -JavaScript runtime heaps may still contain live (non-garbage) objects that: - -* Garbage collection cannot reclaim. -* The quota does not include. -* Continue to consume memory beyond the configured limit. - -As a result, setting a memory quota does not guarantee that Eventing Functions remain within that limit. - -[#no-enforce-c-groups] -=== No OS-Level Enforcement Outside cgroups - -In non-containerized environments, the operating system does not enforce the memory quota. - -You must monitor the Eventing Service's memory usage using system tools. - -If you configure too many workers for your Eventing Functions, you can cause memory exhaustion in your cluster. -High memory-consuming Eventing Functions can affect your overall system stability. - -Again, the Eventing Service does not automatically stop or throttle execution when total memory exceeds the quota. - -[#worker-sizing-memory] -=== Worker Sizing Impacts Memory - -When configuring the memory quota for the Eventing Service, consider the per-worker quota when determining the number of workers. -Avoid over-provisioning workers when Eventing Functions require substantial memory. - -For best results, try to balance your worker count against your available memory. - -[#quota-per-worker] -=== Quota Applies Per Worker - -The memory quota does not isolate memory usage between Eventing Functions. -All workers draw from the same total memory quota. - -A memory-intensive function can reduce the memory available to other Eventing Functions. - -Eventing does not support per-function memory limits or reservations. - -== Best Practices - -Follow these recommendations to effectively manage Eventing memory usage: - -* <> -* <> -* <> -* <> -* <> - -[#monitor] -=== Monitor Memory Usage - -* Use system-level monitoring tools to track actual memory consumption. -* Monitor memory usage for the Eventing process and individual workers. -* Configure alerts for memory thresholds well below system limits. - -[#test] -=== Test in Representative Environments - -* Test Eventing Functions under production-like load conditions. -* Measure actual memory consumption during peak processing. -* Validate that memory usage remains within acceptable limits. - -[#use-cgroups] -=== Use cgroups for Enforcement - -* Consider containerized deployments or cgroup-based memory limits in production environments. -* Container platforms such as Docker and Kubernetes provide hard memory limits. -* cgroups enforce OS-level memory restrictions. -This approach adds a safety layer beyond the Eventing Service memory quota. - -[#size] -=== Size the Memory Quota Appropriately - -* Set the Eventing Service memory quota based on expected worker count and Eventing Function complexity. -* Allow additional headroom on top of the 256{nbsp}MB default for production workloads. -* Account for peak processing scenarios, not just average load. - -[#review] -=== Review Function Memory Efficiency - -* Optimize JavaScript code to minimize memory allocation. -* Avoid accumulating large data structures in the function scope. -* Release object references when data is no longer needed. -* Profile Eventing Functions to identify memory-intensive operations. - -== Related Links -* xref:eventing-service-overview.adoc[Eventing Service Overview] -* xref:eventing-service-settings.adoc[Eventing Service Settings] -* xref:manage:eventing/manage-eventing.adoc[Managing the Eventing Service] -* xref:troubleshooting/eventing-troubleshooting.adoc[Eventing Service Troubleshooting] From 91fc88f0f134dd13c82380407a778f9a3d573f0a Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 14:26:14 +0530 Subject: [PATCH 84/93] deleting the link to the eventing-memory-quota.adoc file from the nav.adoc file in the docs-server repo --- modules/ROOT/nav.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index a48b3b60ae..9e1a0063cb 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -51,7 +51,6 @@ include::third-party:partial$nav.adoc[] *** xref:learn:buckets-memory-and-storage/compression.adoc[Compression] ** xref:learn:buckets-memory-and-storage/memory-and-storage.adoc[Memory and Storage] *** xref:learn:buckets-memory-and-storage/memory.adoc[Memory] - *** xref:learn:buckets-memory-and-storage/eventing-memory-quota.adoc[Eventing Memory Quota] *** xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines] *** xref:learn:buckets-memory-and-storage/storage-settings.adoc[Storage Properties] * xref:learn:services-and-indexes/services/services.adoc[Services] From e87c625e87320454189a28d1be451019aed848b8 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 15:44:05 +0530 Subject: [PATCH 85/93] gave a fresh link to the eventing-memory-quota.adoc file from the nav.adoc file in the docs-server repo --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 9f887d4a60..171c6dca39 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -622,7 +622,7 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -The xref:eventing:eventing-memory-quota.adoc[Eventing Service Memory Quota] doc discusses the Eventing Service Memory quota in detail. +The xref:eventing:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service Memory quota in detail. Refer to this document to learn more about: From e8228092b53e863c7d466494c3189df425bfa06a Mon Sep 17 00:00:00 2001 From: Hakim Cassimally Date: Tue, 13 Jan 2026 11:27:03 +0000 Subject: [PATCH 86/93] DOC-13422 add preview config This will also build the related docs-devex branch --- preview/DOC-13422-Eventing-Memory-Quota.yml | 29 +++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 preview/DOC-13422-Eventing-Memory-Quota.yml diff --git a/preview/DOC-13422-Eventing-Memory-Quota.yml b/preview/DOC-13422-Eventing-Memory-Quota.yml new file mode 100644 index 0000000000..941d8ddab5 --- /dev/null +++ b/preview/DOC-13422-Eventing-Memory-Quota.yml @@ -0,0 +1,29 @@ +sources: + docs-devex: + branches: DOC-13422-Eventing-Memory-Quota_FOR_DEVEX + + docs-analytics: + branches: release/8.0 + + couchbase-cli: + branches: morpheus + startPaths: docs/ + + backup: + branches: morpheus + startPaths: docs/ + + #analytics: + # url: ../../docs-includes/docs-analytics + # branches: HEAD + + cb-swagger: + url: https://github.com/couchbaselabs/cb-swagger + branches: release/8.0 + start_path: docs + + # Minimal SDK build + docs-sdk-common: + branches: [release/8.0] + docs-sdk-java: + branches: [3.8-api] From fe8f5dffe54111d0da58bcfa8975873d20d09000 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 20:18:41 +0530 Subject: [PATCH 87/93] deleted some bulletted reference points that were suggested to be deleted --- modules/install/pages/sizing-general.adoc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 171c6dca39..efc5481048 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -624,15 +624,6 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. The xref:eventing:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service Memory quota in detail. -Refer to this document to learn more about: - --- -* Eventing Service memory quota -* How Eventing Service memory quota works -* The distribution of the total memory quota across workers -* The limitations and considerations -* Best practices and recommendations --- === Eventing Storage Collection (previously Metadata Bucket) From 667e3ec74782eb665c741a76110c3a676991fbb4 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 22:44:51 +0530 Subject: [PATCH 88/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index efc5481048..c731034dcd 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -515,7 +515,7 @@ Based on the above formula, these are the suggested sizing guidelines: | (3200000000) * (1 + 0.25) * 0.2 = 800000000 bytes |=== -The above example shows the memory requirement of a secondary index with 10M index entries, each with 50 bytes size of secondary key and 30 bytes size of documentID. +The previous example shows the memory requirement of a secondary index with 10M index entries, each with a 50 bytes secondary key and a 30 bytes DocumentID. The memory usage requirements are 2.5{nbsp}GB (Nitro, 100% resident), 1{nbsp}GB (plasma, 20% resident), 800{nbsp}MB (ForestDB, 20% resident). NOTE: The storage engine used in the sizing calculation corresponds to the storage mode chosen for Index Service as explained in the table below. From baf5e045de43fc7b9a520f98fd9faac5b127a3bf Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 22:46:14 +0530 Subject: [PATCH 89/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index c731034dcd..1fe26116ca 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -614,7 +614,7 @@ You cannot define a precise formula unless you know the function designs, their For example, if you process 100K mutations per second and only match 1 out of 1000 patterns, then perform some intense computation on the matched 100 items in your Eventing Function, you need 100X less compute than if you performed the intense computation on each mutation. -Eventing also can perform I/O to external REST endpoints via a synchronous HTTP/S cURL call. +Eventing also can perform I/O to external REST endpoints through a synchronous HTTP/S cURL call. Eventing typically blocks on I/O and requires little CPU. Achieving high throughput to overcome bandwidth requires additional workers and cores. From 46af64277f1ef9460b9bf4f831f38baa85a527d9 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 22:48:28 +0530 Subject: [PATCH 90/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 1fe26116ca..340c678428 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -622,7 +622,7 @@ Use 8 vCPUs or 4 physical cores to run Eventing Functions. === RAM -The xref:eventing:eventing-memory-quota.adoc[Eventing Memory Quota] doc discusses the Eventing Service Memory quota in detail. +For more information about how to size your Eventing memory quota, see xref:eventing:eventing-memory-quota.adoc[]. === Eventing Storage Collection (previously Metadata Bucket) From b1cd88e377438f345e1f4973b2a1c54fe9beb43c Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 13 Jan 2026 23:09:43 +0530 Subject: [PATCH 91/93] Apply suggestions from code review Making few editorial review comments Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 340c678428..e4f7724c07 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -636,7 +636,7 @@ Each active timer requires 800 bytes, plus the size of the passed context, which A 200-byte context results in 1 KB of storage per active timer. 100,000 active timers require 100 MB of additional bucket space. -As a best practice, keep this collection fully resident in-memory to make sure constant availability. +As a best practice, keep this collection fully resident in-memory to make sure you have constant availability. NOTE: All Eventing functions use this collection. @@ -667,6 +667,6 @@ Your cluster must be properly sized to be able to handle new XDCR streams. For example, XDCR needs 1-2 additional CPU cores per stream. In some cases, it also requires additional RAM and network resources. -If a cluster is not sized to handle `both` the existing workload `and` the new XDCR streams, the performance of both XDCR and the cluster overall may be negatively impacted. +If a cluster is not sized to handle both the existing workload and the new XDCR streams, the performance of both XDCR and the cluster overall might be negatively impacted. For information about preparing your cluster for replication, see xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR]. From 94221b846ad7b332bea0c6851ce6125bb485dc03 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Wed, 14 Jan 2026 00:32:57 +0530 Subject: [PATCH 92/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index e4f7724c07..2d3ab196c5 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -82,7 +82,7 @@ Some components that require RAM are: | 256 MB minimum; 2048 MB and above recommended | Query Service -| This service does not require any RAM allocation. +| The Query Service does not require a RAM allocation. | Eventing Service | 256 MB From 464fb7f542fb1cbced3162062ed20e156b33a3fd Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Fri, 16 Jan 2026 19:43:49 +0530 Subject: [PATCH 93/93] Update modules/install/pages/sizing-general.adoc Co-authored-by: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> --- modules/install/pages/sizing-general.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install/pages/sizing-general.adoc b/modules/install/pages/sizing-general.adoc index 2d3ab196c5..006e88ec30 100644 --- a/modules/install/pages/sizing-general.adoc +++ b/modules/install/pages/sizing-general.adoc @@ -42,7 +42,7 @@ For more information about the nature and resource demands of each Couchbase Ser This guide discusses four types of resources that you should consider when sizing a Couchbase Server cluster node: CPU:: -CPU specifies the number of cores and clock speed required to run your workload. +CPU controls the number of cores and the clock speed required to run your workload. RAM:: RAM is often the most crucial area to size.