diff --git a/antora.yml b/antora.yml index 648b5dc275..8c1c43470c 100644 --- a/antora.yml +++ b/antora.yml @@ -1,10 +1,10 @@ name: server -version: '8.0' +version: '8.1' asciidoc: attributes: ui-name: Server Web Console product-name: Server -# prerelease: Prerelease +prerelease: Prerelease title: Couchbase Server start_page: introduction:intro.adoc nav: diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index c6db029fd3..7edf06da92 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -61,6 +61,7 @@ include::third-party:partial$nav.adoc[] ** xref:learn:services-and-indexes/services/analytics-service.adoc[Analytics Service] ** xref:learn:services-and-indexes/services/eventing-service.adoc[Eventing Service] ** xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service] + *** xref:learn:services-and-indexes/services/continuous-backup.adoc[Continuous Backup & PITR] * xref:learn:clusters-and-availability/clusters-and-availability.adoc[Clusters and Availability] ** xref:learn:clusters-and-availability/cluster-manager.adoc[Cluster Manager] ** xref:learn:clusters-and-availability/metadata-management.adoc[Metadata Management] @@ -76,6 +77,7 @@ include::third-party:partial$nav.adoc[] **** xref:learn:clusters-and-availability/graceful-failover.adoc[Graceful] **** xref:learn:clusters-and-availability/hard-failover.adoc[Hard] **** xref:learn:clusters-and-availability/automatic-failover.adoc[Automatic] + *** xref:learn:clusters-and-availability/unstable-nodes.adoc[] *** xref:learn:clusters-and-availability/recovery.adoc[Recovery] *** xref:learn:clusters-and-availability/node-to-node-encryption.adoc[Node-to-Node Encryption] ** xref:learn:clusters-and-availability/replication-architecture.adoc[Availability] @@ -88,6 +90,7 @@ include::third-party:partial$nav.adoc[] **** xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc[XDCR Conflict Logging] ***** xref:learn:clusters-and-availability/xdcr-viewing-conflict-logs.adoc[Viewing Conflict Logs] **** xref:learn:clusters-and-availability/xdcr-active-active-sgw.adoc[XDCR Active-Active with Sync Gateway] + **** xref:xdcr-reference:xdcr-lowering-memory-footprint.adoc[] *** xref:learn:clusters-and-availability/groups.adoc[Server Group Awareness] * xref:learn:security/security-overview.adoc[Security] ** xref:learn:security/authentication.adoc[Authentication] @@ -183,9 +186,13 @@ include::third-party:partial$nav.adoc[] *** xref:backup-restore:cbbackupmgr-cloud.adoc[Cloud Backup] *** xref:backup-restore:cbbackupmgr-network-filesystems.adoc[Network Filesystems] *** xref:backup-restore:cbbackupmgr-encryption.adoc[Encryption] + ** xref:manage:manage-backup-and-restore/manage-continuous-backup.adoc[] + ** xref:manage:manage-backup-and-restore/monitor-continuous-backup.adoc[] + ** xref:manage:manage-backup-and-restore/manage-pitr.adoc[] * xref:manage:monitor/monitor-intro.adoc[Monitor] ** xref:manage:monitor/xdcr-monitor-timestamp-conflict-resolution.adoc[Monitor Clock Drift] - ** xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[Configure Prometheus to Collect Couchbase Metrics] + ** xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[] + ** xref:manage:monitor/monitor-node-stability.adoc[] * xref:manage:troubleshoot/troubleshoot.adoc[Troubleshoot] ** xref:manage:troubleshoot/common-errors.adoc[Common Errors] ** xref:manage:troubleshoot/core-files.adoc[Core Files] @@ -430,6 +437,7 @@ include::cli:partial$cbcli/nav.adoc[] *** xref:rest-api:rest-compact-post.adoc[Performing Compaction Manually] *** xref:rest-api:rest-autocompact-global.adoc[Auto-Compaction: Global] *** xref:rest-api:rest-autocompact-per-bucket.adoc[Auto-Compaction: Per Bucket] + *** xref:rest-api:rest-magma-compression-per-bucket.adoc[Magma Compression] ** xref:rest-api:rest-rza.adoc[Server Groups API] *** xref:rest-api:rest-servergroup-get.adoc[Getting Group Information] diff --git a/modules/install/pages/install-ports.adoc b/modules/install/pages/install-ports.adoc index c13a88f9bc..65d142d577 100644 --- a/modules/install/pages/install-ports.adoc +++ b/modules/install/pages/install-ports.adoc @@ -70,7 +70,7 @@ The following table lists all port numbers, grouped by category of communication | Communication Path | Default Ports | _Node-local only_ -| *Unencrypted*: 9119, 9998, 11213, 21200, 21300 +| *Unencrypted*: 9119, 9125, 9998, 11213, 21200, 21300 *Encrypted*: 21250 {fn-encrypted-traffic-port}, 21350 {fn-encrypted-communication-port} @@ -99,7 +99,7 @@ a| *Unencrypted*: 8091-8096, 9102, 11210 [NOTE] ==== `cbbackupmgr`, the backup client, connects to the Couchbase Server using the ports listed above. -You can find detailed information about the server ports in the xref:detailed-port-description[Detailed Port Description]. +You can find detailed information about the server ports in the <>. Below is a summary of the services cbbackupmgr is accessing via the ports. [horizontal] @@ -351,6 +351,14 @@ The following table contains a detailed description of each port used by Couchba | No | No +| `cbcontbk` +| 9125 +| Continuous backup +| No +| No +| No + + | `fts_grpc_port` / `fts_grpc_ssl_port` | 9130 / 19130 a| Search Service gRPC port used for xref:learn:services-and-indexes/services/search-service.adoc[scatter-gather] operations between FTS nodes diff --git a/modules/install/pages/server-processes.adoc b/modules/install/pages/server-processes.adoc index f477045a98..8f9f64c159 100644 --- a/modules/install/pages/server-processes.adoc +++ b/modules/install/pages/server-processes.adoc @@ -26,121 +26,126 @@ The following table lists the Couchbase processes that run on Linux platforms. | Process | Description | Service | Path +| `cbcontbk` +| The continuous backup agent. +| Backup +| `/opt/couchbase/bin` + | `cbft` | Couchbase Full-Text Search (FTS) service | Search -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `cbq-engine` | Couchbase Query service | Query -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `goport` (5 copies) | Process that acts as a bridge between `ns_server` (Erlang) and the other server components (`cbq- engine`, `cbft`, etc.) which are written in Go | Query -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `gosecrets` | Service that is used to encrypt the cluster configuration stored on disk | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `goxdcr` | Cross Data Center Replication (XDCR) - replicates data from one cluster to another | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `indexer` | Index service | Index -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `memcached` | Data service responsible for storing user data | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `godu` (2 copies) | Utility in Go to get disk usage stats | Data -| _/opt/couchbase/bin/priv/_ +| `/opt/couchbase/bin/priv/` | `projector` | Extracts secondary key from documents | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `saslauthd-port` | Erlang port process (wrapper) used to talk to the `saslauthd` daemon for authentication purposes | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `beam.smp` (3 copies) | Couchbase cluster manager run as Erlang virtual machines - `babysitter`, `ns_server`, and `ns_couchdb` | Data -| _/opt/couchbase/lib/erlang/erts-9.3.3.9/bin/_ +| `/opt/couchbase/lib/erlang/erts-9.3.3.9/bin/` | `epmd` | Erlang-specific process which acts as a name server for Erlang distribution | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `cpu_sup` (2 copies) | Erlang-specific process used to collect CPU: 1 for `ns_server` VM and 1 for `ns_couchdb` VM | Data -| _/opt/couchbase/lib/erlang/lib/os_mon-2.2.14/priv/bin/_ +| `/opt/couchbase/lib/erlang/lib/os_mon-2.2.14/priv/bin/` | `memsup` (2 copies) | Erlang-specific process used to collect memory usage: 1 for `ns_server` VM and 1 for `ns_couchdb` VM | Data -| _/opt/couchbase/lib/erlang/lib/os_mon-2.2.14/priv/bin/_ +| `/opt/couchbase/lib/erlang/lib/os_mon-2.2.14/priv/bin/` | `inet_gethost` (2 copies) | Built-in Erlang port process that is used to perform name service lookup | Data -| _/opt/couchbase/lib/erlang/erts-5.10.4.0.0.1/bin/_ +| `/opt/couchbase/lib/erlang/erts-5.10.4.0.0.1/bin/` | `portsigar` | Open source tool sigar that is used to collect system information | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `sh -s disksup` (2 copies) | Erlang-specific process that is used to supervise the available disk space: 1 for `ns_server` VM and 1 for `ns_couchdb` VM | Data -| _/opt/couchbase/lib/erlang/lib/os_mon-2.2.14/ebin/_ +| `/opt/couchbase/lib/erlang/lib/os_mon-2.2.14/ebin/` | `sh -s ns_disksup` | Wrapper for `disksup` which also collects information about mounted drives | Data -| _/opt/couchbase/lib/ns_server/erlang/lib/ns_server/ebin/_ +| `/opt/couchbase/lib/ns_server/erlang/lib/ns_server/ebin/` | `cbcollect_info` | Utility used to collect Couchbase server logs (will be seen only during log collection) | Data -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `eventing-producer` (1 copy) | Eventing supervisor service (one instance per node) | Eventing -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `eventing-consumer` (n copies) | Eventing worker (multiple instances per node). Instance count is configured in UI. | Eventing -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` | `java` (Analytics Driver) | JVM running the Analytics NC and CC | Analytics -| _/opt/couchbase/lib/cbas/runtime/bin_ +| `/opt/couchbase/lib/cbas/runtime/bin` | `cbas` | Go-wrapper that communicates with `ns_server` and manages the lifecycle of the Analytics Driver | Analytics -| _/opt/couchbase/bin/_ +| `/opt/couchbase/bin/` |=== == Windows @@ -156,112 +161,112 @@ The following table lists the Couchbase processes that run on the Windows platfo | `backup.exe` | Backup application for Couchbase data | Backup -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `cbas.exe` | Go-wrapper that communicates with `ns_server` and manages the lifecycle of the Analytics Driver | Analytics -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `cbcollect_info.exe` | Utility used to collect Couchbase server logs (will be seen only during log collection) | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `cbft.exe` | Couchbase Full-Text Search (FTS) service | Search -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `cbq-engine.exe` | Couchbase Query service | Query -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `epmd.exe` | Erlang-specific process which acts as a name server for Erlang distribution | Data -| _C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin_ +| `C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin` | `erl.exe` | Erlang process used by the name server. | Data -| _C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin_ +| `C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin` | `erlsrv.exe` | Used to start the Erlang emulator as a Windows process. | Data -| _C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin_ +| `C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin` | `eventing-consumer.exe` | Eventing worker (multiple instances per node). Instance count is configured in UI. | Eventing -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `eventing-producer.exe` | Eventing supervisor service (one instance per node) | Eventing -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `goport.exe` | Process that acts as a bridge between `ns_server` (Erlang) and the other server components (`cbq- engine.exe`, `cbft.exe`, etc.) | Query -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `gosecrets.exe` | Service that is used to encrypt the cluster configuration stored on disk | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `goxdcr.exe` | Cross Data Center Replication (XDCR) - replicates data from one cluster to another | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `indexer.exe` | Index service | Index -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `godu.exe` | Utility in Go to get disk usage stats | Data -| _C:\Program Files\Couchbase\Server\bin\priv_ +| `C:\Program Files\Couchbase\Server\bin\priv` | `inet_gethost.exe` | Built-in Erlang port process that is used to perform name service lookup | Data -| _C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin_ +| `C:\Program Files\Couchbase\Server\erts-x.x.x.x\bin` | `java.exe` (Analytics Driver) | JVM running the Analytics NC and CC | Analytics -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `memcached.exe` | Data service responsible for storing user data | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `projector.exe` | Extracts secondary key from documents | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `prometheus.exe` | Engine used Couchbase for creating metrics. | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `saslauthd-port.exe` | Erlang port process (wrapper) used to talk to the `saslauthd` daemon for authentication purposes | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` | `sigar_port.exe` | Open source tool sigar that is used to collect system information | Data -| _C:\Program Files\Couchbase\Server\bin_ +| `C:\Program Files\Couchbase\Server\bin` |=== diff --git a/modules/introduction/pages/editions.adoc b/modules/introduction/pages/editions.adoc index 9fc4b1485f..89f4d7e0b8 100644 --- a/modules/introduction/pages/editions.adoc +++ b/modules/introduction/pages/editions.adoc @@ -1,40 +1,70 @@ = Couchbase Server Editions :description: Couchbase Server is available in two editions: Enterprise and Community. +:phone-home: footnote:[Usage information is only sent when you use the Admin GUI. \ +No usage information is sent when you use the command line utilities to administer your cluster.] + [abstract] {description} Each edition offers different features and levels of support. -== Enterprise Edition +== Couchbase Server Enterprise Edition + +The Enterprise Edition (EE) represents the latest, most stable, production-ready release of Couchbase Server. +Couchbase recommends the Enterprise Edition binaries for commercial production systems running Couchbase Server. +The Enterprise Edition contains some unique features that make it the best fit for production deployments running in data centers or public cloud infrastructure. + +A subscription to the Enterprise Edition includes: -The Enterprise Edition (EE) represents the latest, most stable, production-ready release of Couchbase Server. We recommend the Enterprise Edition binaries for commercial production systems running Couchbase Server. The Enterprise Edition contains some unique features that make it the best fit for production deployments running in data centers or public cloud infrastructure. +* a commercial license +* better availability capabilities +* enhanced security features +* advanced tooling +* and higher performance and scale. -A subscription to the Enterprise Edition includes a commercial license, better availability capabilities, enhanced security features, advanced tooling, and higher performance and scale. It also includes technical support with service level commitments via our 24/7 support organization and hot fixes for releases. +It also includes technical support with service level commitments via our 24/7-support organization and hot fixes for releases. -Refer to the https://www.couchbase.com/pricing[pricing^] page for details on Couchbase's Enterprise Edition. +For more information, see the https://www.couchbase.com/pricing[pricing^] page for details on Couchbase's Enterprise Edition. -== Community Edition +== Couchbase Server Community Edition The Community Edition (CE) is best for noncommercial developers where basic availability, performance, scale, tooling, security capabilities and community support is sufficient. -One important principle for Community Edition and Enterprise Edition is to ensure full portability of applications between the two editions. The capabilities ensure that an application running on Enterprise Edition should transition to Community Edition without code changes and vice versa. +One important principle for Community Edition and Enterprise Edition is to ensure full portability of applications between the 2 editions. +The capabilities ensure that an application running on Enterprise Edition should transition to Community Edition without code changes and vice versa. + +The Community Edition license provides the free deployment of Couchbase Community Edition for departmental-scale deployments of up to 5 node clusters. + +The Community Edition license has been updated to disallow the use of cross-datacenter replication (XDCR), +which is now an exclusive Enterprise Edition feature. -The Community Edition license provides the free deployment of Couchbase Community Edition for departmental-scale deployments of up to five node clusters. The Community Edition license has recently been updated to disallow the use of Cross Data Center Replication -(XDCR), which is now an exclusive Enterprise Edition feature. -The Community Edition is not subjected to the iterative "test, fix, and verify" quality assurance cycle that is an integral part of the Enterprise Edition release process. The Community Edition does not include the latest bug fixes. +[NOTE] +.Replicating from a CE server to an EE server +==== +You can still replicate data from a CE server as long as the data is being replicated to an EE installation running XDCR. +==== + +Multi-Dimensional Scaling (MDS) is not supported on the Community Edition. + +The Community Edition is not subjected to the iterative `test`, `fix`, and `verify` quality assurance cycle that's an integral part of the Enterprise Edition release process. + +The Community Edition does not include the latest bug fixes. The Community Edition comes with limited concurrency and parallelism and supports a maximum of 4 cores per node. +The Community Edition shares usage information with Couchbase{empty}{phone-home} and notifies you when updates are available. + Documentation, mailing lists, and forums support the Couchbase user community to help troubleshoot issues and answer questions. == Open Source Project -The Couchbase Server open source project is a platform for innovation. Couchbase is committed to open source development, and the open source project continues to serve as the foundation for both the Community Edition and the Enterprise Edition. +The Couchbase Server open source project is a platform for innovation. +Couchbase is committed to open source development, and the open source project continues to serve as the foundation for both the Community Edition and the Enterprise Edition. -There are many ways to contribute to the open source project: +To contribute to the open source project, you can: -* Contribute code to our core engine, our SDKs, connectors and other integration components that help us connect to other products through https://github.com/couchbase[github.com/couchbase^]. Find more details on the https://developer.couchbase.com/open-source-projects/[Open Source Projects^] page. -* Report issues on our tracking system: https://issues.couchbase.com/projects/MB?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page[JIRA^]. -* xref:home:contribute:index.adoc[Contribute to the documentation] either by submitting changes on GitHub or by simply clicking the "Feedback" link in our online documentation. +* Contribute code to Couchbase's core engine, SDKs, connectors, and other integration components that help to connect to other products through https://github.com/couchbase[github.com/couchbase^]. Find more details on the https://developer.couchbase.com/open-source-projects/[Open Source Projects^] page. +* Report issues on the Couch tracking system: https://issues.couchbase.com/projects/MB?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page[JIRA^]. +* xref:home:contribute:index.adoc[Contribute to the documentation] either by submitting changes on GitHub or by clicking the "Feedback" link in the xref:intro.adoc[Couchbase online documentation]. -For a feature by feature comparison between editions, take a look at https://www.couchbase.com/products/editions[^]. +For a feature-by-feature comparison between editions, take a look at https://www.couchbase.com/products/editions[^]. diff --git a/modules/introduction/pages/whats-new.adoc b/modules/introduction/pages/whats-new.adoc index 6cf16bca18..817883fe6a 100644 --- a/modules/introduction/pages/whats-new.adoc +++ b/modules/introduction/pages/whats-new.adoc @@ -1,18 +1,18 @@ -= What's New in Version 8.0 += What's New in Version 8.1 :description: Couchbase is the modern database for enterprise applications. :page-aliases: security:security-watsnew :page-toclevels: 2 [abstract] {description} + -Couchbase Server 8.0 combines the strengths of relational databases with the flexibility, performance, and scale of Couchbase. +Couchbase Server 8.1 combines the strengths of relational databases with the flexibility, performance, and scale of Couchbase. For information about platform support changes, deprecation notifications, and fixed and known issues, see the xref:release-notes:relnotes.adoc[Release Notes]. -[#new-features-80] -== New Features and Enhancements in 8.0.0 +[#new-features-81] +== New Features and Enhancements in 8.1.0 This release introduces the following new features. -include::partial$new-features-80.adoc[] +include::partial$new-features-81.adoc[] diff --git a/modules/introduction/partials/new-features-80.adoc b/modules/introduction/partials/new-features-80.adoc deleted file mode 100644 index e3b36b2aea..0000000000 --- a/modules/introduction/partials/new-features-80.adoc +++ /dev/null @@ -1,515 +0,0 @@ -[#section-new-feature-800-platform-support] -=== Platform Support - -Couchbase Server 8.0 adds support for the following operating systems: - -* Alma Linux 10 -* Debian Linux 13 -* macOS 15 "Sequoia" (for development and testing only) -* Oracle Linux 10 -* RHEL 10 -* Rocky Linux 10 -* Windows Server 2025 - -Couchbase Server 8.0 no longer supports the following operating systems: - -* Amazon Linux 2 -* macOS 12 "Monterey" -* SUSE Linux Enterprise Server (SLES) 12 -* Ubuntu 20.04 LTS -* Windows 10 -* Windows Server 2019 - -For more information about supported operating systems, see xref:install:install-platforms.adoc[]. - -=== Global Secondary Indexing (GSI) Vector Indexes - -Couchbase Server 8.0 introduces Hyperscale Vector indexes and Composite Vector indexes, alongside the previously available Search Vector indexes. -Hyperscale Vector indexes and Composite Vector indexes are stored using the Index Service. -They enable you to perform vector searches in support of AI applications and other uses. - -* Hyperscale Vector indexes contain a single vector column. -They excel at indexing huge datasets that can scale into the billions of documents. -Use this type of index when you want to primarily query vector values with a low memory footprint. - -* Composite Vector indexes contain a single vector column and 1 or more scalar columns. -They apply scalar filters before performing a vector similarity search. -This is ideal for workflows where you want to exclude large portions of the dataset to reduce the number of vectors that the vector search has to compare. - -* Use Search Vector indexes when you need to perform hybrid searches that combine vector searches with other Search Service features, such as text or geospatial search. - -For more information, see xref:vector-index:vectors-and-indexes-overview.adoc[Use Vector Indexes for AI Applications]. - -=== Data Service Changes - -Couchbase Server 8.0 introduces several new features for the Data Service. - -[#whats-new-magma-vbuckets] -==== Magma with 128 vBuckets is the New Default Storage Engine - -If you do not specify a storage engine for a new Couchbase bucket, Couchbase Server Enterprise Edition 8.0 uses Magma with 128 vBuckets as the storage engine. -This new storage engine option has a minimum memory quota requirement of 100MiB compared to the original 1024 vBucket Magma bucket's requirement of 1GiB. -See xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines] for more information about storage engines. - -IMPORTANT: This is a default behavior change. - -The new default storage backend for buckets is a behavior change that may cause issues if you rely on the previous behavior. -Before upgrading, determine if your deployment scripts rely on the previous behavior. -See xref:install:upgrade.adoc#before-you-upgrade[Before You Upgrade] for potential compatibility issues compared with the previous behavior. - -==== Native Encryption at Rest - -Couchbase Server Enterprise Edition can now natively encrypt bucket, log, audit, and configuration data when writing it to disk. - -This feature: - -* Can help reduce the chances of or severity of data breaches. -* Is transparent to the database users. -Couchbase Server automatically decrypts data when reading it from disk and encrypts it when writing to disk. -* Supports using third-party key management services such as Amazon's Key Management Service and those compliant with Key Management Interoperability Protocol. - -For more information about native encryption at rest, see xref:learn:security/native-encryption-at-rest-overview.adoc[Native Encryption at Rest]. - -==== Prevent Data Service From Filling Filesystem - -You can configure the Data Service to stop writing to the data service path once the filesystem has filled to a configurable threshold. -This limit can help avoid problems during recovery caused by a full filesystem. -If the filesystem fills to the limit you set, Couchbase Server stops writing to the data storage path and returns an error instead. -This limit is off by default. -For more information, see xref:learn:buckets-memory-and-storage/storage-settings.adoc#filesystem-free-space-and-usage-limits[Filesystem Free Space and Usage Limits]. - -==== Optionally Maintain Durable Write Availability After Losing Majority Due to Failover - -You can enable a cluster-level option that allows durable writes to succeed even when they cannot meet their majority requirements. -Use this setting to allow durable writes to succeed when nodes are unavailable due to failovers. -For example, you can enable this option to prevent durable writes failing to a bucket with a single replica during an upgrade that uses the graceful failover followed by a delta recovery method. - -[WARNING] -.Potential Data Loss -==== -Enabling this feature degrades the guarantee that durable writes offer: that Couchbase Server has persisted the data in a way that should survive node failure. -This setting makes durable writes during a failover no more safe from data loss as an asynchronous write. -It also means transactions do not provide the same guarantees when this feature is off. -Use this setting only in special cases such as when you're performing a graceful failover and you still want durable writes to succeed. -Always turn off this setting as soon as possible. -==== - -See xref:learn:clusters-and-availability/automatic-failover.adoc#auto-failover-and-ephemeral-buckets[Auto-Failover and Ephemeral Buckets] for more information about this feature. - -==== Configurable Warmup Behavior (Background Warmup) - -The new Warmup behavior setting, configured using `warmupBehavior` in the REST API, -controls when a persistent bucket becomes fully available for `read` and `write` operations after a bucket restart. - -This setting replaces multiple warmup threshold parameters with a single configuration point: - -* *background (default):* The bucket becomes fully available as soon as required metadata is loaded from storage. -The bucket's cache is then filled in the background until memory usage reaches the low watermark (`memoryLowWatermark`). - -* *blocking:* This is the original behavior. -The bucket becomes read-available as soon as required metadata is loaded from storage, -then continues filling the cache until memory usage reaches the low watermark (`memoryLowWatermark`). -The bucket becomes fully available only after this point. - -* *none:* Disables warmup. -The bucket becomes fully available as soon as required metadata is loaded from storage. -The cache remains empty. - -For more information, see xref:learn:buckets-memory-and-storage/memory.adoc#initialization-and-warmup[Initialization and Warmup]. - -==== API Changes for Warmup Behavior - -The REST API now includes the per-bucket setting `warmupBehavior`. -The previous advanced tuning settings `warmup_min_items_threshold` and `warmup_min_memory_threshold` have been removed from the `cbepctl` interface. -The same changes in the warmup behavior settings are applicable to the Couchbase Cluster. -For the REST API information, see xref:rest-api:rest-bucket-create.adoc#warmupbehavior[warmupBehavior]. - -==== Other Data Service Features - -* Memcached buckets have been removed. -If your cluster contains Memcached buckets, you must remove them and replace them with ephemeral buckets before you can upgrade to Couchbase Server 8.0. - -* You can now change the eviction policy of a Couchbase bucket without the bucket restarting. -To do this, you must use the REST API, and you must take additional steps for the new setting to take effect. -See xref:manage:manage-buckets/change-ejection-policy.adoc[] for more information. - -* You can now change the eviction policy of an ephemeral bucket. The new setting takes effect immediately, unlike Couchstore buckets. -See xref:manage:manage-buckets/change-ejection-policy.adoc[] for more information. - -* Previously, Couchbase Server would refuse to automatically failover a node if it had an ephemeral bucket without replicas. -You can now configure Couchbase Server to allow these automatic failovers. -When these failovers happen, Couchbase Server creates a new empty ephemeral bucket on another node to take the place of the bucket on the failed node. -See xref:learn:clusters-and-availability/automatic-failover.adoc#auto-failover-and-ephemeral-buckets[Auto-Failover and Ephemeral Buckets]. - -=== Non-Data Services - -Couchbase Server 8.0 release has key non-Data Services enhancements. - -==== Dynamically Add or Remove Non-Data Services on Existing Nodes - -Now you can add or remove non-Data Services dynamically on existing nodes in a cluster, without adding or removing nodes. -After you add or remove non-Data Services, the rebalancing operation is automatically triggered to distribute service workloads and complete the modification. - -You can modify these services using the Couchbase xref:manage:manage-nodes/modify-services-and-rebalance.adoc#modify-mds-services-from-ui[UI], xref:rest-api:rest-set-up-services-existing-nodes.adoc[REST API], or xref:manage:manage-nodes/modify-services-and-rebalance.adoc#modify-mds-services-using-cli[CLI]. -The following services can be modified: - -* `index` (Index Service) -* `n1ql` (Query Service) -* `fts` (Search Service) -* `cbas` (Analytics Service) -* `eventing` (Eventing Service) -* `backup` (Backup Service) - -==== Backup Service: Support for Retention Periods for Repositories and Pruning of Old Backups - -Backup Service now supports configurable retention periods for repositories and pruning of old backups from the UI and through the REST API. - -* Configurable Retention Periods for Repositories: -+ -You can configure default or custom retention periods to automatically manage backup lifecycles in a repository. -The Backup Service uses the retention period to determine when to delete backups that have exceeded their defined lifespan. -When a backup reaches the end of its retention period, the Backup Service automatically deletes it through scheduled Prune tasks. - -* Pruning of Old Backups: -+ -Pruning is the process of deleting backups that have reached their retention period, to optimize repository storage and maintain efficiency. -The Backup Service automatically removes only those backups, where the repository has reached its retention period and no incremental backups are dependent on this backup. -You can perform pruning by scheduling it or by manually triggering a prune task on-demand. - -For more information, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#backup-retention[Retain Backups] and xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#schedule-backup-pruning[Schedule Pruning]. - -==== Backup Service: Customize the Deletion of Backups - -Incremental backups now keep track of the backups they depend on. -You cannot delete a backup if another incremental backup needs it, which is a default function. -However, you can choose to override this protection from the UI and REST API. -You can either schedule an automatic deletion of backups using the pruning function or delete manually. - -For more information, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#delete-backups[Delete Backups]. - -=== Couchbase Cluster - -==== Added New Data Services Settings Through Bucket REST API - -The following new settings for Data Services are added and made accessible through the Bucket REST API - -`/pools/default/buckets`: - -[cols="1,1,1,1", options="header"] -|=== -|Argument Name |Type |Valid values |Default - -|`accessScannerEnabled` -|bool -|true, false -|true - -|`expiryPagerSleepTime` -|int -|0 to maxInt -|600 - -|`warmupBehavior` -|string -|background, blocking, none -|background - -|`memoryLowWatermark` -|int -|50 to 89 -|75 - -|`memoryHighWatermark` -|int -|51 to 90 -|85 -|=== - -The settings `warmup_min_items_threshold`, `warmup_min_memory_threshold`, `exp_pager_stime`, `mem_high_wat`, and `mem_low_wat` are removed from `cbepctl`. - -The new settings allow administrators to fine-tune bucket behavior and memory management directly through the REST API, eliminating the need to use `cbepctl` for these configurations. - -For more information, see xref:rest-api:rest-bucket-create.adoc[Creating and Editing Buckets] and xref:learn:buckets-memory-and-storage/memory.adoc[Memory]. - -=== XDCR - -Couchbase Server 8.0 release has key cross datacenter replication (XDCR) enhancements and diagnostic capabilities. -These updates improve visibility and operational control in replication topologies. - -==== XDCR Conflict Logging Feature - -XDCR detects and logs concurrent conflicts that occur in different clusters around the same time but on the same document version due to independent modifications by locally connected applications during Active-Active replication. - -When conflict logging is enabled, XDCR records detailed information into a designated conflict log collection about each conflict event through 3 documents; the 2 conflicting documents and the conflict event message. -These 3 documents are not replicated to other clusters. -The conflict logs are for your information only. - -For more information, see xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc[XDCR Conflict Logging Feature]. - -==== Identifying Incoming Replications in an XDCR Topology - -XDCR now supports the identification of incoming replications on a cluster, providing administrators with improved visibility and management of cross-cluster data flows. -This enhancement allows you to view and distinguish replication streams that originate from remote clusters and are targeting the local cluster. -The feature helps maintain replication transparency by showing which clusters are sending data in, how those streams are configured, and their current operational status, all from the UI or REST API. - -For more information, see xref:manage:manage-xdcr/incoming-xdcr-replications.adoc[Incoming Replications] and xref:rest-api:rest-xdcr-list-incoming-replications.adoc[Listing Incoming Replications]. - -==== xdcrDiffer Diagnostic Utility - -The xdcrDiffer diagnostic utility is a command-line tool that helps administrators compare document data between source and target clusters participating in XDCR. -It identifies differences in document content, metadata, or presence across clusters to verify replication accuracy and consistency. -This utility is included in the Server installation package for convenient access. -In the earlier Couchbase Server versions, you'd build this utility from source using the xdcrDiffer GitHub repository. - -For more information, see xref:manage:manage-xdcr/xdcr-differ.adoc[xdcrDiffer Utility]. - -==== Added the Generic Services Log Level configuration in XDCR through REST API - -XDCR supports the new Generic Services Log Level configuration using the REST API through the `genericServicesLogLevel` settings. -Each key represents a service name, and its value specifies the log level. -For more information, see xref:rest-api:rest-xdcr-adv-settings.adoc[XDCR Advanced Settings]. - -=== Security and Authentication - -Couchbase Server 8.0 release has key security and authentication enhancements. - -==== Hybrid Authentication Mode -Couchbase Server now supports the Hybrid authentication mode in the certificate-based client authentication. - -When `Hybrid` is selected: - -* Clients can authenticate using either certificates or username/password credentials. -* All nodes must use mutual TLS (mTLS) for inter-node communication. -* The prerequisite is that the property `clusterEncryptionLevel` be set to `all` or `strict`. - -This mode enhances flexibility for clients while enforcing strict security for node-to-node communication. - -For more information, see xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client Certificate Handling]. - -==== Simultaneous Support for Certificate-Based Client Authentication and Node-To-Node Encryption - -Couchbase Server now supports simultaneous certificate-based client authentication and node-to-node encryption when the Mandatory option is selected. -This configuration enforces the use of mutual TLS (mTLS) for all communications between clients and cluster nodes, ensuring that both entities are authenticated using X.509 certificates. -In this mode, clients must present valid certificates to connect, and all internal cluster traffic is encrypted. -This dual enforcement strengthens security by preventing unauthorized access, protecting data in transit, and maintaining end-to-end encryption across all communication paths. - -For more information, see xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client Certificate Handling]. - -==== Locking and Unlocking Local User Accounts - -You can lock user accounts in Couchbase Server to prevent them from authenticating or maintaining prolonged active sessions. -When an account is locked, all active UI sessions and long-running connections, such as Memcached or streaming connections, are immediately terminated. -This feature is useful during maintenance operations or when you need to temporarily restrict user access without deleting the account. -The account lock feature applies only to local domain user accounts and is available in the Enterprise Edition starting with Couchbase Server version 8.0 and later. - -For more information, see xref:learn:security/authentication-overview.adoc#blocking-user-authentication[Blocking User Authentication]. - -==== Forcing Password Change - -As an administrator, you can require a local domain user to change their password the next time they log in to Couchbase Server. -This option is typically used when issuing a temporary or reset password to ensure that the user sets a new, private password upon their next authentication. -When this setting is enabled, the user cannot access other features or perform operations until they successfully update their password. - -For more information, see xref:learn:security/usernames-and-passwords.adoc#force-password-change[Force Password Change]. - -==== Auditing User Activity - -You can track user activity in Couchbase Server to view the last time a user made a request to the Cluster Manager. -This capability, available through user auditing, helps administrators identify inactive or unused accounts that may need to be reviewed or removed. -Administrators can monitor account activity patterns, and improve overall system visibility and security. -This feature applies only to local domain users, as externally authenticated users, such as those managed through LDAP or external identity providers, cannot be tracked using this mechanism. - -For more information, see xref:learn:security/auditing.adoc#audit-user-activity[Audit User Activity]. - -=== Query Service - -Couchbase Server 8.0 release has key Query Service features. - -==== New {sqlpp} Statements for Vector Indexes - -The {sqlpp} query language contains new statements and keywords to create, alter, and drop Hyperscale Vector indexes and Composite Vector indexes. -You can specify the number of dimensions in the vector, the distance metric to use when comparing vectors, and the settings for quantization and index algorithms. -For more information, see xref:n1ql:n1ql-language-reference/createvectorindex.adoc[CREATE VECTOR INDEX] and xref:n1ql:n1ql-language-reference/createindex.adoc[CREATE INDEX]. - -==== Other New Data Definition Language Statements - -In addition, {sqlpp} now supports the following new statements to improve user, group, and bucket management: - -* `CREATE USER` -* `ALTER USER` -* `DROP USER` -* `CREATE GROUP` -* `ALTER GROUP` -* `DROP GROUP` -* `CREATE BUCKET` -* `ALTER BUCKET` -* `DROP BUCKET` - -For more information, see xref:n1ql:n1ql-language-reference/statements.adoc[SQL++ Statements]. - -==== New {sqlpp} Functions for Vector Comparisons - -The {sqlpp} query language contains new functions to work with vector values. - -These include: - -* The similarity functions `APPROX_VECTOR_DISTANCE` and `VECTOR_DISTANCE` to find the distance between two vectors. The `APPROX_VECTOR_DISTANCE` function selects a suitable Hyperscale Vector index or Composite Vector index to use with the query, if one is available. - -* The `ISVECTOR` function, which checks for a vector value. - -* The `DECODE_VECTOR`, `ENCODE_VECTOR`, and `NORMALIZE_VECTOR` functions, which modify vector values. - -For more information, see xref:n1ql:n1ql-language-reference/vectorfun.adoc[Vector Functions]. - - -==== Other New {sqlpp} Functions - -In addition to the new vector functions, the following {sqlpp} functions are new in Couchbase Server 8.0. - -* `EVALUATE()`: Executes a {sqlpp} statement provided as a string. -For more information, see xref:n1ql:n1ql-language-reference/metafun.adoc#evaluate[EVALUATE]. - -* `COMPRESS()`: Compresses a string using zlib compression and encodes the compressed data into base64 format. -For more information, see xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-compress[COMPRESS]. - -* `UNCOMPRESS()`: Takes a base64 encoded, compressed string as input and returns the original uncompressed string. -For more information, see xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-uncompress[UNCOMPRESS]. - - -==== Automatic Workload Repository - -Automatic Workload Repository (AWR) is a new feature that automatically captures and maintains performance statistics for queries executed on a Couchbase cluster. -It acts as a centralized repository for query performance data, enabling you to track query activity, analyze workload trends, and identify performance bottlenecks. -It also enables you to generate reports to compare query performance over time and optimize your queries based on historical data. - -For more information, see xref:n1ql:n1ql-manage/query-awr.adoc[Automatic Workload Repository]. - -==== Generate {sqlpp} Queries from Natural Language Requests - -{sqlpp} now supports a new `USING AI` statement that leverages AI capabilities to generate {sqlpp} queries from natural language requests. -For example, you can input prompts such as `How many airlines are based in Europe` or `List the names of all hotels in the same city as an airport`, and generate the corresponding {sqlpp} query. - -For more information, see xref:n1ql:n1ql-language-reference/using-ai.adoc[USING AI]. - -==== Auto Update Statistics - -Couchbase Server Enterprise Edition now supports a new Auto Update Statistics feature that keeps the optimizer statistics up to date by automatically identifying and refreshing outdated statistics. This ensures that the Cost-Based Optimizer always has the latest statistics for generating efficient query plans. - -For more information, see xref:n1ql:n1ql-language-reference/auto-update-statistics.adoc[Auto Update Statistics]. - -==== Optimizer Hints for DML Statements and Negative Optimizer Hints - -Couchbase Server 8.0 now supports optimizer hints with the `DELETE`, `UPDATE`, and `MERGE` statements. - -For more information, see xref:n1ql:n1ql-language-reference/optimizer-hints.adoc[Optimizer Hints]. - -In addition, you can now use negative keyspace hints, allowing you to instruct the optimizer not to use certain indexes or join methods. -The supported hints are `NO_INDEX`, `NO_INDEX_FTS`, `NO_USE_NL`, and `NO_USE_HASH`. - -For more information, see xref:n1ql:n1ql-language-reference/negative-keyspace-hints.adoc[Negative Keyspace Hints]. - -==== New System Catalogs - -8.0 introduces 2 new system keyspaces for group and bucket management: - -* `system:group_info`: Provides information about all groups on the cluster. -* `system:bucket_info`: Provides information about all buckets on the cluster. - -For more information, see xref:n1ql:n1ql-intro/sysinfo.adoc[Get System Information]. - -==== Extended Attributes (XATTR) Support in {sqlpp} - -You can now modify extended attributes (XATTRs) of documents directly through {sqlpp} statements such as `INSERT`, `UPSERT`, and `UPDATE`. -You can include up to 15 XATTRs per query. - -For more information, see xref:n1ql:n1ql-language-reference/insert.adoc[INSERT], xref:n1ql:n1ql-language-reference/upsert.adoc[UPSERT], and xref:n1ql:n1ql-language-reference/update.adoc[UPDATE] statements. - -==== Auto-Reprepare Feature for Prepared Statements - -Couchbase Server 8.0 now includes an auto-reprepare feature for PREPARE statements. -When enabled, a prepared statement automatically updates its query plan whenever GSI metadata version changes, ensuring it always uses newer, more efficient indexes as they become available. - -For more information, see xref:n1ql:n1ql-language-reference/prepare.adoc[PREPARE]. - -==== Enhanced Logging for Completed Requests - -You can now log query requests using 2 new qualifiers, `statement` and `plan`. -This allows for logging based on the query text or specific values within the query plan. - -For more information, see xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-completed-config[Completed Requests]. - -==== Additional Options for the INFER Statement - -The INFER statement now supports the following options: array_sample_size, max_nesting_depth, and flags. - -In addition, this statement also now automatically returns the meta.id() attribute, which provides the document keys in the output. - -For more information, see xref:n1ql:n1ql-language-reference/infer.adoc[INFER]. - -=== Search Service - -Couchbase Server 8.0 introduces several new features for the xref:search:search.adoc[Search Service]. - -==== Partition Selection for Queries - -Use the partition_selection property in a Search request to choose how the Search Service chooses the specific partitions to search for a query. - -For more information, see xref:search:search-request-params.adoc#partition_selection[partition_selection]. - -==== Synonym Searches - -Add a synonym collection and synonym documents to add synonym search support to a Search index. -Use synonyms to return matches for words that share the same meaning as the term in your Search query, instead of exact matches. - -For more information, see xref:search:synonyms/synonyms-search.adoc[] or xref:search:synonyms/synonyms-search-quick.adoc[]. - -==== Custom Document Filters -Instead of the xref:search:customize-index.adoc#type-identifiers[default type identifiers], you can now create xref:search:set-type-identifier.adoc#custom[custom document filters] to control the documents added to your Search index from a type mapping. - -For more information about how to configure type identifiers or create a custom document filter, see xref:search:set-type-identifier.adoc[]. - -==== New Search Index Algorithm - -Couchbase Server version 8.0 now supports the BM25 algorithm for scoring search results. -The `BM25` algorithm supports better hybrid searches and richer result rankings, as well as more stable result ordering across Search index partitions. - -You can now choose to use tf-idf or bm25 from your xref:search:set-advanced-settings.adoc#scoring_model[Search index settings]. - -For more information about how bm25 scoring works, see xref:search:run-searches.adoc#scoring[Scoring for Search Queries]. - -=== Eventing - -Couchbase Server 8.0 release has key Eventing enhancements. - -==== OnDeploy Handler - -This feature introduces a new handler OnDeploy in the Eventing function's app code. -The OnDeploy handler runs once when an Eventing function is deployed or resumed, before any mutations are processed. -It supports the same JavaScript capabilities as the OnUpdate and OnDelete handlers. -Use OnDeploy for one-time setup tasks such as registering a Timer or initializing resources required by the Eventing function. - -For more information, see xref:eventing:eventing-language-constructs.adoc#ondeploy_handler[Eventing onDeploy handler]. - -==== Scope-Level Configuration Updates - -Configurations can now be defined at the bucket, or scope level. -Customers can set options like `enable_curl` or `enable_debugger` at the bucket or scope level. - -For more information, see xref:eventing-rest-api:index.adoc#UnivConfig[Eventing REST API]. - -==== Node Configuration for Eventing Functions - -Customers can configure the number of nodes on which an eventing function within a function scope executes, using the `num_nodes_running` setting. -By default, all functions run on all nodes. -If `num_nodes_running` is set, the system will attempt to run the function on the specified number of nodes. -If fewer nodes are available, the function will run on all available nodes. -This can be set at function scope config level. - -For more information, see xref:eventing-rest-api:index.adoc#UnivConfig[Eventing REST API]. - -==== Set timeout for cURL - -Users can now set a timeout for each request in the curl function call. -Specify the curl timeout value in seconds, which takes precedence over the script timeout. - -For more information, see xref:eventing-rest-api:index.adoc#UnivConfig[Eventing REST API]. diff --git a/modules/introduction/partials/new-features-81.adoc b/modules/introduction/partials/new-features-81.adoc new file mode 100644 index 0000000000..1141494f4b --- /dev/null +++ b/modules/introduction/partials/new-features-81.adoc @@ -0,0 +1,73 @@ +[#section-new-feature-810-platform-support] +=== Platform Support + +Couchbase Server 8.1 adds support for the following operating systems: + +* TBD + +For more information about supported operating systems, see xref:install:install-platforms.adoc[]. + +=== Global Secondary Indexing (GSI) Vector Indexes + +TBD + +=== Data Service Changes + +Couchbase Server 8.1 introduces several new features for the Data Service. + +TBD + + +=== Non-Data Services + +Couchbase Server 8.1 release has key non-Data Services enhancements. + + +=== Couchbase Cluster + +Couchbase Server 8.1 release has added cluster enhancements and diagnostic capabilities. + +[#unstable-metric] +==== New Metric to Detect Unstable Nodes + +Couchbase Server 8.1.0 introduces a new metric, `cm_node_unreachable_total`, to help you monitor for unstable nodes in your cluster. +An unstable node periodically becomes unavailable but recovers before the auto failover timeout expires. +This metric counts the number of times a node has been unable to reach another node in the cluster. +By monitoring it, you can identify nodes that are having issues before they become unavailable for long enough to be automatically failed over. + +See xref:learn:clusters-and-availability/unstable-nodes.adoc[] for more information about using this metric to identify unstable nodes. + +=== XDCR + +Couchbase Server 8.1 release has key cross datacenter replication (XDCR) enhancements and diagnostic capabilities. + +TBD. + +=== Security and Authentication + +Couchbase Server 8.1 release has key security and authentication enhancements. + +TBD. + +=== Query Service + +Couchbase Server 8.1 release adds these Query Service features. + + +TBD. + +=== Search Service + +Couchbase Server 8.1 introduces several new features for the xref:search:search.adoc[Search Service]. + +TBD. + +=== Backup Service + +Couchbase Server 8.1 introduces several new features for the xref:backup:backup.adoc[Backup Service]. + +* The new continuous backup feature supplements traditional periodic backups by frequently backing up changes to Magma buckets. +This backup can limit the loss of data updates that occur between full and incremental backups. +In addition to backup up data, it also backs up timestamps of when the data was updated. +These timestamps let you perform Point-In-Time Recovery (PITR) to restore the Magma bucket's data to the state it was in at a specific moment. +See xref:learn:services-and-indexes/services/continuous-backup.adoc[] for more information. diff --git a/modules/learn/assets/images/clusters-and-availability/unstable-node-metric-timeseries.png b/modules/learn/assets/images/clusters-and-availability/unstable-node-metric-timeseries.png new file mode 100644 index 0000000000..4bd0d40b2c Binary files /dev/null and b/modules/learn/assets/images/clusters-and-availability/unstable-node-metric-timeseries.png differ diff --git a/modules/learn/assets/images/clusters-and-availability/unstable-node-prometheus_chart.png b/modules/learn/assets/images/clusters-and-availability/unstable-node-prometheus_chart.png new file mode 100644 index 0000000000..cbf88f940c Binary files /dev/null and b/modules/learn/assets/images/clusters-and-availability/unstable-node-prometheus_chart.png differ diff --git a/modules/learn/pages/clusters-and-availability/failover.adoc b/modules/learn/pages/clusters-and-availability/failover.adoc index dcc3210c18..ff197198cc 100644 --- a/modules/learn/pages/clusters-and-availability/failover.adoc +++ b/modules/learn/pages/clusters-and-availability/failover.adoc @@ -52,6 +52,21 @@ If manual failover is to be used, administrative intervention is required to det This can be achieved either by assigning an administrator to monitor the cluster; or by creating an externally based monitoring system that uses the Couchbase REST API to monitor the cluster, detect problems, and either provide notifications, or itself trigger failover. Such a system might be designed to take into account system or network components beyond the scope of Couchbase Server. +[#detect-unstable-nodes] +== Detecting Unstable Nodes + +You can have Couchbase Server's Cluster Manager perform automatic failovers of nodes that have been unreachable for a set period of time. +Failing over these nodes prevents the loss of the node from degrading database performance. +However, nodes can become unstable, where other nodes lose contact with them periodically. +These nodes may recover before the failover timeout expires and resume operation. + +In some cases, these nodes become unreachable for long enough that the Cluster Manager fails them over. +In other cases they can continue the cycle of instability followed by recovery. +Even though these disruptions are not as severe as a complete loss of the node, they can cause performance issues. +You should investigate and resolve these issues to prevent further problems. + +See xref:learn:clusters-and-availability/unstable-nodes.adoc[] for more information about unstable nodes. + [#failover-and-replica-promotion] == Failover and Replica Promotion diff --git a/modules/learn/pages/clusters-and-availability/hard-failover.adoc b/modules/learn/pages/clusters-and-availability/hard-failover.adoc index 5eb0732f62..d1d9c132e4 100644 --- a/modules/learn/pages/clusters-and-availability/hard-failover.adoc +++ b/modules/learn/pages/clusters-and-availability/hard-failover.adoc @@ -39,6 +39,10 @@ Note that this restriction also protects the cluster in situations where multipl [#performing-an-unsafe-failover] === Performing an Unsafe Failover +CAUTION: If you have 1 or more buckets using continuous backup, you must stop the Couchbase Server process on the node before performing an unsafe failover on it. +Not stopping the Couchbase Server process could result in data inconsistencies that can cause issues with the continuous backup. +See xref:learn:services-and-indexes/services/continuous-backup.adoc[] for more information. + In Couchbase Server 7.0 or a later version, metadata is managed by a _consensus protocol_; which achieves strong consistency by _synchronously_ replicating metadata to a majority of the nodes before considering it committed. (This is described in xref:learn:clusters-and-availability/metadata-management.adoc[Metadata Management].) The metadata so managed includes _topology information_. diff --git a/modules/learn/pages/clusters-and-availability/unstable-nodes.adoc b/modules/learn/pages/clusters-and-availability/unstable-nodes.adoc new file mode 100644 index 0000000000..897e3fdeda --- /dev/null +++ b/modules/learn/pages/clusters-and-availability/unstable-nodes.adoc @@ -0,0 +1,100 @@ += Unstable Nodes +:page-topic-type: concept +:description: Nodes that periodically become unavailable but recover before the auto failover timeout expires are considered unstable. This page describes what unstable nodes are and how to detect them. + +[abstract] +{description} + +== About Unstable Nodes + +An unstable node periodically becomes unavailable but recovers before the auto failover timeout expires. +Nodes can become unstable for a variety of reasons, such as: + +Network hardware issues:: +For example, a network port that's flapping (periodically failing) can cause intermittent connectivity issues. + +Kernel TCP/IP memory pressure:: +When a node is under heavy network load, the Linux kernel's TCP/IP stack can run low on memory. +The kernel may respond by refusing connections and dropping packets, which can cause nodes to become unreachable until the memory shortage is resolved. +See xref:install:tcp_mem_settings.adoc[] for more information about the kernel's TCP/IP memory settings. + +CPU, Memory, or Disk Resource Issues:: +When a node is under heavy CPU, memory, or disk I/O load, it may struggle to meet the demands of the cluster. +Hardware issues with any of these resources can also cause instability. + +Any of these issues can cause periods where the node is unreachable. +In some cases, the node may continue to be unreachable until it's automatically failed over. +However, the node can recover before the auto failover timeout expires, which lets it potentially repeat the cycle again. + +An unstable node can cause performance issues for the cluster, even if it does not lead to automatic failover. +When a node is unreachable, other nodes in the cluster may experience increased latency as they attempt to communicate with the unreachable node. + +== Tracking Instability Using Metrics + +Couchbase Server provides metrics to help you monitor its performance. +See xref:metrics-reference:metrics-reference.adoc[] for more information about Couchbase Server metrics. + +To track instability, you can monitor the xref:metrics-reference:ns-server-metrics.adoc#cm_node_unreachable_total[`cm_node_unreachable_total`] metric. +It is a cross-node counter metric that reports how many times a node has been unable to reach another node. +When you see multiple nodes incrementing this counter for the same node, it may indicate the node is unstable. + +[#what-metric-reports] +== What the Metric Reports + +The following screenshot shows an example of using Prometheus to view the `cm_node_unreachable_total` metric. + +image::clusters-and-availability/unstable-node-metric-timeseries.png[Viewing the cm_node_unreachable_total metric in Prometheus] + +Each entry represents a count of the times a node has found another node unreachable for a particular reason. +For example: + +---- +cm_node_unreachable_total{instance="node1.example.com:8091", + job="couchbase-server", + node="ns_1@node4.example.com", + reason="net_tick_timeout"} 26 +---- + +The labels in the metric identify the nodes and the type of issue: + +* The `instance` is the node which is reporting another node as unreachable. +* The `job` is the Prometheus job that you configured to scrape Couchbase Server metrics. +* The `node` is the node being reported as having issues. +It uses the https://www.erlang.org/doc/system/distributed.html#nodes[Erlang node name format]. +The portion before the `@` is the name of the Erlang process running on the host. +* The `reason` is the type of issue the instance (reporting node) observed in its connection to the node. +The possible reasons are: ++ + ** `connection_setup_failed`: Setting up the connection failed (after the `nodeup` messages were sent). + ** `no_network`: The reporting node has no network connection. + ** `net_kernel_terminated`: The Erlang `net_kernel` process terminated. + ** `shutdown`: The connection shut down for an unknown reason. + ** `connection_closed`: The node closed its connection with the instance. + ** `disconnect`: The reporting node forced a disconnection from the node. + ** `net_tick_timeout`: The network distribution heartbeat timed out. + ** `send_net_tick_failed`: The reporting node was not able to send the distribution heartbeat via the connection. + ** `get_status_failed`: The reporting node failed to retrieve status information from the connection. ++ +See https://www.erlang.org/doc/apps/kernel/net_kernel.html#:~:text=map.-,nodedown_reason[the Erlang documentation for `nodedown_reason`^] for more details about these errors. + +In the previous example, `node1.example.com` has reported that it was unable to reach `node4.example.com` 26 times due to a network distribution heartbeat timeout. +In the screenshot, you can see that multiple nodes have reported that `node4.example.com` was unreachable for several reasons. +These reports may indicate that `node4.example.com` is unstable. + +NOTE: Depending on the reason, the reporting node may increment its metric counter immediately or after a delay. +For example, a node reports a `connection closed` error immediately when it happens. +However, it only reports a `net_tick_timeout` after the timeout period has elapsed. +Therefore, you may see a lag between issues that nodes report immediately and ones they report after a delay. + +== Spotting Unstable Nodes + +When a node is unstable, you see a pattern of multiple nodes incrementing their `cm_node_unreachable_total` counters for it. +The following screenshot shows a Prometheus graph of the metric over a period of 50 minutes. + +image::clusters-and-availability/unstable-node-prometheus_chart.png[A chart showing multiple nodes incrementing their cm_node_unreachable_total metric multiple times in between periods of stability.] + +The lines in the graph show nodes incrementing their `cm_node_unreachable_total` metric counters when they were unable to reach `node4.example.com`. +The `reason` label for most of these counters is `net_tick_timeout` errors, although there are several reports of `connection closed`. +You can see there are periods of stability (where the values do not increment) followed by multiple nodes incrementing their counts around the same time. + +See xref:manage:monitor/monitor-node-stability.adoc[] for steps you can take to monitor node stability. \ No newline at end of file diff --git a/modules/learn/pages/data/change-history.adoc b/modules/learn/pages/data/change-history.adoc index dc7cac3def..003a3b423b 100644 --- a/modules/learn/pages/data/change-history.adoc +++ b/modules/learn/pages/data/change-history.adoc @@ -49,6 +49,11 @@ See xref:rest-api:rest-bucket-create.adoc[Creating and Editing Buckets]. * The CLI, using `couchbase-cli bucket-create` (to create a bucket) or `couchbase-cli bucket-edit` (to edit a bucket); specifying one or both of the parameters `history-retention-bytes` and `history-retention-seconds`. See xref:cli:cbcli/couchbase-cli-bucket-create.adoc[bucket-create] and xref:cli:cbcli/couchbase-cli-bucket-edit.adoc[bucket-edit]. +IMPORTANT: You must enable change history on any bucket you want to back up using continuous backup on. +Once you enable continuous backup, you cannot turn off change history for the bucket unless you turn off continuous backup first. +Using collection-level overrides of change history in a bucket where you have enabled continuous backup us unsupported. +See xref:learn:services/continuous-backup.adoc[] for more information. + [#default-collection-setting] === Default Collection-Setting diff --git a/modules/learn/pages/services-and-indexes/services/backup-service.adoc b/modules/learn/pages/services-and-indexes/services/backup-service.adoc index e24e3c1438..1f89e97778 100644 --- a/modules/learn/pages/services-and-indexes/services/backup-service.adoc +++ b/modules/learn/pages/services-and-indexes/services/backup-service.adoc @@ -36,6 +36,14 @@ To use it on a regular schedule, you must rely on an external scheduling system See xref:backup-restore:enterprise-backup-restore.adoc[cbbackupmgr] for more information about using the command-line tool. +== The Backup Service and Continuous Backup + +In addition to the periodic backups provided by the Backup Service, you can also use the continuous backup agent to frequently back up changes to Magma buckets. +This backup can limit the loss of data updates that occur between full and incremental backups. +It also records the timestamps of when data was mutated. +These timestamps let you perform Point-In-Time Recovery (PITR) to restore the Magma bucket's data to the state it was in at a specific moment. +See xref:learn:services/continuous-backup.adoc[] for more information about using continuous backup. + [#backup-service-architecture] == Backup Service Architecture diff --git a/modules/learn/pages/services-and-indexes/services/continuous-backup.adoc b/modules/learn/pages/services-and-indexes/services/continuous-backup.adoc new file mode 100644 index 0000000000..5e496207c8 --- /dev/null +++ b/modules/learn/pages/services-and-indexes/services/continuous-backup.adoc @@ -0,0 +1,222 @@ += Continuous Backup & Point in Time Recovery +:description: pass:q[Continuous backup frequently backs up mutations to Magma buckets and records timestamps to enable Point-In-Time Recovery (PITR).] +:enterprise-only: +:toclevels: 3 + +[abstract] +{description} + +The Backup Service and `cbbackupmgr` are designed to perform periodic backups. +For example, you may choose to have the Backup Service perform a daily full backup at midnight and then incremental backups every 2 hours. + +[ditaa] +.... + Periodic Backups + +----------+ +-----------+ + | cEEE | | cEEE | + | Full | |Incremental| + | Backup | | Backup | +Time ---+----------+-------------------------------------------------+-----------+------> + | | + Midnight 2:00 AM +.... + + +Any data mutations made since the last periodic backup could be lost if there is data loss or corruption. + +Continuous backup supplements full and incremental backups by performing backups at shorter intervals. +You can have it perform backups as frequently as every 2 minutes. +It can limit the loss of data mutations that take place between periodic full and incremental backups. +For example, the following diagram shows a continuous backup that's configured to perform backups every 10 minutes. + +[ditaa] +.... + Continuous Backups + +----------+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-----------+ + | cEEE | | | | | | | | | | | | | | | | | | | | | | | | | | cEEE | + | Full | +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ |Incremental| + | Backup | | Backup | +--------+----------+-------------------------------------------------+-----------+------> + | | + | Midnight | 2:00 A.M. +.... + +== Point in Time Recovery + +With periodic backups, you can only restore a bucket to the state it was in when it was backed up. +For example, consider the backups shown in the Periodic Backup diagram. +You can only choose to restore the bucket to the state it was in at midnight or at 2 A.M. +You cannot restore it to any state between the 2 backups. + +In addition to backing up data, continuous backup also records the timestamp of data mutations. +These timestamps let you perform Point-In-Time Recovery (PITR)—restoring the bucket to the state it was in at a specific moment. + +Using PITR, you can precisely recover from data loss or corruption. +For example, suppose a user accidentally flushed a bucket. +You can restore the bucket to seconds before the flush occurred, recovering the lost data. + +== How Continuous Backup Works + +Continuous backup relies on feature of the Magma storage engine to track changes to the data in a bucket. +Because it relies on these features, continuous backup is only available for Magma buckets. +You cannot use it with Couchstore buckets. + +You enable continuous backup on a per-bucket basis. +You can choose to enable it for buckets that contain critical data while leaving it off for buckets that not as vital or do not see many mutations. + +=== Continuous Backup Locations + +Continuous backup saves the data mutations and their timestamps to a backup storage location. +This location must be separate from the location of the backup repository for full and incremental backups. +All of the nodes in the cluster must have access to this storage location. +You can host the location on a shared network directory such as a Network File System (NFS) share. +Continuous backup also supports storage locations on Amazon S3, Microsoft Azure Blob Storage, and Google's Cloud Storage. + +You can use 1 continuous backup storage location to store backups for multiple buckets. +Having multiple buckets sharing the same storage location makes performing PITR on multiple buckets easier. +You use the same commands to restore multiple buckets. + +You can also use different storage locations for buckets. +Separate locations are useful in multi-tenancy configurations. +Each tenant can supply their own continuous backup location. +You can also separately track the cost of a tenant's cloud-based continuous backup location. + +=== The Continuous Backup Interval + +When enabling continuous backup, you must choose the interval when continuous backup copies the mutations to a bucket's data to the backup location. +The minimum interval is 2 minutes. +When setting the interval, you must consider potential data loss vs. potential increased storage cost. + +The longer you make the interval, the greater the possibility of losing data mutations that occur before the next continuous backup. +It also affects the latest moment you can choose to restore the bucket to during a PITR. + +[ditaa] +.... ++-------------+ Up to the +| Latest | backup +| continuous | interval | Current +| backup | + 2 Minutes | time +| | <-----------> | +| cEEE | | ++-------------+ V +--------------*---------------*---------> + | + Latest point in time + you can restore to +.... + +The latest point in time you can restore the bucket to is within the latest continuous backup. +This can be as long as the entire backup interval, plus an additional 2 minutes. +The additional 2 minutes is because Magma flushes its in-memory data to disk every 2 minutes. + +The continuous backup interval plus 2 minutes is the worst case scenario. +In most cases, you'll be able to restore to a more recent point in time. + +A shorter continuous backup interval can cost you more money if your storage location is cloud-based. +The cloud services that continuous backup supports all have per-request fees in addition to their raw data storage fee. +Having a shorter interval means more frequent API requests, and therefore more charges. +A continuous backup interval of 5 minutes costs you twice the amount of request fees than a 10 minute backup interval. + +The continuous backup interval setting is per bucket. +You can choose to have a shorter continuous backup interval on vital buckets that have a higher volume mutations. +You can also set a longer interval for less important buckets have fewer mutations. + +=== Continuous Backup Retention + +Continuous backup retains its backups for a configurable period of time. +The range you can set the retention period is from 1 hour to 60 days. + +The retention period controls how far back in time you can restore a bucket using PITR. +Continuous backup purges data that's older than the retention period. +Once continuous backup purges the data, you cannot perform a PITR to the range of time it contained. + +Assuming you have traditional full and incremental backups older than the continuous backup retention period, you can use them to restore the bucket. +However, they can only restore the bucket to the state it was in when the backup was taken. +You cannot use them to restore the bucket to an arbitrary point in time. + +When choosing the retention period, you must balance between the cost of storing the backup data and the flexibility of restoring your bucket to an earlier time. +If you choose cloud storage for your continuous backup location, you pay data storage fees based on the amounrt of data you store. +These fees increase the longer you set the retention period. + +== How PITR Works + +You can perform a PITR on a bucket to the same cluster or a different cluster. +When restoring to the same cluster, you can choose to restore to the a new bucket or to the existing bucket. + +If you're restoring to the original bucket, decide whether you want the bucket to be in the state it was in at the specific point in time. +PITR does not automatically flush the bucket before performing a restore. +Any documents added after the point in time you choose will remain in the bucket. +However, mutations to existing documents made after the point in time are lost. +If you want the bucket to be the way it was at the point in time you chose to restore to, flush the bucket before restoring. + +When restoring, PITR first restores the latest full and incremental backups from before restore time you chose. +It then replays the mutations stored in the continuous backups since the last full or incremental backup. +It continues replaying the mutations until it reaches the point in time you chose. + +[ditaa] +.... + + +----------+ +-----------+ + | cEEE | | cEEE | Continuous Backups + | Full | . . . |Incremental+--+--+--+--+--+--+--+--+--+ + | Backup | | Backup | | | | | | | | | | +----+----------+---------+-----------+--+--+--+--+--+--+--+*-+--+--> + | | | | + Restored Restored |<------------------->| + first second Continuous backups | + replayed | + | + Selected + point in + time +.... + + +== Continuous Backup's Effects on the Cluster + +Enabling has several impacts on the cluster and interactions with other features. + +* Continuous backup increases the disk usage on nodes. +Couchbase Server has to retain some files it would otherwise delete until continuous backup can back them up. +The amount of added disk space depends on the number of mutations and the length of the continuous backup interval. + +* You must use the credential store to provide the credentials for any cloud storage locations you use for continuous backup. +The credential store has its own requirements---you must enable peer-to-peer encryption and encryption at rest for Couchbase Server configuration files. +See the credential store documentation for more information. + +// FIXME: add link to the credential store docs when they are done. + +* As part of enabling continuous backup, you must enable the bucket's change history. +Change history is a Magma feature that lets continuous backup record the mutations so it can replay them back during a PITR. +When you have continuous backup enabled for a bucket, you cannot turn off the bucket's change history setting. + ++ +When you enable continuous backup for a bucket, disabling change history for individual collections is not supported. +Verify that no collection has a change history override setting on it before enabling continuous backup. + ++ +See xref:learn:data/change-history.adoc[] for more information about change history. + +=== Continuous Backup and Unsafe Failover + +For continuous backup to be able to reliably restore a bucket to a point it time, it must have a consistent history of the changes made to a bucket. +An xref:learn:clusters-and-availability/hard-failover.adoc#performing-an-unsafe-failover[unsafe failover] can cause consistency issues in this history. +If you must perform an unsafe failover on a node, first stop the Couchbase Server process on it. +Stopping the process prevents inconsistencies in history, and protects continuous backup's ability to perform a PITR. + +See xref:install:startup-shutdown.adoc[] for more instructions on shutting down the Couchbase Server process. + +=== Continuous Backup and Encryption at Rest + +If you enable encryption at rest for a bucket's data, continuous backup needs to maintain a copy of the encryption at rest Data Encryption Keys (DEKs). +It needs its own copy of these keys because the encryption at rest rotates its DEKs. +Therefore, the current DEKs are usually not the same ones continuous backup needs to decrypt older the data in its backups. +Continuous backup creates a backup of the DEKs along with the bucket's data so that it can decrypt the data itself. + +To protect the DEKs, you must configure continuous backup with access to a Key Management System (KMS) to protect the DEKs it saves alongside the bucket data. +It uses the KMS to securely re-encrypt the DEKs. +This re-encryption protects the keys the same way encryption at rest does. +All nodes in the cluster must be able to connect to the KMS you configure for continuous backup. + +If you have already configured a KMS to manage encryption keys for your traditional full and incremental backups, you can reuse it to manage the keys for continuous backup. + diff --git a/modules/manage/examples/continuous-backup.log b/modules/manage/examples/continuous-backup.log new file mode 100644 index 0000000000..5af6911e66 --- /dev/null +++ b/modules/manage/examples/continuous-backup.log @@ -0,0 +1,150 @@ +# Result of getting continuous backup info +# tag::get-backup-info[] +| Buckets +| ------- +| +| * Bucket +| ------ +| Name | UUID | +| travel-sample | b5de13bdc656985b0a41dd3d832c9be6 | +| +| Range +| ----- +| Start | End | +| 2026-06-05T14:57:18Z | 2026-06-23T17:55:22Z | +| +# end::get-backup-info[] + +# tag::restore-output[] +Warning: Restore has skipped some users and/or groups. Please check the logs for more information. +(1/6) Restoring backup '2026-06-05T14_07_44.644199759Z' +Copied all data in 2.196s (Avg. 20.72MiB/Sec) 63288 items / 41.43MiB +[===========================================================================================================================================] 100.00% + +| Transfer +| -------- +| Status | Avg Transfer Rate | Started At | Finished At | Duration | +| Succeeded | 20.72MiB/s | Tue, 09 Jun 2026 18:28:44 +0000 | Tue, 09 Jun 2026 18:28:46 +0000 | 2.274s | + +| Bucket +| ------ +| Name | Status | Transferred | Avg Transfer Rate | Started At | Finished At | Duration | +| travel-sample | Succeeded | 41.43MiB | 41.43MiB/s | Tue, 09 Jun 2026 18:28:45 +0000 | Tue, 09 Jun 2026 18:28:46 +0000 | 1.939s | +| +| Mutations | Deletions | Expirations | +| --------- | --------- | ----------- | +| Received | Errored | Skipped | Received | Errored | Skipped | Received | Errored | Skipped | +| 63288 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | + +Warning: Restore has skipped some users and/or groups. Please check the logs for more information. +(2/6) Restoring backup '2026-06-05T15_30_24.625814389Z' +Copied all data in 2.599s (Avg. 206.57KiB/Sec) 619 items / 413.14KiB +[===========================================================================================================================================] 100.00% + +| Transfer +| -------- +| Status | Avg Transfer Rate | Started At | Finished At | Duration | +| Succeeded | 206.57KiB/s | Tue, 09 Jun 2026 18:28:44 +0000 | Tue, 09 Jun 2026 18:28:47 +0000 | 2.663s | + +| Bucket +| ------ +| Name | Status | Transferred | Avg Transfer Rate | Started At | Finished At | Duration | +| travel-sample | Succeeded | 413.14KiB | 413.14KiB/s | Tue, 09 Jun 2026 18:28:47 +0000 | Tue, 09 Jun 2026 18:28:47 +0000 | 177ms | +| +| Mutations | Deletions | Expirations | +| --------- | --------- | ----------- | +| Received | Errored | Skipped | Received | Errored | Skipped | Received | Errored | Skipped | +| 369 | 0 | 0 | 250 | 0 | 0 | 0 | 0 | 0 | + +Warning: Restore has skipped some users and/or groups. Please check the logs for more information. +(3/6) Restoring backup '2026-06-05T16_37_54.174811004Z' +Copied all data in 2.991s (Avg. 143.06KiB/Sec) 303 items / 286.13KiB +[===========================================================================================================================================] 100.00% + +| Transfer +| -------- +| Status | Avg Transfer Rate | Started At | Finished At | Duration | +| Succeeded | 95.38KiB/s | Tue, 09 Jun 2026 18:28:44 +0000 | Tue, 09 Jun 2026 18:28:47 +0000 | 3.042s | + +| Bucket +| ------ +| Name | Status | Transferred | Avg Transfer Rate | Started At | Finished At | Duration | +| travel-sample | Succeeded | 286.13KiB | 286.13KiB/s | Tue, 09 Jun 2026 18:28:47 +0000 | Tue, 09 Jun 2026 18:28:47 +0000 | 172ms | +| +| Mutations | Deletions | Expirations | +| --------- | --------- | ----------- | +| Received | Errored | Skipped | Received | Errored | Skipped | Received | Errored | Skipped | +| 233 | 0 | 0 | 70 | 0 | 0 | 0 | 0 | 0 | + +Warning: Restore has skipped some users and/or groups. Please check the logs for more information. +(4/6) Restoring backup '2026-06-05T18_30_56.913953884Z' +Copied all data in 3.461s (Avg. 241.02KiB/Sec) 910 items / 723.06KiB +[===========================================================================================================================================] 100.00% + +| Transfer +| -------- +| Status | Avg Transfer Rate | Started At | Finished At | Duration | +| Succeeded | 241.02KiB/s | Tue, 09 Jun 2026 18:28:44 +0000 | Tue, 09 Jun 2026 18:28:48 +0000 | 3.498s | + +| Bucket +| ------ +| Name | Status | Transferred | Avg Transfer Rate | Started At | Finished At | Duration | +| travel-sample | Succeeded | 723.06KiB | 723.06KiB/s | Tue, 09 Jun 2026 18:28:47 +0000 | Tue, 09 Jun 2026 18:28:48 +0000 | 243ms | +| +| Mutations | Deletions | Expirations | +| --------- | --------- | ----------- | +| Received | Errored | Skipped | Received | Errored | Skipped | Received | Errored | Skipped | +| 633 | 0 | 0 | 277 | 0 | 0 | 0 | 0 | 0 | + +Warning: Restore has skipped some users and/or groups. Please check the logs for more information. +(5/6) Restoring backup '2026-06-05T19_30_57.726884217Z' +Copied all data in 5.093s (Avg. 11.28KiB/Sec) 54 items / 56.39KiB +[===========================================================================================================================================] 100.00% + +| Transfer +| -------- +| Status | Avg Transfer Rate | Started At | Finished At | Duration | +| Succeeded | 11.28KiB/s | Tue, 09 Jun 2026 18:28:44 +0000 | Tue, 09 Jun 2026 18:28:49 +0000 | 5.119s | + +| Bucket +| ------ +| Name | Status | Transferred | Avg Transfer Rate | Started At | Finished At | Duration | +| travel-sample | Succeeded | 56.39KiB | 56.39KiB/s | Tue, 09 Jun 2026 18:28:49 +0000 | Tue, 09 Jun 2026 18:28:49 +0000 | 117ms | +| +| Mutations | Deletions | Expirations | +| --------- | --------- | ----------- | +| Received | Errored | Skipped | Received | Errored | Skipped | Received | Errored | Skipped | +| 44 | 0 | 0 | 10 | 0 | 0 | 0 | 0 | 0 | + +(6/6) Restoring backup 'Continuous' +Copied all data in 5.316s (Avg. 378B/Sec) 0 items / 1.85KiB +[===========================================================================================================================================] 100.00% + +| Transfer +| -------- +| Status | Avg Transfer Rate | Started At | Finished At | Duration | +| Succeeded | 378B/s | Tue, 09 Jun 2026 18:28:44 +0000 | Tue, 09 Jun 2026 18:28:50 +0000 | 5.454s | + +| Bucket +| ------ +| Name | Status | Transferred | Avg Transfer Rate | Started At | Finished At | Duration | +| travel-sample | Succeeded | 1.85KiB | 1.85KiB/s | Tue, 09 Jun 2026 18:28:50 +0000 | Tue, 09 Jun 2026 18:28:50 +0000 | 91ms | +| +| Mutations | Deletions | Expirations | +| --------- | --------- | ----------- | +| Received | Errored | Skipped | Received | Errored | Skipped | Received | Errored | Skipped | +| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +root@node1:/# cbcontbk info -l /shared/continuous-backup/ +| Buckets +| ------- +| +| * Bucket +| ------ +| Name | UUID | +| travel-sample | b5de13bdc656985b0a41dd3d832c9be6 | +| +| Range +| ----- +| Start | End | +| 2026-06-05T14:57:18Z | 2026-06-09T14:54:10Z | +# end::restore-output[] \ No newline at end of file diff --git a/modules/manage/examples/continuous-backup.sh b/modules/manage/examples/continuous-backup.sh new file mode 100644 index 0000000000..cc0bd8562a --- /dev/null +++ b/modules/manage/examples/continuous-backup.sh @@ -0,0 +1,15 @@ +# Get information about the continuous backup location +# tag::get-backup-info[] +cbcontbk info -l /shared/continuous-backup/ +# end::get-backup-info[] + +# Restore the bucket +# tag::restore-bucket[] +cbcontbk restore --target 2026-06-08T19:54:10Z \ + -u $COUCHBASE_USERNAME -p $COUCHBASE_PASSWORD \ + --tmp-dir /scratch \ + -l /shared/continuous-backup/ \ + -a /shared/backups \ + -r 1c48c43c-45b8-4155-8352-7d21523b2603 \ + -c couchbase://node3.example.com +# end::restore-bucket[] \ No newline at end of file diff --git a/modules/manage/pages/manage-backup-and-restore/manage-continuous-backup.adoc b/modules/manage/pages/manage-backup-and-restore/manage-continuous-backup.adoc new file mode 100644 index 0000000000..0841bf2d6b --- /dev/null +++ b/modules/manage/pages/manage-backup-and-restore/manage-continuous-backup.adoc @@ -0,0 +1,305 @@ += Manage Continuous Backup +:description: pass:q[This topic describes how to configure continuous backup to frequently back up the data in your Magma buckets.] +:enterprise-only: +:toclevels: 3 + +[abstract] +{description} +See xref:learn:services-and-indexes/services/continuous-backup.adoc[] for an overview of continuous backup. + +== Prerequisites + +Before configuring continuous backup, your cluster must meet the following requirements: + +* Your Couchbase Server account must have the xref:learn:security/roles.adoc#backup-full-admin[Full Admin] or xref:learn:security/roles.adoc#backup-full-admin[Backup Full Admin] role. + +* It must have 1 or more Magma buckets. +Continuous backup relies on Magma's change history feature to back up individual mutations. +You cannot use it on Couchstore buckets. +Couchstore buckets can still be backed up and restored using the traditional full and incremental backups. + +* Verify that all of the system clocks in your cluster are synchronized. +See xref:install:synchronize-clocks-using-ntp.adoc[] for more information. + +* You must configure scheduled periodic backups using either the Backup Service or `cbbackupmgr`. +Point in Time Recovery (PITR) uses the full and incremental backups taken just before the point in time you're restoring to. +It restores these backups and then uses the data stored in the continuous backup to fill the gap between the previous intermittent backup and the point in time you're recovering to. +See xref:manage-backup-and-restore.adoc[] to learn how to configure intermittent backups. + +* You must have a shared location where continuous backup can store its backup data. +All node in the cluster must be able to reach this location. +It can be a shared filesystem, such as an NFS share. +You can also use cloud-based storage hosted by Amazon S3, Microsoft Azure Blob Storage, and Google's Cloud Storage. + ++ +Whatever location you choose, it must be empty of existing files and dedicated to continuous backup. +You can use the same storage location to store continuous backups for multiple buckets. +Using the same location makes performing a PITR on multiple buckets easier, as you can use the same commands to restore multiple buckets. + +* If you're using cloud-based storage for your continuous backup location, you must add the credentials to access the location to the Couchbase Server credential store. +You must also grant the backup service access to this credential. +See Credential Store for more information. + +// FIXME: add link to credential store docs once written. + +* If you have enabled encryption at rest for the bucket's data that you're backing up, you must supply continuous backup with access to a https://en.wikipedia.org/wiki/Key_management#Key_management_system[Key Management System^] (KMS). +It uses the KMS to encrypt the encryption at rest Data Access Keys (DEKs) it needs to decrypt the data during PITR. +If you have configured a KMS to encrypt keys for traditional periodic backup, you can reuse those credentials for continuous backup. +See xref:learn:security/native-encryption-at-rest-overview.adoc[] for more information about encryption at rest. + +== Configure Bucket Change History for Continuous Backup + +The continuous backup feature relies on the bucket having change history enabled. +Therefore, before you enable continuous backup, you must verify that the bucket's `historyRetentionCollectionDefault` setting is `true`. +You also must verify that no collection overrides the bucket's change history setting. + +You must also configure the bucket so that it keeps its change history long enough for continuous backup to save it to the storage location. +This period is either 15 minutes or twice the continuous backup interval, whichever is greater. + +See xref:learn:data/scopes-and-collections.adoc#change-history[Change History] for more information about Magma's change history feature. + +To configure the bucket's change history settings: + +. Verify that the bucket's change history setting is the default value of `true`. +The following example calls the REST API and pipes the result through `jq` to get the setting for the `travel-sample` bucket: + ++ +[source,bash] +``` +curl -s -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + http://node1.example.com:8091/pools/default/buckets/travel-sample \ + | jq '.historyRetentionCollectionDefault' +``` + ++ +The previous examples returns either `true` or `false`. + +. If the value is not `true`, set it to `true` as shown in the following example: + ++ +[source,bash] +``` +curl -s POST -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + http://node1.example.com:8091/pools/default/buckets/travel-sample\ + -d historyRetentionCollectionDefault=true +``` + ++ +Repeat step 1 to verify that `historyRetentionCollectionDefault` is now set to `true`. + +. Verify that no collection in the bucket overrides the bucket's `historyRetentionCollectionDefault` setting. +If a collection overrides this setting, continuous backup cannot back it up. +Excluding collections from continuous backup is unsupported. + ++ +The following example gets the settings for the `travel-sample` bucket and uses `jq` to locate any collections that have their `history` key set to `false`: + ++ +[source,bash] +``` +curl -s GET -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + http://node1.example.com:8091/pools/default/buckets/travel-sample/scopes \ + | jq '.scopes[] + | select(.name != "_system") + | .name as $scope + | .collections[] + | select(.history == false) + | {scope: $scope, collection: .name, history: .history}' +``` + ++ +Any collections that have overrides appear in the output. +For example: + ++ +[source,json] +``` +{ + "scope": "inventory", + "collection": "airline", + "history": false +} +{ + "scope": "tenant_agent_01", + "collection": "bookings", + "history": false +} +``` + +. If any collections have overrides, edit them to change their `history` setting to `true`. +The following example sets the history setting for the `airline` collection in the `inventory` scope to `true`. + ++ +[source,bash] +``` +curl -s -X PATCH -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + http://node1.example.com:8091/pools/default/buckets/travel-sample/scopes/inventory/collections/airline \ + -d history=true +``` + ++ +After editing the collections that had overrides, re-run step 3 to verify that no collection overrides the bucket's setting. + +. You must set the history retention time for the bucket to a period long enough for continuous backup to collect and save the bucket's history to the backup location. +This period is 15 minutes or double the continuous backup interval, whichever is longer. +For example, if you chose 10 minutes for your continuous backup interval, set the retention time to 20 minutes. + ++ +The following example sets the `travel-sample` bucket's history retention to 20 minutes (1200 seconds). + ++ +[source,bash] +``` +curl -s POST -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + http://node1.example.com:8091/pools/default/buckets/travel-sample \ + -d historyRetentionSeconds=1200 +``` + + +== Configure Continuous Backup + +You can configure continuous backup using the Couchbase Server Web Console, the command line interface, or the REST API. + +=== Configure Continuous Backup Using the Web Console + +. Click *Buckets*. +. If creating a new bucket, click *Add Bucket*. +Otherwise, expand an existing bucket and click *Edit*. +. Click *Advanced Bucket Settings*. +. Under +. Under Continuous Backup, select *Enable*. +. Enter the location to store the continuous backup data. + This is either: + * An absolute path to the mount point of a shared network storage location such as an NFS share. + This mount point must be the same on all nodes. + * The cloud storage URI for the storage location. +. Set how frequently continuous backup saves data to the storage location in minutes. +Remember that if you use a cloud storage location, a lower settings for this value can often result in greater cost due to per-access charges. +The minimum value is 2. +. Set the number of hours Couchbase Server should retain the continuous backup data, +This value controls the window where you can restore to a point in time. +If you use the cloud as a backup storage location, a higher setting results in higher data storage charges. +. If you entered a cloud storage URI for the Backup Location, choose the credential from the credential store for the Backup Service to use when authenticating with the cloud provider. +Make sure you have granted access to Backup Service for this credential. +. If you have enabled encryption at rest for the data in the bucket, enter the URI for the KMS Key. +Valid URIs start with `awskms`, `azurekeyvalue`, or `gcpkms`. + +=== Configure Continuous Backup Using the REST API + +You can enable continuous backup when creating a bucket or editing it via the REST-API. + +Whether you're creating a new bucket or editing an existing bucket, make a POST call to the `/pools/default/buckets/` REST API endpoint. +Set the following: + + +* `continuousBackupEnabled`: set to `true` to enable continuous backup for the bucket. +* `continuousBackupLocation`: The location where the backup service will store the continuous backup data. +This value must be either an absolute path to NFS an mount point mounted on every node or a cloud storage URI. +* `continuousBackupCloudStorageCredId`: If you set `continuousBackupLocation` to a cloud storage URI, set this to the name of a credential in the credential store that the Backup Service can use to authenticate. +You must grant the Backup Service access to this credential. +* `continuousBackupInterval`: How frequently, in minutes, the Backup Service copies data to the continuous backup location. +When using a cloud-based storage location, lower settings for this value result in higher per-access costs. +* `continuousBackupRetentionPeriod`: the number of hours the Backup Service keeps the continuous backup data before purging it. +This value sets how far back in time you can use Point in Time Recovery (PITR). +* If you have enabled encryption at rest for the bucket, you must supply one of the following: +** `continuousBackupKmKeyUrl`: The URI for the KMS key the Backup Service uses to manage the encryption key it uses to encrypt data encryption keys. + This URI must start with `awskms`, `azurekeyvalue`, or `gcpkms`. +** `continuousBackupKmCredId`: the name of a credential in the Couchbase Server credential store that grants the Backup Service access to a KMS to manage its encryption keys. + +The following example enables continuous backup for `travel-sample` bucket. +It sets the backup interval to 10 minutes. +The backup location is an NFS share mounted on each not at the path `/shared.continuous-backup`. + +[source,bash] +``` +curl -X POST localhost:8091/pools/default/buckets/travel-sample \ + -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + -d continuousBackupEnabled=true \ + -d continuousBackupLocation="/shared/continuous-backup" \ + -d continuousBackupInterval=10 +``` + +See xref:rest-api:rest-bucket-create.adoc[] for details about editing bucket settings using the REST API. + +=== Enable Continuous Backup Using the Command Line + +Use the `couchbase-cli` tool's `bucket create` or `bucket-edit` command to change the continuous backup settings for the bucket. + +Use the following arguments to configure continuous backup: + +* `--continuous-backup-enabled`: set to `1` to enable continuous backup for the bucket. +* `--continuous-backup-location`: The location where the backup service will store the continuous backup data. +This value must a string containing either an absolute path to an NFS mount point mounted on every node or a cloud storage URI. +* `--continuous-backup-cloud-storage-cred-id`: If you set `--continuous-backup-location` to a cloud storage URI, set this to the name of a credential in the Couchbase Server credential store. +The Backup Service uses this credential to authenticate with the cloud provider. +You must also grant the Backup Service access to this credential. +* `--continuous-backup-interval`: How frequently in minutes then Backup Service copies data to the continuous backup location. +When using a cloud-based storage location, lower settings for this value result in higher per-access costs. +* `--continuous-backup-retention-period`: the number of hours the Backup Service keeps the continuous backup data before purging it. +This value sets how far back in time you can use Point in Time Recovery (PITR). +* If you have enabled encryption at rest for the bucket, you must supply one of the following: +** `--continuous-backup-km-key-url`: The URI for the KMS key the Backup Service uses to manage the encryption key it uses to encrypt data encryption keys. + This URI must start with `awskms`, `azurekeyvalue`, or `gcpkms`. +** `--continuous-backup-km-cred=id`: the name of a credential in the Couchbase Server credential store that grants the Backup Service access to a KMS to manage its encryption keys. + +The following example enables continuous backup on the `travel-sample` bucket. +It sets the backup interval to 10 minutes and the retention period to 30 days (270 hours). +The backup location is an NFS share mounted at `/shared/continuous-backup` on all nodes. + +[source,bash] +``` +couchbase-cli bucket-edit --cluster couchbase://node1.example.com \ + --username $COUCHBASE_USERNAME \ + --password $COUCHBASE_PASSWORD \ + --bucket travel-sample \ + --continuous-backup-enabled 1 \ + --continuous-backup-location /shared/continuous-backup \ + --continuous-backup-interval 10 \ + --continuous-backup-retention-period 270 +``` + +See the documentation for the `couchbase-cli` tool's xref:cli:cbcli/couchbase-cli-bucket-create.adoc[] and xref:cli:cbcli/couchbase-cli-bucket-edit.adoc[] commands for more information about creating and editing buckets using the command line. + +[#stop-continuous-backup] +## Stop Continuous Backup + +Once enabled, you can stop continuous backup for a bucket. +You must must continuous backups before you do a PITR to prevent a backup from occurring during the restore. +You may also want to stop it to preserve the PITR recovery window that's currently in the continuous backup location. + +You can turn off continuous backup using the Couchbase Server Web Console, REST API, or command line: + +Using the Couchbase Server Web Console:: + ++ +. Click *Buckets*. +. Click the entry for the bucket. +. Click *Edit*. +. Click *Advanced bucket settings*. +. Under *Continuous Backup*, deselect *Enabled*. +. Click *Save Changes*. + +Using the REST API:: + +Make a POST call to the `/pools/default/buckets/` endpoint and set `continuousBackupEnabled` to `false`. +For example, to turn off continuous backup for the `travel-sample` bucket, use this command: + ++ +[souce,bash] +``` +curl -X POST localhost:8091/pools/default/buckets/travel-sample \ + -u $COUCHBASE_USERNAME:$COUCHBASE_PASSWORD \ + -d continuousBackupEnabled=false +``` + +Using the Command Line Interface:: + +Use the `couchbase-cli` tools' `edit-bucket` command with the argument `--continuous-backup-enabled 0`: + +[source.bash] +``` +couchbase-cli bucket-edit --cluster couchbase://node1.example.com \ + --username $COUCHBASE_USERNAME --password $COUCHBASE_PASSWORD \ + --bucket travel-sample \ + --continuous-backup-enabled 0 +``` diff --git a/modules/manage/pages/manage-backup-and-restore/manage-pitr.adoc b/modules/manage/pages/manage-backup-and-restore/manage-pitr.adoc new file mode 100644 index 0000000000..6b5d672646 --- /dev/null +++ b/modules/manage/pages/manage-backup-and-restore/manage-pitr.adoc @@ -0,0 +1,182 @@ += Manage Point in Time Recovery (PITR) +:description: pass:q[Point in time recovery (PITR) lets you restore a bucket to the state it was in at a specific time.] +:enterprise-only: +:toclevels: 3 + +[abstract] +{description} +See xref:learn:services-and-indexes/services/continuous-backup.adoc[] for an overview of continuous backup and point in time recovery. + +## Prerequisites + +* Your Couchbase Server account must have the xref:learn:security/roles.adoc#backup-full-admin[Full Admin] or xref:learn:security/roles.adoc#backup-full-admin[Backup Full Admin] role. + +* You must have a Magma bucket configured with continuous backup. +See xref:manage:manage-backup-and-restore/manage-continuous-backup.adoc[] for the steps to configure continuous backup for a Magma bucket. + +* Continuous backup must have made at least a single backup to the continuous backup location. +This means continuous backup must have been active for a bit longer than its continuous backup interval. + +* You must have a traditional periodic backups for the bucket you are restoring. +Continuous backup restores the most recent full backup taken before the pont in time you are restoring to. +It then restores any incremental backups taken between the full backup and the point in time you chose. +It uses the data in the continuous backup location to fill the gap between the last traditional backup it restored and the target point in time. + +* You must choose which point in time you want to restore the bucket to. + ++ +The earliest point in time you can restore to is determined by your continuous backup retention period. +The exception is if you enabled continuous backup more recently than the retention period. +In that case, the earliest moment you can restore to is shortly after you enabled continuous backup. +If you need to restore your cluster to a point earlier than this time, you can only restore a traditional backup, assuming you have one that covers the time you need to restore to. +However, you cannot restore to a specific point in time with traditional backup. + ++ +The latest time you can restore to is whenever the Backup Service last copied data to the continuous backup location. +This may be as far back in the past as the continuous backup iteration period you set when configuring continuous backup. +If you stopped continuous backup earlier than + ++ +See xref:manage:manage-backup-and-restore/monitor-continuous-backup.adoc#get-cont-backup-info[Get Information About a Continuous Backup Location] to learn how to find the range of time backed up by a continuous backup location. + +* You must have a bucket where you want to restore to. +This can be: ++ +-- +** The original bucket. +** A new bucket in the same cluster. +** A bucket in a different cluster. +-- ++ +PITR recovery does not flush the bucket before a restore. +By default, it does not overwrite existing documents already in the bucket. +If you want to restore the bucket to its exact state at the point in time you choose, flush the bucket before restoring. +See xref:manage:manage-buckets/flush-bucket.adoc[] for more information about flushing buckets. + +* To prevent consistency issues, stop continuous backup on the bucket you're restoring. +You must stop continuous backup even if you're not restoring to the original bucket. +Once the PITR finishes, you can restart continuous backup. +See xref:manage:manage-backup-and-restore/manage-continuous-backup.adoc#stop-continuous-backup[Stop Continuous Backup] to learn how to stop continuous backup for a bucket. + +NOTE: You do not need to stop traditional periodic backups or XDCR for the bucket when performing PITR. + + +## Restore to a Point in Time + +You use the `cbcontbk` command line tool to restore a bucket backed up using continuous backup to point in time. + +When calling `cbcontbk`, you must supply the following arguments: + +* `--target` is the date and time you want to restore the bucket to in an https://www.rfc-editor.org/info/rfc3339/[RFC3339 timestamp^]. +* `-u` and `-p` are the username and password for the full administrator. +* `--tmp-dir` a temporary directory the Backup Service can use when restoring data. +* `-l` the continuous backup storage location. +This is either the absolute path of the NFS mount point, or the URI of the cloud storage location. +* `-a` the path to the traditional backup directory or its . +* `-r` is the UUID for the repository containing the bucket's traditional backup. +* `-c` is the URL for a node in the cluster running the backup service. + +In addition, you must supply credentials the Backup Service can use to authenticate with the continuous backup location and the traditional backup repository if they're stored in the cloud. +You have encrypted backups, you must also supply credentials to decrypt them. +See the documentation for `cbcontbk` for details. + +// FIXME: add link to `cbcontbk` docs when they are available in the repo. + +For example, suppose you want to restore the `travel-sample` bucket that uses locally mounted NFS shares for continuous backup and traditional backup. +Also suppose you want to restore to the original bucket and want the bucket to be in the state it was in at your chosen restoration time. +In that case, you can follow these steps to perform the PITR: + +. Stop continuous backup for the bucket. +Because you'll need to use the command line to run `cbcontbk` anyhow, this example uses command line on one of the nodes to stop continuous backup: + ++ +[source,bash] +``` +couchbase-cli bucket-edit --cluster couchbase://localhost \ + --username $COUCHBASE_USERNAME --password $COUCHBASE_PASSWORD \ + --bucket travel-sample \ + --continuous-backup-enabled 0 +``` + +. In this example, the goal is to have the bucket to be the exact state it was at the recovery time. +Therefore, you need to flush the bucket before performing PITR. + ++ +[source,bash] +``` +couchbase-cli bucket-flush --cluster couchbase://localhost \ + --username $COUCHBASE_USERNAME --password $COUCHBASE_PASSWORD \ + --bucket travel-sample +``` + ++ +[NOTE] +==== +The previous example assumes the bucket is already configured to allow flushing. +If it's not, you must first enable flushing using the command: + +[source,bash] +``` +couchbase-cli bucket-edit --cluster couchbase://localhost \ + --username $COUCHBASE_USERNAME --password $COUCHBASE_PASSWORD \ + --bucket travel-sample \ + --enable-flush 1 +``` + +After finishing the PITR, consider tunring off flushing the bucket again to prevent accidental data loss. +==== + +. Before performing the restore, you should verify the point in time you want to restore to is available in the continuous backup location. +You can find the range of times you can restore to using the `cbcontbk` command line tool. + ++ +[source,bash] +``` +include::manage:example$continuous-backup.sh[tag=get-backup-info] +``` + ++ +The result of the previous command looks like the following: + ++ +[source,log] +``` +include::manage:example$continuous-backup.log[tag=get-backup-info] +``` + ++ +The result shows that you can restore to a point in time between June 6th at 14:57 GMT and June 23rd at 17:55 GMT. + +. Use the `cbcontbk restore` command to restore the bucket. +The following command restores `travel-sample` to the state it was in at June 8th, 2026 at 19:54:10 GMT. + ++ +[source,bash] +``` +include::manage:example$continuous-backup.sh[tag=restore-bucket] +``` + ++ +The output from this command looks like this: + ++ +[source,log] +``` +include::manage:example$continuous-backup.log[tag=restore-output] +``` + ++ +You can see that PITR restores a traditional full backup and possibly multiple incremental backups. +Then it replays mutations from the continuous backup until it reaches the selected point in time. + +. After you have finished the PITR, start continuous backup again. + ++ +[source,bash] +``` +couchbase-cli bucket-edit --cluster couchbase://localhost \ + --username $COUCHBASE_USERNAME --password $COUCHBASE_PASSWORD \ + --bucket travel-sample \ + --continuous-backup-enabled 1 +``` + diff --git a/modules/manage/pages/manage-backup-and-restore/monitor-continuous-backup.adoc b/modules/manage/pages/manage-backup-and-restore/monitor-continuous-backup.adoc new file mode 100644 index 0000000000..15af3b1ae1 --- /dev/null +++ b/modules/manage/pages/manage-backup-and-restore/monitor-continuous-backup.adoc @@ -0,0 +1,62 @@ += Monitor Continuous Backup +:description: pass:q[Once you have enabled continuous backup for a bucket, you can monitor its status.] +:enterprise-only: +:toclevels: 3 + +[abstract] +{description} +See xref:learn:services-and-indexes/services/continuous-backup.adoc[] for an overview of continuous backup and point in time recovery. + +== Prerequisites + +* Your Couchbase Server account must have the xref:learn:security/roles.adoc#backup-full-admin[Full Admin] or xref:learn:security/roles.adoc#backup-full-admin[Backup Full Admin] role. +* You must have a Magma bucket with continuous backup enabled. +See xref:manage:manage-backup-and-restore/manage-continuous-backup.adoc[] for the steps to configure continuous backup for a Magma bucket. + + +[#get-cont-backup-info] +== Get Information About a Continuous Backup Location + +Once you have enabled continuous backup, you can get information about your backup location using the `cbcontbk` command line tool's `info` command. +The information includes the earliest and latest data in the location. + +To get the information about the location, use the command: + +[source,bash] +``` +cbcontbk info -l +``` + +Where `` is either the local path to the NFS mount or the URI of the cloud storage location where the backup is stored. +If the storage location is cloud-based, you must also supply the credentials and other settings `cbcontbk` needs to read data from the location. +See the `cbcontbk` documentation for details. + +// FIXME: link to cbcontbk docs when they are available. + +The following example gets information about the continuous backup location stored on an NFS share mounted at `/shared/continuous-backup` on all nodes in the cluster. + +[source,bash] +``` +include::manage:example$continuous-backup.sh[tag=get-backup-info] +``` + +The following example shows the output of the previous command for a location backing up the `travel-sample` bucket. + +[source,log] +``` +include::manage:example$continuous-backup.log[tag=get-backup-info] +``` + +The timestamps under the Range heading in the output show you the earliest and latest times you can restore the bucket to using point in time recovery (PITR). +See xref:manage:manage-backup-and-restore/manage-pitr.adoc[] for more information about performing a PITR. + +## Continuous Backup Metrics + +Continuous backup exposes several metrics that let you monitor its status. +You can use these metrics to monitor its status in tools such as Prometheus. +These metrics all start with the `contbk_` (continuous backup) prefix. + +// FIXME: link to metrics whenever they show up in the metrics_metadata file in the server build.. They aren't there as of build #2395 + +For more information about monitoring Couchbase Server using metrics, see xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[]. + diff --git a/modules/manage/pages/manage-xdcr/xdcr-management-overview.adoc b/modules/manage/pages/manage-xdcr/xdcr-management-overview.adoc index 16d3ff8a32..5110d0c008 100644 --- a/modules/manage/pages/manage-xdcr/xdcr-management-overview.adoc +++ b/modules/manage/pages/manage-xdcr/xdcr-management-overview.adoc @@ -1,5 +1,5 @@ = XDCR Management Overview -:description: Cross Datacenter Replication (XDCR) provides an easy way to replicate data from one cluster to another. +:description: Cross datacenter Replication (XDCR) provides an easy way to replicate data from one cluster to another. :page-aliases: xdcr:xdcr-intro [abstract] @@ -7,73 +7,97 @@ [#xdcr-summary] == What is XDCR? -Cross Data Center Replication (XDCR) replicates data between clusters: this provides protection against data-center failure, and also provides high-performance data-access for globally distributed, mission-critical applications. +Cross datacenter Replication (XDCR) replicates data between clusters: this provides protection against datacenter failure, and also provides high-performance data-access for globally distributed, mission-critical applications. -Note that Couchbase has modified the license restrictions to its Couchbase Server Community Edition package, for version 7.0 and higher: in consequence, XDCR is promoted to a commercial-only feature of Enterprise Edition. -See https://blog.couchbase.com/couchbase-modifies-license-free-community-edition-package/[Couchbase Modifies License of Free Community Edition Package^], for more information on the license restrictions; and see xref:manage:manage-xdcr/xdcr-management-overview.adoc#xdcr-and-community-edition[XDCR and Community Edition], below, for information on how the new restrictions affect the experience of Community-Edition administrators. +[NOTE] +==== +Couchbase has modified the license restrictions to its Couchbase Server Community Edition package, for version 7.0 and higher: + +XDCR is promoted to a commercial-only feature of Couchbase Server Enterprise Edition. + +For more information, see https://blog.couchbase.com/couchbase-modifies-license-free-community-edition-package/[Couchbase Modifies License of Free Community Edition Package^], + +For more information about how the new restrictions affect the experience of Community-Edition administrators, see xref:manage:manage-xdcr/xdcr-management-overview.adoc#xdcr-and-community-edition[XDCR and Community Edition] below. +==== XDCR replicates data from a specific bucket on the source cluster to a specific bucket on the target cluster. -Any bucket (Couchbase or Ephemeral) on any cluster can be specified as a source or a target for one or more XDCR definitions. -_Scopes_ and _collections_, within source and target buckets, can also be specified. -Data from the source is pushed to the target bucket by means of an XDCR agent, running on the source cluster, using the Database Change Protocol. +Any bucket (Couchbase or Ephemeral) on any cluster can be specified as a source or a target for 1 or more XDCR definitions. +`Scopes` and `collections`, within source and target buckets, can also be specified. +Data from the source is pushed to the target bucket by an XDCR agent, running on the source cluster, using the Database Change Protocol. + +[NOTE] +==== +Prior to Server 8.0, +XDCR could only be established between buckets where the numbers of vBuckets were the same. + +Now, if the cluster versions in the replication topology are 8.0 and later, XDCR can be established between buckets with different numbers of vBuckets. -Note that XDCR can only be established between clusters whose numbers of vBuckets are equal: all supported platforms have _1024_ vBuckets except _MacOS_, which has _64_. -For more information, see xref:learn:buckets-memory-and-storage/vbuckets.adoc[vBuckets]. +While an 8.x cluster can create an XDCR to a 7.x cluster bucket with a different number of vBuckets, a 7.x cluster can only create an XDCR to a bucket with the same number of vBuckets regardless of the target cluster version. +==== -A complete architectural description of XDCR is provided in xref:learn:clusters-and-availability/xdcr-overview.adoc[Cross Data Center Replication (XDCR)]. -You may wish to familiarize yourself with the information provided there, before performing the routines provided in this section. +A complete architectural description of XDCR is provided in xref:learn:clusters-and-availability/xdcr-overview.adoc[Cross datacenter Replication (XDCR)]. +You may want to familiarize yourself with the information provided there before performing the routines provided in this section. -For information on scopes and collections, see xref:learn:data/scopes-and-collections.adoc[Scopes and Collections]. +For information about scopes and collections, see xref:learn:data/scopes-and-collections.adoc[Scopes and Collections]. [#what-xdcr-tasks-can-be-performed] == What XDCR Tasks Can Be Performed? Management of XDCR includes the following: -* _Preparation_: Make sure that you have appropriate permissions for managing XDCR. +* Preparation: Make sure that you have appropriate permissions for managing XDCR. Check platform sizes, configurations, and ports. Details are provided in xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR]. -* _Reference_ management: Remote clusters must be registered as targets for XDCR. +* Reference management: Remote clusters must be registered as targets for XDCR. This requires appropriate administration credentials for the remote cluster, and the existence on that cluster of one or more buckets that can be specified as recipients of replicated data. -Information on establishing references is provided in xref:manage:manage-xdcr/create-xdcr-reference.adoc[Create a Reference]; and information on deleting them in xref:manage:manage-xdcr/delete-xdcr-reference.adoc[Delete a Reference]. +Information about establishing references is provided in xref:manage:manage-xdcr/create-xdcr-reference.adoc[Create a Reference]; and information about deleting them in xref:manage:manage-xdcr/delete-xdcr-reference.adoc[Delete a Reference]. -* _Replication_ management: Once a reference has been registered on the local cluster, it can be specified as the target for a _replication_. +* Replication management: Once a reference has been registered on the local cluster, it can be specified as the target for a replication. This requires that an existing source and an existing target bucket also be specified. Optionally, filters can be established, so that only documents with matching ids, fields, values, or extended attributes are replicated. -Additionally, advanced settings can be configured, to ensure optimal performance. -Information on establishing replications is provided in xref:manage:manage-xdcr/create-xdcr-replication.adoc[Create a Replication]; and information on deleting them in xref:manage:manage-xdcr/delete-xdcr-replication.adoc[Delete a Replication]. +Advanced settings can be configured to ensure optimal performance. +Information about establishing replications is provided in xref:manage:manage-xdcr/create-xdcr-replication.adoc[Create a Replication] and information about deleting them in xref:manage:manage-xdcr/delete-xdcr-replication.adoc[Delete a Replication]. + -Note that replications can be configured to occur between specific _scopes_ and _collections_; as described in xref:manage:manage-xdcr/replicate-using-scopes-and-collections.adoc[Replicate Using Scopes and Collections]. +NOTE: Replications can be configured to occur between specific `scopes` and `collections` as described in xref:manage:manage-xdcr/replicate-using-scopes-and-collections.adoc[Replicate Using Scopes and Collections]. -* _Pausing_ and _Resuming_ replications: Once started, a replication is continuous; mutations on the source being constantly transmitted to the target. -Occasionally, for purposes of system maintenance, it may be desirable manually to pause a replication, and then resume it. -Information is provided in xref:manage:manage-xdcr/pause-xdcr-replication.adoc[Pause a Replication]; and xref:manage:manage-xdcr/resume-xdcr-replication.adoc[Resume a Replication]. +* Pausing and Resuming replications: Once started, a replication is continuous; mutations on the source are constantly transmitted to the target. +For purposes of system maintenance, it may be desirable manually to pause a replication and then resume it. +Information is provided in xref:manage:manage-xdcr/pause-xdcr-replication.adoc[Pause a Replication] and xref:manage:manage-xdcr/resume-xdcr-replication.adoc[Resume a Replication]. -* _Recovering Data_: In the event of data-loss, the *cbrecovery* tool can be used to restore data. -The tool accesses remotely replicated buckets, previously created with XDCR, and copies appropriate subsets of their data back onto the original source-cluster. +* Recovering Data: In the event of data-loss, the `cbrecovery` tool can be used to restore data. +The tool accesses remotely replicated buckets created with XDCR, and copies appropriate subsets of their data back onto the original source-cluster. Information is provided in xref:manage:manage-xdcr/recover-data-with-xdcr.adoc[Recover Data with XDCR]. [#how-to-use-xdcr-management-section] == How to Use This Section This section is divided into multiple subsections, each of which presents step-by-step examples of how to perform a particular XDCR management task. -In most subsections, three examples are provided, showing how to perform the same task with Couchbase Web Console, CLI, and REST API respectively. -The subsections are arranged in a sequence, to make it easy to start from the first example, xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR], and proceed to the last. +In most subsections, 3 examples are provided, showing how to perform the same task with Couchbase Web Console, command-line tool, and REST API respectively. +The subsections are arranged in a sequence to make it easy to start from the first example, xref:manage:manage-xdcr/prepare-for-xdcr.adoc[Prepare for XDCR], and proceed to the last. [#xdcr-and-community-edition] == XDCR and Community Edition Couchbase has modified the license restrictions to its Couchbase Server Community Edition package, for version 7.0 and higher: in consequence, XDCR is promoted to a commercial-only feature of Enterprise Edition. -Consequently, prior to any attempt to add a remote cluster, the *XDCR* screen displays the following message: -image::manage-xdcr/xdcr-screen-ce.png[,720,align=middle] +[NOTE] +.Replicating from a CE server to an EE server +==== +You can still replicate data from a CE server as long as the data is being replicated to an EE installation running XDCR. +==== -The provided link takes the reader to detailed information on the new license restrictions, at https://blog.couchbase.com/couchbase-modifies-license-free-community-edition-package/[Couchbase Modifies License of Free Community Edition Package^]. +Prior to any attempt to add a remote cluster, the *XDCR* screen displays the following message: + +image::manage-xdcr/xdcr-screen-ce.png[,720, align=middle] + +The provided link takes the reader to detailed information about the new license restrictions, at https://blog.couchbase.com/couchbase-modifies-license-free-community-edition-package/[Couchbase Modifies License of Free Community Edition Package^]. Attempts to establish replications cause the following console message to be displayed: -image::manage-xdcr/xdcr-console-message-ce.png[,400,align=middle] +image::manage-xdcr/xdcr-console-message-ce.png[,400, align=middle] + +Community-Edition administrators who want to upgrade to version 7.0 or later and also want to use XDCR are recommended to consult https://blog.couchbase.com/couchbase-modifies-license-free-community-edition-package/[Couchbase Modifies License of Free Community Edition Package^], for guidance. + -Community-Edition adminstrators who wish to upgrade to version 7.0 or later, and wish to use XDCR, are recommended to consult https://blog.couchbase.com/couchbase-modifies-license-free-community-edition-package/[Couchbase Modifies License of Free Community Edition Package^], for guidance. diff --git a/modules/manage/pages/monitor/monitor-node-stability.adoc b/modules/manage/pages/monitor/monitor-node-stability.adoc new file mode 100644 index 0000000000..6635dcee50 --- /dev/null +++ b/modules/manage/pages/monitor/monitor-node-stability.adoc @@ -0,0 +1,322 @@ += Monitor Node Stability +:page-topic-type: guide +:description: Nodes that periodically become unavailable but recover before the auto failover timeout expires are considered unstable. This page describes how to monitor for unstable nodes and investigate the causes of instability. + +[abstract] +{description} + +To learn more about unstable nodes, see xref:learn:clusters-and-availability/unstable-nodes.adoc[]. + + +== Prerequisites + +* You must have some way of monitoring Couchbase Server metrics. +You can either use scripts that call the Couchbase Server xref:rest-api:rest-statistics.adoc[] REST API or xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[configure Prometheus] to monitor the metric. + +* To troubleshoot the causes of instability, you may need access to the node's operating system logs and other diagnostic information. + +== Monitor for Unstable Nodes + +To monitor for unstable nodes, you track Couchbase Server's xref:metrics-reference:ns-server-metrics.adoc#cm_node_unreachable_total[`cm_node_unreachable_total`] metric for each node in your cluster. +This metric records each time a node cannot reach another node in the cluster. +When you see a pattern of multiple nodes reporting the same node as unreachable, but that node recovers, it may be unstable. + +=== Use Prometheus to Monitor for Unstable Nodes + +If you're using Prometheus to monitor Couchbase Server, you can create alerts that trigger when multiple nodes report the same node as being unreachable over time. +The following example Prometheus alert rule triggers when 2 or more nodes report the same node as being unreachable over a 5 minute period: + +[source,yaml] +---- +groups: + - name: couchbase-stability + rules: + - alert: CouchbaseUnstableNode + expr: | + count by (node) ( + increase(cm_node_unreachable_total[5m]) > 0 + ) >= 2 + for: 5m + labels: + severity: warning + annotations: + summary: "Unstable Couchbase node detected" + description: > + {{ $value }} nodes have reported {{ $labels.node }} as unreachable. +---- + +The `expr` field in the alert rule uses the `increase` function to see if there have been any increments in the `cm_node_unreachable_total` metric for each node during the last 5 minutes. +It then counts how many nodes have reported each node as unreachable. +It triggers the alert if 2 or more nodes have reported the same node as unreachable. + +You can use this example as a starting point to monitor for unstable nodes. +You should customize the alert further to reduce false positives. + +For example, before triggering an alert, you may want to determine whether Couchbase Server has performed an auto failover on the node. +By the time Couchbase Server performs an auto failover on a node, its peers have already reported it as unreachable by incrementing their `cm_node_unreachable_total` counters. +In this case, there's no need to trigger the unstable node alert because the auto failover should alert administrators to the issue. + +[#stat-rest-api] +=== Use the Statistics REST API to Monitor Node Instability + +You can use the `/pools/default/stats/range/cm_node_unreachable_total` REST API endpoint to get the values of the metric over time. +The following example demonstrates getting the starting and ending values of the `cm_node_unreachable_total` metric counters from the last 20 minutes: + +[source,bash] +---- + curl -u Administrator:password -X GET \ + 'http://localhost:8091/pools/default/stats/range/cm_node_unreachable_total?start=-1200&step=1200' \ + | jq +---- + +The previous example returns a JSON object whose `data` field contains a list of metric counters for different nodes and reasons. +The following JSON is an example of the response to the previous example: + +[source,json] +---- +{ + "data": [ + { + "metric": { + "nodes": [ + "node1.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node3.example.com", + "reason": "connection_closed" + }, + "values": [ + [ + 1775762638, + "3" + ], + [ + 1775763838, + "4" + ] + ] + }, + { + "metric": { + "nodes": [ + "node1.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node3.example.com", + "reason": "net_tick_timeout" + }, + "values": [ + [ + 1775762638, + "36" + ], + [ + 1775763838, + "39" + ] + ] + }, + { + "metric": { + "nodes": [ + "node2.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node3.example.com", + "reason": "net_tick_timeout" + }, + "values": [ + [ + 1775762638, + "34" + ], + [ + 1775763838, + "40" + ] + ] + }, + { + "metric": { + "nodes": [ + "node3.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node1.example.com", + "reason": "connection_closed" + }, + "values": [ + [ + 1775762638, + "5" + ], + [ + 1775763838, + "7" + ] + ] + }, + { + "metric": { + "nodes": [ + "node3.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node1.example.com", + "reason": "disconnect" + }, + "values": [ + [ + 1775762638, + "3" + ], + [ + 1775763838, + "4" + ] + ] + }, + { + "metric": { + "nodes": [ + "node3.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node1.example.com", + "reason": "net_tick_timeout" + }, + "values": [ + [ + 1775762638, + "16" + ], + [ + 1775763838, + "16" + ] + ] + }, + { + "metric": { + "nodes": [ + "node3.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node2.example.com", + "reason": "connection_closed" + }, + "values": [ + [ + 1775762638, + "7" + ], + [ + 1775763838, + "9" + ] + ] + }, + { + "metric": { + "nodes": [ + "node3.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node2.example.com", + "reason": "disconnect" + }, + "values": [ + [ + 1775762638, + "3" + ], + [ + 1775763838, + "3" + ] + ] + }, + { + "metric": { + "nodes": [ + "node3.example.com:8091" + ], + "instance": "ns_server", + "name": "cm_node_unreachable_total", + "node": "ns_1@node2.example.com", + "reason": "net_tick_timeout" + }, + "values": [ + [ + 1775762638, + "20" + ], + [ + 1775763838, + "23" + ] + ] + }, + ], + "errors": [], + "startTimestamp": 1775762638, + "endTimestamp": 1775763838 +} +---- + +Each `metric` contains the following information: + +* The `nodes` list tells you which node is reporting the metric. +* The `node` field contains the target of the metric. +* The `reason` is why the reporting node could not reach the target node. +See xref:learn:clusters-and-availability/unstable-nodes.adoc#what-metric-reports[What the Metric Reports] for a description. + +The associated `values` list contains the starting and ending value for the counter. +The key for these entries is the Unix epoch timestamp of when the value was recorded, and the value is the value of the counter at that time. + +From the example output, you can see that during the 20 minutes, `node1` and `node2` reported `node3` as being unreachable due to `net_tick_timeout` 3 times and 6 times respectively (the end value minus the start value). +Meanwhile, neither `node1` nor `node2` reported issues with each other. +This suggests `node3` is unstable, rather than a wider issue in the cluster. + +NOTE: You can also see that `node3` reported connection issues with the other 2 nodes. +However, because neither `node1` nor `node2` had issues with each other, the issue is probably localized to `node3`. + +You can use the REST API call in the previous example as the basis for monitoring for unstable nodes. +For example, suppose you have a custom monitoring script or monitoring tool that queries Couchbase Server's statistics API. +You can have the script or tool find unstable nodes by performing the following steps: + +. Make a REST API call similar to the previous example to get a snapshot of the `cm_node_unreachable_total` metric over a time period. +. Compare the beginning and end values for each metric to spot new increments. +. Correlate the reports to see whether multiple peers have reported the same node as unavailable. + +If it finds an unstable node, have the script or tool alert an administrator so they can investigate. + +== Troubleshooting Unstable Nodes + +When you find an unstable node, you should investigate the causes of instability. +Nodes can increment their `cm_node_unreachable_total` metric for multiple reasons, not all of which point to an unstable node: + +* Planned downtime, such as graceful failovers. +If your alerts do not verify that the node is still up, then you may get these false positives. +* Network partitioning. +When network issues such as partitioning happen, groups of nodes report each other as unreachable. +To resolve, investigate the health of the network including routers, switches, and bridges. + +When multiple peers have connection issues with a specific node, you should investigate that node. +Node investigation can include looking at the Couchbase Server logs for more information. +This information can include messages telling you when other nodes noticed that the unstable node became available again. +The length of the outage may provide clues about the cause of the instability. + +Also examine the system log of the unstable node to look for potential hardware issues such as network port or disk errors. +Error messages often appear in the `syslog` or `dmesg` logs on Linux nodes. + +On Linux nodes, consider whether the kernel's TCP memory pool is under pressure or is full. +See xref:install:tcp_mem_settings.adoc[] for more information about the symptoms a kernel TCP/IP memory shortage. diff --git a/modules/manage/pages/monitor/set-up-prometheus-for-monitoring.adoc b/modules/manage/pages/monitor/set-up-prometheus-for-monitoring.adoc index 6ebfd69310..d81f607163 100644 --- a/modules/manage/pages/monitor/set-up-prometheus-for-monitoring.adoc +++ b/modules/manage/pages/monitor/set-up-prometheus-for-monitoring.adoc @@ -1,5 +1,5 @@ = Configure Prometheus to Collect Couchbase Metrics - +:page-topic-type: guide :description: Couchbase Server provides an API endpoint that helps you configure Prometheus to collect data from it. [abstract] diff --git a/modules/manage/pages/troubleshoot/common-errors.adoc b/modules/manage/pages/troubleshoot/common-errors.adoc index 178ffee678..2bbef7b67f 100644 --- a/modules/manage/pages/troubleshoot/common-errors.adoc +++ b/modules/manage/pages/troubleshoot/common-errors.adoc @@ -272,3 +272,31 @@ If the CPU supports split lock detection, a misaligned atomic memory access can The mitigation can artificially slow execution, causing a pronounced performance drop for the affected workload. For more information about how to resolve issues with split lock mitigation, see xref:install:install-splitlock-mitigation.adoc[] + +[#unstable-nodes] +== Unstable Nodes Causing Frequent Network Log Messages + +You may notice performance issues in your cluster or frequent errors in your logs related to nodes being unreachable. +For example, you may see messages like this in the Couchbase Server logs: + +[source,log] +---- +Node 'ns_1@node1.example.com' saw that node 'ns_1@node3.example.com' went down. Details: + [{nodedown_reason, net_tick_timeout}] +---- + +Later messages may show that the node is back up: + +[source,log] +---- +Node 'ns_1@node1.example.com' saw that node 'ns_1@node3.example.com' came up. Tags: [] +---- + +If you see these messages frequently reporting issues with the same node, but Couchbase Server does not perform an auto failover on it, the node may be unstable. + +An unstable node periodically becomes unavailable but recovers before the auto failover timeout expires. +An unstable node can cause performance issues for the cluster, even if it does not lead to automatic failover. +When a node is unreachable, other nodes in the cluster may experience increased latency as they attempt to re-establish communication with the unstable node. + +You can monitor for unstable nodes using the `cm_node_unreachable_total` metric. +See xref:learn:clusters-and-availability/unstable-nodes.adoc[] for more information about unstable nodes. diff --git a/modules/metrics-reference/attachments/cm_metrics_metadata.json b/modules/metrics-reference/attachments/cm_metrics_metadata.json index 83d38d9d50..92a0aaa874 100644 --- a/modules/metrics-reference/attachments/cm_metrics_metadata.json +++ b/modules/metrics-reference/attachments/cm_metrics_metadata.json @@ -11,6 +11,18 @@ "stability": "committed", "type": "counter" }, + "cm_alerts_triggered_total": { + "added": "8.1.0", + "help": "Number of times an alert has been triggered", + "labels": [ + { + "help": "Name of the alert", + "name": "type" + } + ], + "stability": "committed", + "type": "counter" + }, "cm_app_telemetry_curr_connections": { "added": "8.0.0", "help": "Number of active app telemetry connections", @@ -71,6 +83,12 @@ "stability": "committed", "type": "gauge" }, + "cm_bucket_autoreprovision_total": { + "added": "8.1.0", + "help": "Number of times buckets have been auto-reprovisioned. Only reported by the orchestrator node.", + "stability": "committed", + "type": "counter" + }, "cm_build_streaming_info_total": { "added": "7.0.0", "help": "Number of streaming requests processed", @@ -125,19 +143,55 @@ "help": "Encryption at rest status per data type (1 - encrypted, 0.5 - partially encrypted, 0 - unencrypted, -1 - unknown)", "labels": [ { - "help": "Encrypted data type (config, logs, audit, bucket_)", + "help": "Encrypted data type (config, logs, audit, other, bucket_)", "name": "data_type" } ], "stability": "internal", "type": "gauge" }, + "cm_encr_at_rest_deks_import_failures_total": { + "added": "8.1.0", + "help": "Total number of DEK import failures", + "labels": [ + { + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", + "name": "type" + } + ], + "stability": "internal", + "type": "counter" + }, + "cm_encr_at_rest_deks_import_skipped_total": { + "added": "8.1.0", + "help": "Total number of DEK import skipped (because it already exists)", + "labels": [ + { + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", + "name": "type" + } + ], + "stability": "internal", + "type": "counter" + }, + "cm_encr_at_rest_deks_imported_total": { + "added": "8.1.0", + "help": "Total number of DEK imported", + "labels": [ + { + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", + "name": "type" + } + ], + "stability": "internal", + "type": "counter" + }, "cm_encr_at_rest_deks_in_use": { "added": "8.0.0", "help": "Number of data keys in use per data type", "labels": [ { - "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, bucketDek_)", + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", "name": "type" } ], @@ -149,7 +203,7 @@ "help": "Total number drop DEKs events (when some DEK expires and the system tries to stop using that DEK by re-encrypting data)", "labels": [ { - "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, bucketDek_)", + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", "name": "type" } ], @@ -161,7 +215,7 @@ "help": "Total number of data key generation failures", "labels": [ { - "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, bucketDek_)", + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", "name": "type" } ], @@ -173,7 +227,31 @@ "help": "Total number of successful data key generation events", "labels": [ { - "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, bucketDek_)", + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", + "name": "type" + } + ], + "stability": "internal", + "type": "counter" + }, + "cm_encr_at_rest_retire_key_events_total": { + "added": "8.1.0", + "help": "Total number of successful key retirement events", + "labels": [ + { + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", + "name": "type" + } + ], + "stability": "internal", + "type": "counter" + }, + "cm_encr_at_rest_retire_key_failures_total": { + "added": "8.1.0", + "help": "Total number of key retirement failures", + "labels": [ + { + "help": "Data encryption key (DEK) type (configDek, logDek, auditDek, otherDek, bucketDek_)", "name": "type" } ], @@ -264,6 +342,32 @@ ], "type": "counter" }, + "cm_fusion_bucket_state_timestamp_seconds": { + "added": "8.1.0", + "help": "Timestamp when bucket entered the fusion state", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + }, + { + "help": "bucket fusion state (enabled/disabling/disabled/stopped/stopping)", + "name": "state" + } + ], + "type": "gauge" + }, + "cm_fusion_state_timestamp_seconds": { + "added": "8.1.0", + "help": "Timestamp when fusion entered the state", + "labels": [ + { + "help": "fusion state (enabling/enabled/disabling/disabled/stopped/stopping)", + "name": "state" + } + ], + "type": "gauge" + }, "cm_gc_duration_seconds": { "added": "7.6.0", "help": "Time to perform erlang garbage collection", @@ -403,6 +507,18 @@ "stability": "internal", "type": "counter" }, + "cm_lighthouse_telemetry_sends_total": { + "added": "7.6.12", + "help": "Number of times lighthouse telemetry sends were attempted", + "labels": [ + { + "help": "Whether the report was a success or a failure", + "name": "result" + } + ], + "stability": "internal", + "type": "counter" + }, "cm_logs_total": { "added": "7.1.0", "help": "Total number of logs logged", @@ -542,6 +658,21 @@ ], "type": "counter" }, + "cm_node_unreachable_total": { + "added": "7.6.11", + "help": "Total number of times the node identified by the node label was reported as unreachable. Depending on the reason, the notification may be immediate (for example, connection closed) or delayed (for example, tick timeout). This can help identify intermittent network connectivity issues that may not trigger auto-failover.", + "labels": [ + { + "help": "The node that is unreachable", + "name": "node" + }, + { + "help": "The erlang provided reason for the node being unreachable", + "name": "reason" + } + ], + "type": "counter" + }, "cm_ns_config_merger_queue_len_1m_max": { "added": "7.0.0", "help": "Length of the ns_config merger queue", @@ -803,6 +934,44 @@ "type": "gauge", "unit": "bytes" }, + "couch_spatial_data_size": { + "added": "7.0.0", + "help": "Size of object data for spatial views", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + } + ], + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "couch_spatial_disk_size": { + "added": "7.0.0", + "help": "Amount of disk space occupied by spatial views", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + } + ], + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "couch_spatial_ops": { + "added": "7.0.0", + "help": "Spatial operations", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + } + ], + "stability": "committed", + "type": "gauge" + }, "couch_views_actual_disk_size": { "added": "7.0.0", "help": "Amount of disk space used by Views data", @@ -816,6 +985,44 @@ "type": "gauge", "unit": "bytes" }, + "couch_views_data_size": { + "added": "7.0.0", + "help": "Size of object data for views", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + } + ], + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "couch_views_disk_size": { + "added": "7.0.0", + "help": "Amount of disk space occupied by views", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + } + ], + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "couch_views_ops": { + "added": "7.0.0", + "help": "View operations", + "labels": [ + { + "help": "Name of the bucket associated with the stat", + "name": "bucket" + } + ], + "stability": "committed", + "type": "gauge" + }, "sdk_invalid_metric_total": { "added": "8.0.0", "help": "Number of invalid metrics received from app telemetry clients", diff --git a/modules/metrics-reference/attachments/fts_metrics_metadata.json b/modules/metrics-reference/attachments/fts_metrics_metadata.json index 05115734a0..7803c24f9c 100644 --- a/modules/metrics-reference/attachments/fts_metrics_metadata.json +++ b/modules/metrics-reference/attachments/fts_metrics_metadata.json @@ -150,6 +150,11 @@ "type": "counter", "uiName": "Search Docs" }, + "fts_frees": { + "added": "8.1.0", + "help": "Cumulative count of heap objects freed", + "type": "counter" + }, "fts_global_query_timer_count": { "added": "8.0.0", "help": "The number of query timer events received at the global query endpoint", @@ -260,6 +265,31 @@ ], "type": "gauge" }, + "fts_heap_alloc": { + "added": "8.1.0", + "help": "Bytes of allocated heap objects currently in use", + "type": "gauge" + }, + "fts_heap_idle": { + "added": "8.1.0", + "help": "Bytes in idle (unused) heap spans", + "type": "gauge" + }, + "fts_heap_inuse": { + "added": "8.1.0", + "help": "Bytes in non-idle heap spans", + "type": "gauge" + }, + "fts_heap_released": { + "added": "8.1.0", + "help": "Bytes of physical memory returned to the OS", + "type": "gauge" + }, + "fts_mallocs": { + "added": "8.1.0", + "help": "Cumulative count of heap objects allocated", + "type": "counter" + }, "fts_meter_cu_total": { "added": "7.5.0", "help": "The number of Compute Units (CUs) recorded.", @@ -345,6 +375,11 @@ "uiName": "RAM Used by Search", "unit": "bytes" }, + "fts_num_cgocalls": { + "added": "8.1.0", + "help": "Total number of CGo calls made by the FTS process since startup", + "type": "counter" + }, "fts_num_files_on_disk": { "added": "7.2.0", "help": "The number of files on disk for an index", @@ -357,6 +392,11 @@ "type": "gauge", "uiName": "Search Disk Files" }, + "fts_num_goroutines": { + "added": "8.1.0", + "help": "Current number of goroutines running in the FTS process", + "type": "gauge" + }, "fts_num_indexes": { "added": "8.0.0", "help": "Number of search indexes in the cluster", @@ -793,7 +833,7 @@ }, "fts_total_queries": { "added": "7.2.0", - "help": "The number of full text queries per second for an index", + "help": "The number of search queries for an index", "labels": [ "bucket", "scope", @@ -909,6 +949,11 @@ "type": "counter", "unit": "nanoseconds" }, + "fts_total_scan_plus_queries_kv_errors": { + "added": "8.1.0", + "help": "Total number of KV errors encountered during scan plus queries", + "type": "counter" + }, "fts_total_synonym_searches": { "added": "8.0.0", "help": "Total bleve synonym search operations", @@ -944,6 +989,16 @@ ], "type": "counter" }, + "fts_total_vector_indexes_in_cpu": { + "added": "8.1.0", + "help": "The total number of segmented vector indexes currently loaded in CPU memory", + "type": "gauge" + }, + "fts_total_vector_indexes_in_gpu": { + "added": "8.1.0", + "help": "The total number of segmented vector indexes currently loaded in GPU memory", + "type": "gauge" + }, "fts_total_vectors": { "added": "7.6.1", "help": "The total number of vectors indexed", diff --git a/modules/metrics-reference/attachments/goxdcr_metrics_metadata.json b/modules/metrics-reference/attachments/goxdcr_metrics_metadata.json index e88357a2c5..45ab299913 100644 --- a/modules/metrics-reference/attachments/goxdcr_metrics_metadata.json +++ b/modules/metrics-reference/attachments/goxdcr_metrics_metadata.json @@ -339,6 +339,30 @@ "stability": "committed", "type": "counter" }, + "xdcr_cng_col_not_found_total": { + "added": "8.1.0", + "help": "Number of times a document failed to be replicated because the target collection was not found", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "committed", + "type": "counter" + }, + "xdcr_cng_scope_not_found_total": { + "added": "8.1.0", + "help": "Number of times a document failed to be replicated because the target scope was not found", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "committed", + "type": "counter" + }, "xdcr_data_merge_failed_bytes": { "added": "7.0.0", "help": "Amount of data failed to merge as part of Source custom conflict-resolution", @@ -746,25 +770,27 @@ }, "xdcr_docs_sent_with_subdoc_delete_total": { "added": "7.6.6", - "help": "The number of deletes issued using subdoc command instead of delete_with_meta to avoid cas rollback on target", + "help": "The number of deletes issued using subdoc (or MutateWithMeta) command instead of delete_with_meta to avoid cas rollback on target", "labels": [ "sourceBucketName", "targetClusterUUID", "targetBucketName", "pipelineType" ], + "notes": "MutateWithMeta is used when both source and target cluster are 8.1+. Subdoc command is used otherwise", "stability": "committed", "type": "counter" }, "xdcr_docs_sent_with_subdoc_set_total": { "added": "7.6.6", - "help": "The number of sets issued using subdoc command instead of set_with_meta to avoid cas rollback on target", + "help": "The number of sets issued using subdoc (or MutateWithMeta) command instead of set_with_meta to avoid cas rollback on target", "labels": [ "sourceBucketName", "targetClusterUUID", "targetBucketName", "pipelineType" ], + "notes": "MutateWithMeta is used when both source and target cluster are 8.1+. Subdoc command is used otherwise", "stability": "committed", "type": "counter" }, @@ -927,6 +953,198 @@ "stability": "internal", "type": "counter" }, + "xdcr_grpc_aborted_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that were aborted", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_already_exists_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed because resource already exists. A resource could be a document, collection, scope, or bucket", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_cancelled_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that were cancelled", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_data_loss_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to data loss", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_deadline_exceeded_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to deadline exceeded", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_failed_precondition_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to failed precondition", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_internal_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to internal error", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_invalid_argument_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to invalid argument", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_not_found_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed because resource was not found. A resource could be a document, collection, scope, or bucket", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_out_of_range_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to out of range error", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_permission_denied_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to permission denied", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_resource_exhausted_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to resource exhausted", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_unauthenticated_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed due to authentication failure", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_unavailable_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed because service is unavailable", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_unimplemented_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that failed because operation is unimplemented", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, + "xdcr_grpc_unknown_total": { + "added": "8.1.0", + "help": "Number of GRPC requests that returned unknown error", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "internal", + "type": "counter" + }, "xdcr_guardrail_data_size_total": { "added": "7.6.0", "help": "The number of writes that target rejected because each target data node is holding too much data", @@ -1026,6 +1244,20 @@ "stability": "committed", "type": "counter" }, + "xdcr_metadata_transferred_bytes": { + "added": "8.1.0", + "help": "The total amount of data transferred to and from target that is used for source side conflict resolution that is not the actual document replicated", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "notes": "This is metadata that is transferred as part of GET_META, or SubdocGet command", + "stability": "internal", + "type": "counter", + "unit": "bytes" + }, "xdcr_mobile_docs_filtered_total": { "added": "7.6.0", "help": "Total number of documents filtered and not replicated because the documents were mobile records", @@ -1038,6 +1270,18 @@ "stability": "committed", "type": "counter" }, + "xdcr_non_local_mutations_skipped_total": { + "added": "8.0.2", + "help": "Number of document mutations that were not batched for replication to Target because they did not qualify as 'local' for the 'forwardLocalOnly' replication", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "stability": "committed", + "type": "counter" + }, "xdcr_num_checkpoints_total": { "added": "7.0.0", "help": "The number of times checkpoint operation has completed successfully since this XDCR process instance is made aware of this replication", @@ -1119,6 +1363,16 @@ "stability": "committed", "type": "gauge" }, + "xdcr_remote_cluster_monitoring_metadata_transferred_bytes": { + "added": "8.1.0", + "help": "The total size of monitoring metadata sent and received to and from the remote cluster", + "labels": [ + "targetClusterUUID" + ], + "stability": "internal", + "type": "counter", + "unit": "bytes" + }, "xdcr_resp_wait_time_seconds": { "added": "7.0.0", "help": "The rolling average amount of time it takes from when a MemcachedRequest is created to be ready to route to an outnozzle to the time that the response has been heard back from the target node after a successful write", @@ -1244,6 +1498,18 @@ "type": "gauge", "unit": "bytes" }, + "xdcr_source_cluster_heartbeat_recv_bytes": { + "added": "8.1.0", + "help": "For a given source cluster, the size of the accumulated heartbeat messages received from this cluster", + "labels": [ + "sourceClusterUUID", + "sourceClusterName" + ], + "notes": "One source node will be responsible to send heartbeat to one target node. This stats will accumulate only if this particular node received data", + "stability": "internal", + "type": "counter", + "unit": "bytes" + }, "xdcr_source_sync_xattr_removed_total": { "added": "7.6.6", "help": "Number of mutations with source mobile extended attributes removed", @@ -1280,6 +1546,20 @@ "stability": "internal", "type": "counter" }, + "xdcr_sys_metadata_transferred_bytes": { + "added": "8.1.0", + "help": "The total amount of data transferred to and from target that is not related to document but within a context of a pipeline", + "labels": [ + "sourceBucketName", + "targetClusterUUID", + "targetBucketName", + "pipelineType" + ], + "notes": "This is metadata such as checkpoint manager used as part of checkpointing operation of a pipeline. Any other stats outside the context of a replication will not be accounted here. The metric will be re-initialized to 0 when a paused pipeline is resumed. The metadata checkpoint from the act of pausing a pipeline will not be accounted.", + "stability": "internal", + "type": "counter", + "unit": "bytes" + }, "xdcr_system_events_received_from_dcp_total": { "added": "7.6.0", "help": "The number of system events received from source data service", diff --git a/modules/metrics-reference/attachments/index_metrics_metadata.json b/modules/metrics-reference/attachments/index_metrics_metadata.json index 877ce46e5c..96dc374b68 100644 --- a/modules/metrics-reference/attachments/index_metrics_metadata.json +++ b/modules/metrics-reference/attachments/index_metrics_metadata.json @@ -235,6 +235,26 @@ "help": "Average index scan rate across all indexes, for this node", "type": "gauge" }, + "index_num_bhive_dense_indexes": { + "added": "8.1.0", + "help": "Total number of bhive indexes without sparse vector, located on this node", + "type": "gauge" + }, + "index_num_bhive_sparse_indexes": { + "added": "8.1.0", + "help": "Total number of bhive indexes with sparse vector, located on this node", + "type": "gauge" + }, + "index_num_composite_dense_indexes": { + "added": "8.1.0", + "help": "Total number of composite indexes without sparse vector, located on this node", + "type": "gauge" + }, + "index_num_composite_sparse_indexes": { + "added": "8.1.0", + "help": "Total number of composite indexes with sparse vector, located on this node", + "type": "gauge" + }, "index_num_diverging_replica_indexes": { "added": "8.0.0", "help": "Number of index partitions with diverging replica item counts.", @@ -291,6 +311,12 @@ ], "type": "counter" }, + "index_num_lost_replica_indexes": { + "added": "8.1.0", + "help": "Number of index partitions with atleast one lost replica.", + "notes": "Valid only for replicated indexes.", + "type": "gauge" + }, "index_num_requests": { "help": "Number of scan requests received by the index service, for this index", "labels": [ @@ -358,6 +384,19 @@ "notes": "This metric is valid only for partitioned indexes.", "type": "gauge" }, + "index_partn_num_lost_replicas": { + "added": "8.1.0", + "help": "Set to the number of lost replicas, if the index partition has any lost replicas", + "labels": [ + "bucket", + "scope", + "collection", + "index", + "partition" + ], + "notes": "Valid only for replicated indexes", + "type": "gauge" + }, "index_raw_data_size": { "help": "Encoded, uncompressed size of the index data, for this index", "labels": [ diff --git a/modules/metrics-reference/attachments/kv_metrics_metadata.json b/modules/metrics-reference/attachments/kv_metrics_metadata.json index 9e754386be..d2980c4e94 100644 --- a/modules/metrics-reference/attachments/kv_metrics_metadata.json +++ b/modules/metrics-reference/attachments/kv_metrics_metadata.json @@ -76,12 +76,6 @@ "type": "gauge", "unit": "seconds" }, - "kv_clients": { - "added": "7.6.0", - "help": "The number of references to the bucket", - "stability": "committed", - "type": "gauge" - }, "kv_cmd_duration_seconds": { "added": "7.0.0", "help": "Per-opcode histogram of time taken to execute operations", @@ -199,6 +193,13 @@ "stability": "committed", "type": "gauge" }, + "kv_cookie_notification_histogram_seconds": { + "added": "7.6.10", + "help": "Histogram containing the time taken to schedule a notification for a cookie until it is run", + "stability": "committed", + "type": "histogram", + "unit": "seconds" + }, "kv_credit_cu_total": { "added": "7.6.0", "help": "Total Compute Units refunded for a bucket (CU was charged, but operation failed) since reset", @@ -217,6 +218,18 @@ "stability": "internal", "type": "counter" }, + "kv_curr_bucket_connections": { + "added": "8.1.0", + "help": "The current number of connections for this bucket", + "stability": "committed", + "type": "gauge" + }, + "kv_curr_bucket_connections_closing": { + "added": "8.1.0", + "help": "The current number of connections currently closing down for this bucket", + "stability": "committed", + "type": "gauge" + }, "kv_curr_connections": { "added": "7.0.0", "help": "The current number of connections. This includes user, system and daemon connections", @@ -385,6 +398,13 @@ "type": "histogram", "unit": "seconds" }, + "kv_dispatch_socket_histogram_seconds": { + "added": "7.6.10", + "help": "Histogram containing the time taken to dispatch a newly created socket to its worker thread", + "stability": "committed", + "type": "histogram", + "unit": "seconds" + }, "kv_domain_memory_used_bytes": { "added": "7.1.0", "help": "Current memory used in KV for primary/secondary domain", @@ -632,6 +652,7 @@ "kv_ep_cache_size": { "added": "7.0.0", "help": "Memory quota (in bytes) for this bucket.", + "long_description": "Provides the absolute maximum amount of memory, measured in bytes, allocated to a specific bucket on a single node. It represents the hard memory quota configured by the administrator, serving as the strict baseline for calculating critical thresholds like high and low watermarks. This value is critical for capacity planning.", "stability": "volatile", "type": "gauge" }, @@ -685,6 +706,7 @@ "kv_ep_checkpoint_memory_ratio": { "added": "7.0.0", "help": "Max ratio of the bucket quota that can be allocated in checkpoints. The system enters a TempOOM phase if hit.", + "long_description": "Provides the maximum percentage of the bucket's memory quota dedicated to checkpoints. When this ratio is hit, the system enters a temporary TempOOM phase and immediately triggers memory recovery to minimize the duration of TempOOM state. A checkpoint is a sequenced queue of mutations that acts as the single source of truth for both persistence and replication within a bucket. Persistence and replication consume from this queue independently, each progressing at its own pace without coordinating with the other. The checkpoint queue allow disk flusher and DCP consumers to read from the same data structure to ensure consistency. This value helps ensure efficient memory utilization.", "stability": "volatile", "type": "gauge" }, @@ -756,14 +778,14 @@ }, "kv_ep_commit_time_seconds": { "added": "7.0.0", - "help": "Number of milliseconds of most recent commit", + "help": "Number of microseconds of most recent commit", "stability": "committed", "type": "gauge", "unit": "seconds" }, "kv_ep_commit_time_total_seconds": { "added": "7.0.0", - "help": "Cumulative milliseconds spent committing", + "help": "Cumulative microseconds spent committing", "stability": "committed", "type": "gauge", "unit": "seconds" @@ -841,12 +863,6 @@ "stability": "volatile", "type": "gauge" }, - "kv_ep_couchstore_file_cache_max_size": { - "added": "7.0.0", - "help": "Maximum number of couchstore files that we will keep open. Default value is 30 * 1024 (i.e. one file for each vBucket and 30 Buckets - the supported limit).", - "stability": "volatile", - "type": "gauge" - }, "kv_ep_couchstore_midpoint_rollback_optimisation": { "added": "7.0.0", "help": "Should we have to rollback more than half of the seqnos seen by this vBucket we will instead rollback to 0 and re-stream from the active if set to true", @@ -936,6 +952,18 @@ "type": "gauge", "unit": "bytes" }, + "kv_ep_db_tombstones": { + "added": "7.6.10", + "help": "The number of tombstones in db files (currently tracked only in couchstore)", + "stability": "committed", + "type": "gauge" + }, + "kv_ep_dcp_active_stream_inline_checkpoint_item_limit": { + "added": "7.0.0", + "help": "When the number of items pending for an ActiveStream's cursor is less than or equal to this value, the stream will run checkpoint item extraction inline rather than scheduling the ActiveStreamCheckpointProcessorTask. This avoids task-scheduling latency for small numbers of items. Set to 0 to always schedule the task.", + "stability": "volatile", + "type": "gauge" + }, "kv_ep_dcp_backfill_byte_drain_ratio": { "added": "7.0.0", "help": "What ratio of the dcp_backfill_byte_limit must be drained for un-pausing a paused backfill", @@ -962,7 +990,7 @@ }, "kv_ep_dcp_backfill_idle_protection_enabled": { "added": "7.0.0", - "help": "When true, DCP backfills will be checked for progress. Any backfill which makes no progress for dcp_backfill_idle_limit_seconds will be subject to further checks. If the directory referenced by dbname is over dcp_backfill_idle_disk_threshold percent used and cancelling the backfill will free disk space, the scan cancels and the associated DCP stream will end with reason slow.", + "help": "When true, DCP backfills will be checked for progress. Any backfill which makes no progress for dcp_backfill_idle_limit_seconds will be subject to further checks. If the directory referenced by dbname is over dcp_backfill_idle_disk_threshold percent used and cancelling the backfill will free disk space, the scan cancels and the associated DCP stream will end with reason slow. This is ignored for emphemeral buckets", "stability": "volatile", "type": "gauge" }, @@ -978,6 +1006,43 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_dcp_cache_transfer_enabled": { + "added": "7.0.0", + "help": "Does the producer support a cache transfer?", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_dcp_cache_transfer_high_memory_backoff_duration": { + "added": "7.0.0", + "help": "The duration in floating point seconds to snooze the CacheTransferTask when memory pressure is present and the task should back-off to avoid making memory usage worse (and wait for memory to reduce).", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_dcp_cache_transfer_max_batch_bytes": { + "added": "7.0.0", + "help": "Maximum batch size in bytes for batching cache transfer items. At least 1 item will included in a batch, so a value of 0 is always 1 item per batch.", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_dcp_cache_transfer_one_visit_per_step": { + "added": "7.0.0", + "help": "Set to false for simpler unit-testing. When true CacheTransferTask to visit the hash table many times per step, when false one item per task step", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_dcp_cache_transfer_read_bytes": { + "added": "8.1.0", + "help": "The number of bytes read by DCP cache transfer", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_ep_dcp_cache_transfer_visit_duration_ms": { + "added": "7.0.0", + "help": "The upper bound in milliseconds for the CacheTransferTask hash table visitor", + "stability": "volatile", + "type": "gauge" + }, "kv_ep_dcp_checkpoint_dequeue_limit": { "added": "7.0.0", "help": "The limit given to CheckpointManager::getNextItemsForDcp by ActiveStream", @@ -1420,9 +1485,16 @@ "type": "counter", "unit": "count" }, + "kv_ep_fusion_log_store_data_size_bytes": { + "added": "8.0.0", + "help": "Total size of the file data present in all the logs on FusionLogStore.", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, "kv_ep_fusion_log_store_garbage_size_bytes": { "added": "8.0.0", - "help": "Total size of the garbage data present on FusionLogStore.", + "help": "Total size of the garbage file data present on FusionLogStore.", "stability": "committed", "type": "gauge", "unit": "bytes" @@ -1469,9 +1541,9 @@ "type": "counter", "unit": "count" }, - "kv_ep_fusion_log_store_size_bytes": { + "kv_ep_fusion_log_store_summary_section_size_bytes": { "added": "8.0.0", - "help": "Total size of all the logs on FusionLogStore.", + "help": "Total size of the summary section of all logs on FusionLogStore.", "stability": "committed", "type": "gauge", "unit": "bytes" @@ -1539,6 +1611,20 @@ "type": "counter", "unit": "count" }, + "kv_ep_fusion_pending_upload_bytes_bytes": { + "added": "8.1.0", + "help": "Total amount of data not yet synced to FusionLogStore.", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_ep_fusion_sync_attempts": { + "added": "8.1.0", + "help": "Total number of sync attempts to Fusion including both successful and failed attempts.", + "stability": "committed", + "type": "counter", + "unit": "count" + }, "kv_ep_fusion_sync_failures": { "added": "8.0.0", "help": "Total number of times syncing data to Fusion failed.", @@ -1866,6 +1952,30 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_magma_bloom_filter_cache_hits": { + "added": "8.1.0", + "help": "Number of bloom filter lookups served from the in-memory bloom filter cache", + "stability": "committed", + "type": "counter" + }, + "kv_ep_magma_bloom_filter_cache_misses": { + "added": "8.1.0", + "help": "Number of bloom filter lookups that required a disk read", + "stability": "committed", + "type": "counter" + }, + "kv_ep_magma_bloom_filter_lookups_hit": { + "added": "8.1.0", + "help": "Number of bloom filter lookups where the filter correctly indicated the key did not exist", + "stability": "committed", + "type": "counter" + }, + "kv_ep_magma_bloom_filter_lookups_miss": { + "added": "8.1.0", + "help": "Number of bloom filter lookups where the filter returned a false positive", + "stability": "committed", + "type": "counter" + }, "kv_ep_magma_bloom_filter_mem_used_bytes": { "added": "7.1.0", "help": "Bloom filter memory usage in all versions of the LSM Trees", @@ -1894,6 +2004,13 @@ "type": "gauge", "unit": "bytes" }, + "kv_ep_magma_bytes_overwritten_bytes": { + "added": "8.1.0", + "help": "Logical bytes that were overwritten during write operations (size of replaced documents).", + "stability": "committed", + "type": "counter", + "unit": "bytes" + }, "kv_ep_magma_bytes_per_read_ratio": { "added": "7.1.0", "help": "Bytes read by get / number of Gets", @@ -1926,6 +2043,54 @@ "stability": "committed", "type": "gauge" }, + "kv_ep_magma_contbk_num_backup_hardlinks": { + "added": "8.1.0", + "help": "Number of file hardlinks that have occurred as a part of backup", + "stability": "committed", + "type": "counter", + "unit": "count" + }, + "kv_ep_magma_contbk_num_backups": { + "added": "8.1.0", + "help": "Number of Backups that have occurred", + "stability": "committed", + "type": "counter", + "unit": "count" + }, + "kv_ep_magma_contbk_num_bytes_written_bytes": { + "added": "8.1.0", + "help": "Number of bytes written as a part of the backup", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_ep_magma_contbk_num_failed_backups": { + "added": "8.1.0", + "help": "Number of Backups that have failed", + "stability": "committed", + "type": "counter", + "unit": "count" + }, + "kv_ep_magma_contbk_num_table_bytes_backedup_bytes": { + "added": "8.1.0", + "help": "Number of Table Bytes that have been backed up", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_ep_magma_contbk_num_write_ios": { + "added": "8.1.0", + "help": "Number of Write IOs that have occurred as a part of backup", + "stability": "committed", + "type": "counter", + "unit": "count" + }, + "kv_ep_magma_corruption_errors": { + "added": "8.1.0", + "help": "Number of corruption errors detected by Magma", + "stability": "committed", + "type": "gauge" + }, "kv_ep_magma_data_blocks_compressed_size": { "added": "7.2.0", "help": "Data blocks compressed size; actual size in storage", @@ -1976,6 +2141,12 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_magma_enable_data_block_autotuning": { + "added": "7.0.0", + "help": "Enable auto-tuning of data block size based on compression ratio.", + "stability": "volatile", + "type": "gauge" + }, "kv_ep_magma_enable_direct_io": { "added": "7.0.0", "help": "Using direct IO tells magma to bypass the file system cache when writing or reading sstables.", @@ -1988,6 +2159,12 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_magma_enable_index_block_autotuning": { + "added": "7.0.0", + "help": "Enable auto-tuning of index block size based on compression ratio.", + "stability": "volatile", + "type": "gauge" + }, "kv_ep_magma_enable_memory_optimized_writes": { "added": "7.0.0", "help": "When enabled, if copying a write batch into memtable results in exceeding the write cache quota, Magma avoids the copy and instead flushes the batch to disk on the writer thread itself. This tradeoffs an increase in write latency for reduced memory consumption and obeys quota limits. If copying a batch keeps us under the quota, Magma will to continue to copy and do the flush in background.", @@ -2024,12 +2201,6 @@ "stability": "committed", "type": "gauge" }, - "kv_ep_magma_flusher_thread_percentage": { - "added": "7.0.0", - "help": "Percentage of storage threads that are flusher threads (i.e. with a value of 20 we will allocate 4 (1/5th) of the storage threads to flushers and the remaining 16 (4/5ths) threads will be compactors).", - "stability": "volatile", - "type": "gauge" - }, "kv_ep_magma_flushes": { "added": "7.1.0", "help": "Number of write cache flushes performed", @@ -2049,15 +2220,33 @@ "type": "gauge", "unit": "ratio" }, - "kv_ep_magma_fusion_log_checkpoint_interval": { + "kv_ep_magma_fusion_logstore_fragmentation_threshold": { "added": "7.0.0", - "help": "The interval at which FusionFS should create a log checkpoint on the FusionMetadataStore and delete eligible logs from the FusionLogStore, in seconds.", + "help": "The threshold at which the fusion log store will perform garbage collection. This is a ratio between 0.0 and 1.0.", "stability": "volatile", "type": "gauge" }, - "kv_ep_magma_fusion_logstore_fragmentation_threshold": { + "kv_ep_magma_fusion_max_log_cleaning_size_ratio": { "added": "7.0.0", - "help": "The threshold at which the fusion log store will perform garbage collection. This is a ratio between 0.0 and 1.0.", + "help": "Minimum log segment size after which logs will be split. The ratio is a percentage of used log data size.", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_magma_fusion_max_log_size": { + "added": "7.0.0", + "help": "Upper cap for the effective log size, in bytes.", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_magma_fusion_max_num_log_files": { + "added": "7.0.0", + "help": "Base cap for maximum number of log files.", + "stability": "volatile", + "type": "gauge" + }, + "kv_ep_magma_fusion_max_upload_interval": { + "added": "7.0.0", + "help": "Maximum interval after which an upload will be permitted irrespective of upload thresholds, in seconds. This will be set to the smaller of the current value and 25% of persistent_metadata_purge_age.", "stability": "volatile", "type": "gauge" }, @@ -2190,21 +2379,27 @@ "type": "gauge", "unit": "bytes" }, + "kv_ep_magma_max_base_level_size": { + "added": "7.0.0", + "help": "Upper bound on the dynamic L0/L1 target size. The target scales with the bottom level; values above this are clamped.", + "stability": "volatile", + "type": "gauge" + }, "kv_ep_magma_max_checkpoints": { "added": "7.0.0", "help": "Maximum # of checkpoints retained for rollback.", "stability": "volatile", "type": "gauge" }, - "kv_ep_magma_max_default_storage_threads": { + "kv_ep_magma_max_level0_ttl": { "added": "7.0.0", - "help": "If the number of storage threads = 0, then we set the number of storage threads to this value and use magma_flusher_thread_percentage to determine the ratio of flusher and compactor threads.", + "help": "Maximum time (in seconds) that data is kept in level 0 before it is merged.", "stability": "volatile", "type": "gauge" }, - "kv_ep_magma_max_level_0_ttl": { + "kv_ep_magma_max_num_level0_tables": { "added": "7.0.0", - "help": "Maximum time (in seconds) that data is kept in level 0 before it is merged.", + "help": "Maximum number of L0 tables in the magma LSM trees.", "stability": "volatile", "type": "gauge" }, @@ -2232,6 +2427,12 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_magma_metaonly_gets": { + "added": "8.1.0", + "help": "Number of metadata-only get operations", + "stability": "committed", + "type": "gauge" + }, "kv_ep_magma_min_checkpoint_interval": { "added": "7.0.0", "help": "Minimum interval between two checkpoints; in seconds. Prevents excessive creation of checkpoints.", @@ -2244,6 +2445,12 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_magma_nonresident_bloom_filter_size": { + "added": "8.1.0", + "help": "Space taken up by bloom filters not currently in memory", + "stability": "committed", + "type": "gauge" + }, "kv_ep_magma_per_document_compression_enabled": { "added": "7.0.0", "help": "Apply Snappy compression to each document when persisted (magma only)", @@ -2298,6 +2505,18 @@ "stability": "committed", "type": "gauge" }, + "kv_ep_magma_readio_get": { + "added": "8.1.0", + "help": "Number of read IOs performed on the get path", + "stability": "committed", + "type": "counter" + }, + "kv_ep_magma_readio_set": { + "added": "8.1.0", + "help": "Number of read IOs performed on the set path", + "stability": "committed", + "type": "counter" + }, "kv_ep_magma_readioamp_ratio": { "added": "7.1.0", "help": "Number of read IOs performed by GetDocs divided by the number of GetDocs", @@ -2524,6 +2743,7 @@ "kv_ep_max_size": { "added": "7.0.0", "help": "Memory quota (in bytes) for this bucket.", + "long_description": "Provides the absolute maximum amount of memory, measured in bytes, allocated to a specific bucket on a single node. It represents the hard memory quota configured by the administrator, serving as the strict baseline for calculating critical thresholds like high and low watermarks. This value is critical for capacity planning.", "stability": "volatile", "type": "gauge" }, @@ -2568,6 +2788,7 @@ "kv_ep_mem_high_wat_percent": { "added": "7.0.0", "help": "Ratio of the Bucket Quota at which to place the high watermark. This is the maximum desired memory usage. This value should be lower than mutation_mem_ratio to avoid no memory errors.", + "long_description": "Provides the specific percentage of the total bucket memory quota that acts as the high watermark threshold. By default, the high watermark is set at 85% of the bucket's allocated memory. It represents the critical trigger point where the engine proactively initiates background memory management routines to evict data from RAM to disk until memory usage drops below the low watermark. This value is vital for identifying heavy memory pressure.", "stability": "volatile", "type": "gauge" }, @@ -2580,6 +2801,7 @@ "kv_ep_mem_low_wat_percent": { "added": "7.0.0", "help": "Ratio of the Bucket Quota at which to place the low watermark. This is the point to which to reduce the memory usage of the bucket after hitting the high watermark.", + "long_description": "Provides the specific percentage of the maximum bucket memory quota designated as the low watermark. By default it is set at 10% lower than the high watermark. It represents the target recovery threshold for the item pager, indicating the point at which continuous eviction from memory to disk ceases after a high watermark breach. This value ensures a healthy buffer of free memory.", "stability": "volatile", "type": "gauge" }, @@ -2615,9 +2837,16 @@ "stability": "volatile", "type": "gauge" }, + "kv_ep_monitor_task_interval": { + "added": "7.0.0", + "help": "Schedule interval (in seconds) for the MonitorTask.", + "stability": "volatile", + "type": "gauge" + }, "kv_ep_mutation_mem_ratio": { "added": "7.0.0", "help": "Ratio of the Bucket Quota that can be used before mutations return tmpOOMs", + "long_description": "Provides the precise percentage of the maximum bucket memory quota beyond which the engine will begin to reject frontend mutations with temporary OOM errors. It is set at a default of 93%. It represents a protective throttling threshold, indicating the system is nearing complete memory exhaustion and must temporarily block incoming writes. It is a dynamic value that can be modified. This value protects the node from allocating beyond the assigned bucket quota. It prevent crashes in the cases like high memory fragmentation where memcached memory usage is higher than logical allocation.", "stability": "volatile", "type": "gauge" }, @@ -2741,6 +2970,13 @@ "stability": "committed", "type": "gauge" }, + "kv_ep_pageable_mem_bytes": { + "added": "7.6.11", + "help": "Current pageable memory usage (used in paging management)", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, "kv_ep_pager_sleep_time_ms": { "added": "7.0.0", "help": "How long in milliseconds the ItemPager will sleep for when not being requested to run", @@ -2800,6 +3036,7 @@ "kv_ep_persistent_metadata_purge_age": { "added": "7.0.0", "help": "Age in seconds after which tombstones may be purged. Defaults to 3 days. Max of 60 days. If this is dynamically changed for a magma bucket then magma may not trigger compactions when it should, this can be avoided by running a full manual compaction after changing this parameter.", + "long_description": "Provides the configured time interval after which the persistent metadata of deleted items, known as tombstones, is permanently purged from disk storage. It represents the active policy for tombstone expiration, balancing robust replication consistency against disk space reclamation. This value is crucial for tuning storage overhead.", "stability": "volatile", "type": "gauge" }, @@ -2946,6 +3183,20 @@ "type": "gauge", "unit": "bytes" }, + "kv_ep_total_compressed_value_size_bytes": { + "added": "8.1.0", + "help": "The total size of document values that are compressed, including documents that are later expired or deleted.", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_ep_total_decompressed_value_size_bytes": { + "added": "8.1.0", + "help": "The total decompressed size of document values that are compressed, including documents that are later expired or deleted.", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, "kv_ep_total_deduplicated": { "added": "7.0.0", "help": "Total number of items de-duplicated when queued to CheckpointManager", @@ -3131,20 +3382,40 @@ "stability": "volatile", "type": "gauge" }, - "kv_ephemeral_vb_checkpoint_memory_overhead_bytes": { + "kv_ephemeral_vb_ht_memory_bytes": { "added": "7.6.0", - "help": "Total memory overhead of all checkpoints", + "help": "Total memory used by HashTable items", "stability": "internal", "type": "gauge", "unit": "bytes" }, - "kv_ephemeral_vb_ht_memory_bytes": { - "added": "7.6.0", - "help": "Total memory used by HashTable items", + "kv_file_chunk_read_bytes": { + "added": "8.1.0", + "help": "Total number of bytes read from the bucket using GetFileFragment", "stability": "internal", + "type": "counter", + "unit": "bytes" + }, + "kv_fusion_deferred_upload_bytes_bytes": { + "added": "8.1.0", + "help": "The amount of data Fusion knows is pending sync but has decided to defer in order to reduce the number of uploads to FusionLogStore", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_fusion_max_pending_upload_bytes_bytes": { + "added": "8.1.0", + "help": "Configuration value for the maximum amount of pending upload bytes across all volumes.", + "stability": "committed", "type": "gauge", "unit": "bytes" }, + "kv_fusion_max_pending_upload_bytes_lwm_ratio": { + "added": "8.1.0", + "help": "Configuration value for the proportion of max_pending_upload_bytes beyond which syncs for volumes with highest pending bytes are only allowed.", + "stability": "committed", + "type": "gauge" + }, "kv_fusion_migration_rate_limit_bytes": { "added": "8.0.0", "help": "The rate limit for fusion extent migration, in bytes per second.", @@ -3152,6 +3423,20 @@ "type": "gauge", "unit": "bytes" }, + "kv_fusion_num_migrator_threads_bytes": { + "added": "8.0.0", + "help": "The number of Fusion Migrator threads.", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_fusion_num_uploader_threads_bytes": { + "added": "8.0.0", + "help": "The number of Fusion Uploader threads.", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, "kv_fusion_sync_rate_limit_bytes": { "added": "8.0.0", "help": "The rate limit for fusion sync uploads, in bytes per second.", @@ -3195,6 +3480,13 @@ "type": "gauge", "unit": "bytes" }, + "kv_magma_compaction_rate_limit_bytes": { + "added": "8.1.0", + "help": "The I/O bandwidth in bytes per second that compactions across all shards in a node can consume", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, "kv_magma_compactions": { "added": "7.2.0", "help": "Count of Magma compactions", @@ -3204,6 +3496,18 @@ "stability": "committed", "type": "gauge" }, + "kv_magma_enable_compaction_dataonly_ratelimiting": { + "added": "8.1.0", + "help": "Limits rate-limiting to fragmentation-reduction compactions only. If disabled, all compactions are throttled", + "stability": "committed", + "type": "gauge" + }, + "kv_magma_flusher_thread_percentage": { + "added": "7.6.10", + "help": "Percent of magma flusher threads out of total magma threads", + "stability": "committed", + "type": "gauge" + }, "kv_magma_itr": { "added": "7.6.0", "help": "Number of items returned by iterators", @@ -3214,6 +3518,24 @@ "stability": "committed", "type": "gauge" }, + "kv_magma_max_default_storage_threads": { + "added": "7.6.10", + "help": "The number of total magma threads", + "stability": "committed", + "type": "gauge" + }, + "kv_magma_num_compactor_threads": { + "added": "7.6.11", + "help": "The number of magma compactor threads.", + "stability": "committed", + "type": "gauge" + }, + "kv_magma_num_flusher_threads": { + "added": "7.6.11", + "help": "The number of magma flusher threads.", + "stability": "committed", + "type": "gauge" + }, "kv_magma_write_bytes_bytes": { "added": "7.6.0", "help": "Bytes written by Magma flushes, compactions.", @@ -3249,6 +3571,7 @@ "kv_mem_used_bytes": { "added": "7.0.0", "help": "Engine's total memory usage", + "long_description": "Provides the most comprehensive view of bucket memory consumption. It is used for quota enforcement, eviction decisions, and monitoring memory pressure. It is calculated using jemalloc's ArenaMalloc. The metric includes (1) Item data (item metadata, keys, resident and non-resident values); (2) Structural overhead (checkpoint queues, persistence queues, DCP queues, hash table and collections/scope metadata); and (3) Component allocations (Magma storage buffers, bloom filters, durability monitor memory, arena allocator overhead and any other internal allocations).", "stability": "committed", "type": "gauge", "unit": "bytes" @@ -3286,18 +3609,6 @@ "stability": "internal", "type": "counter" }, - "kv_meter_ru_total": { - "added": "7.6.0", - "help": "Total Read Units used by a bucket since reset", - "stability": "internal", - "type": "counter" - }, - "kv_meter_wu_total": { - "added": "7.6.0", - "help": "Total Write Units used by a bucket since reset", - "stability": "internal", - "type": "counter" - }, "kv_num_high_pri_requests": { "added": "7.0.0", "help": "Num of async high priority requests", @@ -3334,6 +3645,19 @@ "stability": "committed", "type": "counter" }, + "kv_pager_deleted_bytes": { + "added": "7.6.11", + "help": "Number of bytes deleted by pager", + "stability": "committed", + "type": "gauge", + "unit": "bytes" + }, + "kv_pager_throttled": { + "added": "7.6.11", + "help": "Total number of times pager has been throttled", + "stability": "committed", + "type": "counter" + }, "kv_read_bytes": { "added": "7.0.0", "help": "The number bytes received from all connections bound to this bucket", @@ -3359,6 +3683,12 @@ "stability": "committed", "type": "gauge" }, + "kv_ru_total": { + "added": "8.1.0", + "help": "Total Read Units used by a bucket since reset", + "stability": "internal", + "type": "counter" + }, "kv_stat_timings_mem_usage_bytes": { "added": "7.1.0", "help": "The memory footprint for tracing times spent processing stat requests", @@ -3401,6 +3731,12 @@ "type": "gauge", "unit": "bytes" }, + "kv_subdoc_offload_count": { + "added": "8.1.0", + "help": "The number of subdoc operations executed in the non-IO thread pool", + "stability": "committed", + "type": "gauge" + }, "kv_subdoc_ops": { "added": "7.0.0", "help": "The number of subdoc operations", @@ -3452,11 +3788,24 @@ "stability": "internal", "type": "counter" }, - "kv_throttle_seconds_total": { - "added": "7.6.0", - "help": "Total time spent throttling requests for a bucket since reset", + "kv_throttle_duration_seconds": { + "added": "8.1.0", + "help": "Histogram of throttle wait times for a bucket since reset", "stability": "internal", - "type": "counter" + "type": "histogram", + "unit": "seconds" + }, + "kv_throttle_hard_limit": { + "added": "8.1.0", + "help": "Current hard throttle limit for a bucket (units per second).", + "stability": "internal", + "type": "gauge" + }, + "kv_throttle_reserved": { + "added": "8.1.0", + "help": "Current reserved throttle limit for a bucket (units per second).", + "stability": "internal", + "type": "gauge" }, "kv_time_seconds": { "added": "7.0.0", @@ -3465,6 +3814,12 @@ "type": "gauge", "unit": "seconds" }, + "kv_tls_certificate_verification_problems": { + "added": "totoro", + "help": "The number of times TLS certificate verification has found issues with the certificate presented by the client during connection establishment", + "stability": "committed", + "type": "gauge" + }, "kv_total_connections": { "added": "7.0.0", "help": "The total number of connections to this system since the process started (or reset)", @@ -3828,5 +4183,11 @@ "stability": "committed", "type": "gauge", "unit": "bytes" + }, + "kv_wu_total": { + "added": "8.1.0", + "help": "Total Write Units used by a bucket since reset", + "stability": "internal", + "type": "counter" } } diff --git a/modules/metrics-reference/attachments/n1ql_metrics_metadata.json b/modules/metrics-reference/attachments/n1ql_metrics_metadata.json index 71f4895467..a9ea5ff49b 100644 --- a/modules/metrics-reference/attachments/n1ql_metrics_metadata.json +++ b/modules/metrics-reference/attachments/n1ql_metrics_metadata.json @@ -89,6 +89,11 @@ "help": "Count of CAS mismatch errors", "type": "counter" }, + "n1ql_chats": { + "added": "8.1.0", + "help": "Total number of natural language chats.", + "type": "counter" + }, "n1ql_counter_cu_total": { "added": "7.6.0", "help": "The number of distinct operations recording Compute Units (CUs) with Regulator.", @@ -235,6 +240,11 @@ "type": "counter", "uiName": "N1QL Error Rate" }, + "n1ql_external_scans": { + "added": "8.1.0", + "help": "Total number of external collection scans.", + "type": "counter" + }, "n1ql_ffdc_manual": { "added": "7.6.6", "help": "The total number of ffdc captures triggered due to manual invocation of ffdc admin api", @@ -366,6 +376,11 @@ "help": "The STDDEV latency of SQL++ Hyperscale VECTOR requests.", "type": "gauge" }, + "n1ql_index_hint_not_followed": { + "added": "7.6.11", + "help": "The total number of index hints not followed", + "type": "counter" + }, "n1ql_index_scans": { "added": "7.0.0", "help": "Total number of secondary index scans.", @@ -712,11 +727,26 @@ "uiName": "Query Execution Time", "unit": "nanoseconds" }, + "n1ql_spills_merge": { + "added": "7.6.12", + "help": "Number of merge operations that have spilled to disk.", + "type": "counter" + }, "n1ql_spills_order": { - "added": "8.0.0", + "added": "7.6.12", "help": "Number of order by operations that have spilled to disk.", "type": "counter" }, + "n1ql_spills_seq_scan": { + "added": "7.6.12", + "help": "Number of sequential scans that have spilled to disk.", + "type": "counter" + }, + "n1ql_spills_update_statistics": { + "added": "7.6.12", + "help": "Number of statistics update operations that have spilled to disk.", + "type": "counter" + }, "n1ql_svi_request_timer_15m_rate": { "added": "8.0.0", "help": "The 15m.rate latency of SQL++ FTS VECTOR requests.", diff --git a/modules/metrics-reference/partials/metrics.hbs b/modules/metrics-reference/partials/metrics.hbs index 324647f7a6..b0e254d998 100644 --- a/modules/metrics-reference/partials/metrics.hbs +++ b/modules/metrics-reference/partials/metrics.hbs @@ -22,7 +22,7 @@ https://prometheus.io/docs/practices/naming/#base-units[unit] (if present). {{#each this}} {{#if (ne stability "internal")}} -|`{{@key}}` +|[[{{@key}}]]`{{@key}}` {nbsp}{nbsp}{nbsp} [.edition]##{{or added "7.0.0"}}## {{~#with deprecated}}[.deprecated]##Deprecated in {{this}}##{{/with~}} diff --git a/modules/rest-api/pages/rest-magma-compression-per-bucket.adoc b/modules/rest-api/pages/rest-magma-compression-per-bucket.adoc new file mode 100644 index 0000000000..a412dd1562 --- /dev/null +++ b/modules/rest-api/pages/rest-magma-compression-per-bucket.adoc @@ -0,0 +1,133 @@ += Magma Compression +:description: You can set and view the compression algorithms for individual Magma buckets using the following REST APIs. + + +[abstract] +{description} + +Compression settings can be set for an existing bucket. +This requires `Full Admin`, `Cluster Admin` roles, or the `Bucket Admin` role for the specified bucket. + +== HTTP methods and URIs + +[source] +---- +GET /pools/default/buckets/ +POST /pools/default/buckets/ +---- + +== Parameters +The following parameters are available to the REST API +[cols="4,3,3"] +|=== +| Parameter | Type | Description + +| `magmaEnableIndexBlockAutotuning` +| Boolean +| Enable auto-tuning of Magma index block size based on the compression ratio + +Automatically adjusts the pre-compression block-accumulation size so the post-compression (physical) index block size stays close to the configured target block size. + +|`magmaEnableDataBlockAutotuning` +| Boolean +| Enable auto-tuning of Magma data block size based on the compression ratio + +|`magmaIndexCompressionAlgo` +| `snappy`, `lz4`, `none`, `zstd`, or `zstd_` where `` is an integer from 1 to 22. + +| Configure the block compression algorithm for the index blocks. + +| `magmaDataCompressionAlgo` +| `snappy`, `lz4`, `none`, `zstd`, or `zstd_` where `` is an integer from 1 to 22. +| Configure the block compression algorithm for the data blocks. + +| `magmaCompacteddataCompressionAlgo` +| `snappy`, `lz4`, `none`, `zstd`, or `zstd_` where `` is an integer from 1 to 22. +| Configure the block compression algorithm for the data blocks after compaction. + +Allows colder data to be compressed with a higher compression ratio using `zstd`. +This compression also is scheduled in background compaction threads. + +|=== + +== `Curl` Syntax + +[source, shell] +---- +curl -u : -X GET \ + :8091/pools/default/buckets/ + +curl -u : -X POST \ + :8091//pools/default/buckets/ \ + -d magmaEnableIndexBlockAutotuning=true|false \ + -d magmaEnableDataBlockAutotuning=true|false \ + -d magmaIndexCompressionAlgo=snappy|lz4|none|zstd|zstd_ \ + -d magmaDataCompressionAlgo=snappy|lz4|none|zstd|zstd_ \ + -d magmaCompacteddataCompressionAlgo=snappy|lz4|none|zstd|zstd_ \ + +---- + +== Responses + +If the call is successful, `200 OK` is given. + +If the operation is performed on a bucket that does not exist, +the REST service responds with a `404 (Object not found)` error. + +Sending the request with an invalid parameter value (sending a number when a Boolean value is expected, for example), returns a `400 (Bad Request)` response. + +You can find the precise nature of the problem by examining the payload in the response: + +[source, jsonlines] +---- +{ +"errors": { + "magmaEnableDataBlockAutotuning": "Value \"ten\" must be a boolean value (true/false, on/off)" + }, + +} +---- + +[NOTE] +==== +Errors in the parameter name result in no change in any of the parameter values, but the REST service responds with `200 (OK)`: + + +==== + + +== Examples + +.Retrieve parameter settings for the bucket. +[source, shell] +---- +curl -u Administrator:password -X GET \ + localhost:8091/pools/default/buckets/travel-sample | jq +---- + +This retrieves all the parameters in the bucket as a JSON string. +If you want to retrieve a parameter or list of parameters, you can add them to `jq` pipe: + +[source, shell] +---- +curl -u Administrator:password -X GET \ + localhost:8091/pools/default/buckets/travel-sample | jq \ + '.magmaEnableDataBlockAutotuning,.magmaEnableDataBlockAutotuning,.magmaIndexCompressionAlgo,.magmaDataCompressionAlgo,.magmaCompacteddataCompressionAlgo' +---- + +.Enable auto-tuning of the bucket index block. +[source, shell] +---- +curl -u Administrator:password -X POST \ + localhost:8091/pools/default/buckets/travel-sample \ + -d magmaEnableIndexBlockAutotuning=true +---- + +.Set the data compression algorithm +[source,shell] +---- +curl -u Administrator:password -X POST \ + localhost:8091/pools/default/buckets/travel-sample \ + -d magmaDataCompressionAlgo=snappy +---- + diff --git a/modules/rest-api/pages/rest-xdcr-adv-settings.adoc b/modules/rest-api/pages/rest-xdcr-adv-settings.adoc index 40fa6a46fb..e8165e5a18 100644 --- a/modules/rest-api/pages/rest-xdcr-adv-settings.adoc +++ b/modules/rest-api/pages/rest-xdcr-adv-settings.adoc @@ -20,15 +20,15 @@ GET /settings/replications/ [#description] == Description -Used with the `POST` method, the URIs respectively change global settings for _all_ replications; and for _a specific_ replication, which is referenced by its `settings_URI`. -The `settings_URI` comprises the _id_ for the replication, and can be retrieved by means of the `GET /pools/default/tasks` method and URI: see xref:rest-api:rest-get-cluster-tasks.adoc[Getting Cluster Tasks]. +Used with the `POST` method, the URIs respectively change global settings for all replications; and for a specific replication, which is referenced by its `settings_URI`. +The `settings_URI` comprises the id for the replication, and can be retrieved by means of the `GET /pools/default/tasks` method and URI: see xref:rest-api:rest-get-cluster-tasks.adoc[Getting Cluster Tasks]. The global settings are the default values used if settings are not specified during the creation of a particular replication. If settings are specified for a particular replication, the specified settings overwrite the global settings. -If the global settings are themselves changed, existing replications are not affected: only replications created _after_ the change made to the global settings receive the updated global settings. +If the global settings are themselves changed, existing replications are not affected: only replications created after the change made to the global settings receive the updated global settings. -Used with the `GET` method, the URIs respectively retrieve global settings for _all_ replications; and for _a specific_ replication, which is referenced by its `settings_URI`. +Used with the `GET` method, the URIs respectively retrieve global settings for all replications; and for a specific replication, which is referenced by its `settings_URI`. @@ -126,6 +126,7 @@ curl -u Administrator:password -X GET http://localhost:8091/settings/replication If successful, the call returns an object similar to the following: +[source,jsonlines] ---- { "cLogConnPoolGCIntervalMs": 60000, @@ -133,8 +134,10 @@ If successful, the call returns an object similar to the following: "cLogConnPoolReapIntervalMs": 120000, "cLogErrorTimeWindowMs": 120000, "cLogMaxErrorCount": 10, + "cLogMonitorDuration": 0, "cLogNetworkRetryCount": 5, "cLogNetworkRetryIntervalMs": 2000, + "cLogPauseReplThreshold": 0, "cLogPoolGetTimeoutMs": 5000, "cLogQueueCapacity": 6000, "cLogReattemptDurationMs": 600000, @@ -143,11 +146,17 @@ If successful, the call returns an object similar to the following: "casDriftThresholdSecs": 3900, "checkpointInterval": 600, "ckptSvcCacheEnabled": true, + "cngConnCount": 2, + "cngQueueSize": 1000, + "cngRPCDeadlineMs": 5000, + "cngWorkerCount": 500, "collectionsOSOMode": true, + "componentEventsChanLength": 10000, "compressionType": "Auto", - "conflictLogging": {}, "dcpEnablePurgeRollback": false, + "dcpFlowControlThrottle": 100, "desiredLatency": 50, + "devReplOpts": "", "disableHlvBasedShortCircuit": false, "docBatchSizeKb": 2048, "failureRestartInterval": 10, @@ -155,16 +164,18 @@ If successful, the call returns an object similar to the following: "filterBypassExpiry": false, "filterBypassUncommittedTxn": false, "filterDeletion": false, + "filterDeletionsWithExpression": false, "filterExpiration": false, + "filterExpirationsWithExpression": false, "genericServicesLogLevel": { - < ... diagnostic items cut out due to length ... > - }, + // < ... diagnostic items cut out due to length ... > + }, "goGC": 100, "goMaxProcs": 4, "jsFunctionTimeoutMs": 20000, "logLevel": "Info", "mergeFunctionMapping": {}, - "mobile": "Off", + "minHLVHistoryLenForMobile": 5, "networkUsageLimit": 0, "optimisticReplicationThreshold": 256, "preCheckCasDriftThresholdHours": 8760, @@ -176,7 +187,6 @@ If successful, the call returns an object similar to the following: "retryOnRemoteAuthErrMaxWaitSec": 360, "skipReplSpecAutoGc": false, "sourceNozzlePerNode": 2, - "targetTopologyLogFrequency": 1800, "statsInterval": 1000, "targetNozzlePerNode": 2, "targetTopologyLogFrequency": 1800, @@ -423,7 +433,7 @@ curl -X POST -u Administrator:password http://localhost:8091/ -d m For information about _XDCR with Sync Gateway mobile clusters in a bi-directional, active-active replication_, see xref:learn:clusters-and-availability/xdcr-active-active-sgw.adoc[XDCR Active-Active with Sync Gateway]. -===== Change Settings for XDCR Generic Services Log Levels +=== Change Settings for XDCR Generic Services Log Levels The following example modifies the log levels for XDCR Generic Services, for a specific replication. Usually, you modify the log levels only when requested by Couchbase Support. @@ -519,6 +529,21 @@ This setting can only be established for and retrieved from an individual replic | Whether the replication optimizes performance; by streaming, from a source bucket, mutations that could be out of order, in terms of sequence-number. Default is true. +| `componentEventsChanLength` +| Integer (1000 to 10000) +a| Default: 10000 + +Sets the default length of the channels being used by event-listeners to buffer various internal events before processing. + + +NOTE: By decreasing this value, the replication throughput will be throttled in favour of a lower memory footprint. +See xref:xdcr-reference:xdcr-lowering-memory-footprint.adoc[] for more information. + + + +This setting can be established and retrieved either for an individual replication or globally. + + | `compressionType` | String | Default: `Auto`. @@ -533,7 +558,23 @@ This setting can be established and retrieved either for an individual replicati This configuration setting defines objects/parameters and options used to control how conflicts are logged during an XDCR replication. -For more information, see xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#configure-conflictlogging-settings[Enabling and Configuring Conflict Logging]. +For more information, see xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#configure-conflictlogging-settings[Enabling and Configuring Conflict Logging]. + +| `dcpFlowControlThrottle` + +| Integer (5 to 100) +a| Default: 100 + +The percentage applied to the default value for both: + +. The `connection_buffer_size` set by XDCR replication for the DCP connection to KV (1024*1024 bytes by default) +. Length of the channel used by XDCR replication to buffer incoming items (over the DCP connection) from KV (20000 by default) + +NOTE: By decreasing this percentage value, the replication throughput is throttled in favor of a lower memory footprint. +See xref:xdcr-reference:xdcr-lowering-memory-footprint.adoc[] for more information. + +This setting can be established and retrieved either for an individual replication or globally. + | `desiredLatency` | Integer diff --git a/modules/rest-api/partials/rest-memory-and-storage-table.adoc b/modules/rest-api/partials/rest-memory-and-storage-table.adoc index e5d3fbf0b9..06a09eca8e 100644 --- a/modules/rest-api/partials/rest-memory-and-storage-table.adoc +++ b/modules/rest-api/partials/rest-memory-and-storage-table.adoc @@ -41,4 +41,8 @@ | `POST` | `/pools/default/buckets/[bucket-name]` | xref:rest-api:rest-autocompact-per-bucket.adoc[Auto-Compaction: Per Bucket] + +| `POST` +| `/pools/default/buckets/[bucket-name]` +| xref:rest-api:rest-magma-compression-per-bucket.adoc[Magma compression: Per Bucket] |=== diff --git a/modules/xdcr-reference/pages/xdcr-lowering-memory-footprint.adoc b/modules/xdcr-reference/pages/xdcr-lowering-memory-footprint.adoc new file mode 100644 index 0000000000..9febe827c4 --- /dev/null +++ b/modules/xdcr-reference/pages/xdcr-lowering-memory-footprint.adoc @@ -0,0 +1,66 @@ += Lowering the Memory Footprint in XDCR +:description: Using new global settings (introduced in Couchbase Server 8.1) to lower the memory footprint of Cross Data Center Replication. +:stem: asciimath + +[abstract] +{description} + +XDCR has 2 global replication settings that you can adjust to lower the memory footprint of a running replication: + + +dcpFlowControlThrottle:: +This is a percentage applied to the default value of both: ++ +-- +* The `connection_buffer_size` set by XDCR replication for the DCP connection to KV (1024 * 1024 bytes by default) +* Length of the channel used by XDCR replication to buffer incoming items (via the DCP connection) from KV (20000 by default) +-- ++ +Effective value for both the above parameters becomes: ++ +-- +`( * dcpFlowControlThrottle) / 100` +-- ++ +Reducing this setting from its default value of 100 causes a decrease in the max number of documents that can fit into XDCR's memory buffer. + This limitation on the size of the buffer results in a drop in the replication throughput, thereby reducing the memory footprint of the replication. + +componentEventsChanLength:: +This sets the default length of the channels being used by event-listeners to buffer various internal events before processing. ++ +Reducing this setting from its default value of 10,000 lowers the number of buffer slots available to each of the event-listeners, thereby reducing the memory allocated. +However, it may also cause a drop in replication throughput. + +NOTE: Changing these replication settings for an ongoing replication causes it to restart from the last checkpoint's sequence number +so that the new values can take effect. + +== Monitoring the Health of a Throttled Replication + +Lowering either of these settings may adversely affect the throughput of the replication. +Be careful to not over-throttle the replication. + +The health of the replication in response to the throttling can be measured via the following Prometheus metrics expression: + +[source, text] +---- +clamp_min(xdcr_changes_left_total{pipelineType="Main", sourceBucketName="", targetBucketName="", targetClusterUUID=""} - ignoring(name) rate(xdcr_docs_processed_total[1m]), 0) +---- + +The graph of the above expression will have a negative slope, or hover/plateau around zero, when the replication is in a healthy state. + +If the graph has a consistently positive slope or plateaus without ever touching the X-axis, it implies that the replication is not able to keep up with the rate of mutations on the Source bucket. +In such a situation, any throttling imposed on the replication needs to be reversed. + +In the event that a Source cluster node (running a throttled replication) is running out of disk space, it's advisable to reverse the throttling to alleviate any potential excesses in disk usage being caused to KV by the replication having a reduced `connection_buffer_size`. + +== Proposed Values for Memory Footprint Settings + +No fixed formula exists for determining the optimal `dcpFlowControlThrottle` value, as it depends on source bucket conditions such as mutation rates and document sizes. +Qualitatively, a replication whose source bucket has a lower mutation rate can be throttled more than a replication with a higher mutation rate. + +In practice, it's recommended to reduce the *dcpFlowControlThrottle* percentage incrementally from the default value of 100, then check the effect of the new value on the replication health graph described in the previous section. +If the graph starts diverging from zero +(specifically, it has a consistent positive slope), then the setting change must be undone to a value that does not have the same issue. +For example, use an incremental decrease (100 → 75 → 50 → …) while monitoring the graph. + +Similar incremental changes are advised for the *componentEventsChanLength* setting. diff --git a/preview/DOC-12561_Continuous_backup_PITR.yml b/preview/DOC-12561_Continuous_backup_PITR.yml new file mode 100644 index 0000000000..a191863262 --- /dev/null +++ b/preview/DOC-12561_Continuous_backup_PITR.yml @@ -0,0 +1,27 @@ +sources: + docs-devex: + branches: release/8.1 + +# docs-analytics: +# branches: release/8.0 + + couchbase-cli: + url: https://github.com/couchbaselabs/couchbase-cli-doc + branches: master + startPaths: docs/ + + backup: + branches: master + startPaths: docs/ + + cb-swagger: + url: https://github.com/couchbaselabs/cb-swagger + branches: release/8.1 + start_path: docs + + # Minimal SDK build +# docs-sdk-common: +# branches: [release/8.0] +# docs-sdk-java: +# branches: [3.11] + diff --git a/preview/DOC-13717_REST_API_for_appTelemetry.yml b/preview/DOC-13717_REST_API_for_appTelemetry.yml deleted file mode 100644 index 7253dd01f1..0000000000 --- a/preview/DOC-13717_REST_API_for_appTelemetry.yml +++ /dev/null @@ -1,49 +0,0 @@ -sources: - docs-devex: - branches: release/8.0 - - 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, release/8.0.1] - docs-sdk-cxx: - branches: [release/1.2] - docs-sdk-java: - branches: [release/3.11] - docs-sdk-python: - branches: [release/4.6] - docs-sdk-ruby: - branches: [temp/3.7] - docs-sdk-nodejs: - branches: [release/4.2] - docs-sdk-php: - branches: [temp/4.5] - docs-sdk-dotnet: - branches: [release/3.5] - docs-sdk-extensions: - branches: [main] - docs-sdk-go: - branches: [release/2.12] - docs-sdk-kotlin: - branches: [release/3.10] - docs-sdk-scala: - branches: [release/3.11] diff --git a/preview/HEAD.yml b/preview/HEAD.yml index 366f102297..bfbba5c0b2 100644 --- a/preview/HEAD.yml +++ b/preview/HEAD.yml @@ -1,29 +1,27 @@ sources: docs-devex: - branches: release/8.0 + branches: release/8.1 - docs-analytics: - branches: release/8.0 +# docs-analytics: +# branches: release/8.0 couchbase-cli: - branches: morpheus + url: https://github.com/couchbaselabs/couchbase-cli-doc + branches: master startPaths: docs/ - backup: - branches: morpheus - startPaths: docs/ - - #analytics: - # url: ../../docs-includes/docs-analytics - # branches: HEAD +# backup: +# branches: master +# startPaths: docs/ cb-swagger: url: https://github.com/couchbaselabs/cb-swagger - branches: release/8.0 + branches: release/8.1 start_path: docs # Minimal SDK build - docs-sdk-common: - branches: [release/8.0] - docs-sdk-java: - branches: [3.8-api] +# docs-sdk-common: +# branches: [release/8.0] +# docs-sdk-java: +# branches: [3.11] +