From d902f2b6d14960c86c30e842993089463f191e05 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 14 Jun 2024 11:11:46 -0400 Subject: [PATCH 1/4] First draft --- modules/ROOT/nav.adoc | 1 + .../services/backup-service.adoc | 14 ++ .../rest-api/pages/backup-node-threads.adoc | 181 ++++++++++++++++++ modules/rest-api/pages/backup-rest-api.adoc | 14 +- .../partials/rest-backup-service-table.adoc | 75 +++++--- 5 files changed, 255 insertions(+), 30 deletions(-) create mode 100644 modules/rest-api/pages/backup-node-threads.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 2798f54afb..25ce9e34c5 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -497,6 +497,7 @@ include::cli:partial$cbcli/nav.adoc[] *** xref:rest-api:backup-delete-plan.adoc[Delete a Plan] *** xref:rest-api:backup-get-cluster-info.adoc[Get Information on the Cluster] *** xref:rest-api:backup-manage-config.adoc[Manage Backup Configuration] + *** xref:rest-api:backup-node-threads.adoc[] ** xref:rest-api:rest-fts.adoc[Search Service API] *** xref:rest-api:rest-fts-node.adoc[Node Configuration] 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 0cafd855c5..3a96355e79 100644 --- a/modules/learn/pages/services-and-indexes/services/backup-service.adoc +++ b/modules/learn/pages/services-and-indexes/services/backup-service.adoc @@ -1,5 +1,6 @@ = Backup Service :description: pass:q[The Backup Service schedules full and incremental data backups and merges of previous data-backups.] +:stem: latexmath [abstract] {description} @@ -195,6 +196,19 @@ When you use 0 to indicate today, the range starts from the time the scheduled * Example B sets `merge_offset_start` to 4 (four days before today) and `merge_offset_end` to 3 (7 days ago, which is three days before the specified `merge_offset_start`). Therefore, if today is March 15, the time range is from March 11 to March 8, with both the start and end days included entirely. +[#threads] +== Thread Usage + +By default, the Backup Service chooses the number of threads it uses based on the number of CPU cores in the node. +The Backup Service creates one client connection per thread to connect in parallel to nodes when retrieving their data. +The more threads the service uses, the faster it retrieves data. +The formula for the number of threads it uses is stem:[\max(1, cpu\_cores \times 0.75)] (stem:[\tfrac{3}{4}] the number of CPU cores in the system or 1, whichever is larger). + +In some cases, you may find that the default number of threads the Backup Service is using is too high. +Depending on resources, a large number of threads can cause performance issues or out-of-memory errors. +If your cluster is experiencing these issues during backup, you can change the number of threads a Backup Service node allocates using the `nodesThreadsMap` REST API endpoint. +See xref:rest-api:backup-node-threads.adoc[] for details on setting the number of threads the Backup Service uses. + [#see-also] == See Also diff --git a/modules/rest-api/pages/backup-node-threads.adoc b/modules/rest-api/pages/backup-node-threads.adoc new file mode 100644 index 0000000000..35ec5eeb06 --- /dev/null +++ b/modules/rest-api/pages/backup-node-threads.adoc @@ -0,0 +1,181 @@ += Manage Backup Service Threads +:description: You can change the number of threads a Backup Service node uses when backing up data. +:stem: latexmath + +[abstract] +{description} + +== HTTP Methods and URIs + +.Get all overrides to the thread Backup Service settings: +[source, uri] +---- +GET /api/v1/nodesThreadsMap +---- + +.Overwrite all thread settings with new values: +[source, uri] +---- +POST /api/v1/nodesThreadsMap +---- + +.Update some thread settings: +[source, uri] +---- +PATCH /api/v1/nodesThreadsMap +---- + +== Description + +The `nodesThreadMap` endpoint lets you change the number of threads the Backup Service uses. +The default number of threads the Backup Service uses is based on the number of CPU cores in the node: stem:[\max(1, cpu\_cores \times 0.75)]. +The number of threads also sets the number of concurrent client connections the service uses to retrieve data from nodes in the cluster. +Each thread creates one connection. +See xref:learn:services-and-indexes/services/backup-service.adoc#threads[Thread Usage] for more information about how the number of threads affects the Backup Service. + +== Curl Syntax + +.Get the current thread overrides +[source, console] +---- +curl -u $USER:$PASSWORD -X GET \ + http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreads +---- + +.Overwrite all thread settings +[source, console] +---- + curl -u Administrator:password -X POST \ + http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreadsMap \ + -d +---- + +.Update/set some thread settings +[source, console] +---- + curl -u Administrator:password -X PATCH \ + http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreadsMap \ + -d +---- + +.POST Parameters +[cols="2,3,2"] +|=== +|Name | Description | Schema + +| `nodes_thread_map` +| An object that sets the number of threads for Backup Service nodes. +When you use the `PATCH` method, the changes only apply to the nodes in the map. +Any existing settings that are not in the map remain in effect. +Calling `POST`, removes any existing overrides. +After the call, only the overrides you supply in the map are in effect. +| <> + +|=== + +[#nodes_thread_map_schema] +.Node Thread Map Schema +[source, json] +---- +{"nodes_threads_map": { + :, . . . + } +} +---- + +[cols="2,3,2"] +|=== +|Name | Description | Schema + +| `backup_node_uuid` +| The unique identifier for a node running the Backup Service. +You can get this value from the `/pools/nodes` REST API. +See xref:rest-api:rest-node-get-info.adoc[]. +| string + +| `threads` +| The number of threads for the Backup Service to use. +| integer + +|=== + + +== Responses +[cols="1,3"] +|=== +| Value | Description + +| `200 OK` +a| Successful calls to `POST` and `PATCH` just return the response code. + +When calling the `GET` method, you receive a JSON object mapping the node UUIDs to thread values. +See <> for details. + +|`403 Forbidden` +a| User does not have the proper permission to call the API endpoint. + +In addition, the call returns a JSON object similar to the following: + +[source,json] +---- +{ + "message": "Forbidden. User needs one of the following permissions", + "permissions": [ + "ro_admin" + ] +} +---- + +| `404 Not Found` +a| The resource was not found. + +If you call the `GET` method before you have created a nodes threads map by calling `POST` or `PATCH`, you also receive the following JSON message: + +[source, json] +---- +{ + "status":404, + "msg":"Could not find the Nodes Threads Map", + "extras":"element not found" +} +---- + +|=== + +== Required Permissions + +* `GET`: Full Admin, Backup Full Admin, Read-Only Admin +* `POST` and `PATCH`: Full Admin, Backup Full Admin + +[#examples] +== Examples + +.Set a backup service node to use a single thread +[source, console] +---- +curl -s -u Administrator:password -X \ + POST http://localhost:8097/api/v1/nodesThreadsMap \ + -d '{"nodes_threads_map":{"cb5c77719df4f33131251afdca00531a":1}}' +---- + +.Get the thread settings +[source, console] +---- +curl -s -u Administrator:password -X \ + GET http://node3:8097/api/v1/nodesThreadsMap | jq +---- + +The previous example returns output similar to the following: + +[source,json] +---- +{ + "cb5c77719df4f33131251afdca00531a": 1 +} +---- + +== See Also + +* For a an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. +* For a step-by-step guide to configure and use the Backup Service using the Couchbase Server Web Console, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +* See xref:learn:services-and-indexes/services/backup-service.adoc#threads[Thread Usage] for more information about how the number of threads affects the Backup Service. diff --git a/modules/rest-api/pages/backup-rest-api.adoc b/modules/rest-api/pages/backup-rest-api.adoc index 0a94decaa9..c8170d11f5 100644 --- a/modules/rest-api/pages/backup-rest-api.adoc +++ b/modules/rest-api/pages/backup-rest-api.adoc @@ -7,9 +7,17 @@ == APIs in this Section -The Backup Service API provides endpoints categorized as follows: _Cluster_, _Configuration_, _Repository_, _Plan_, _Task_, and _Data_. -For a conceptual overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -For information on using Couchbase Web Console to configure and use the Backup Service, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +The Backup Service API endpoints can be grouped into several categories: + +* xref:#cluster[Cluster] +* xref:#configuration[Configuration] +* xref:#repository[Repository] +* xref:#plan[Plan] +* xref:#task[Task] +* xref:#data[Data] + +For an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. +For information on using Couchbase Server Web Console to configure and use the Backup Service, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. All calls require the Full Admin role, and use port `8097`. Each URI, in Couchbase Server Enterprise Edition Version 7.0, must be prefixed with `/api/v1`. diff --git a/modules/rest-api/partials/rest-backup-service-table.adoc b/modules/rest-api/partials/rest-backup-service-table.adoc index f31161b9cd..f9cb28ba12 100644 --- a/modules/rest-api/partials/rest-backup-service-table.adoc +++ b/modules/rest-api/partials/rest-backup-service-table.adoc @@ -1,3 +1,4 @@ +[#cluster] === Cluster [cols="76,215,249"] @@ -5,10 +6,11 @@ | HTTP Method | URI | Documented at | `GET` -| `/cluster/self` +| `/api/v1/cluster/self` | xref:rest-api:backup-get-cluster-info.adoc[Get Information on the Cluster] |=== +[#configuration] === Configuration [cols="76,215,249"] @@ -16,19 +18,35 @@ | HTTP Method | URI | Description | `GET` -| `/config` +| `/api/v1/config` | xref:rest-api:backup-manage-config.adoc[Manage Backup Configuration] | `POST` -| `/config` +| `/api/v1/config` | xref:rest-api:backup-manage-config.adoc[Manage Backup Configuration] | `PUT` -| `/config` +| `/api/v1/config` | xref:rest-api:backup-manage-config.adoc[Manage Backup Configuration] +| `GET` +| `/api/v1/nodesThreadsMap` +| xref:rest-api:backup-node-threads.adoc[] + +| `PATCH` +| `/api/v1/nodesThreadsMap` +| xref:rest-api:backup-node-threads.adoc[] + +| `POST` +| `/api/v1/nodesThreadsMap` +| xref:rest-api:backup-node-threads.adoc[] + + + + |=== +[#repository] === Repository [cols="76,215,249"] @@ -36,66 +54,67 @@ | HTTP Method | URI | Documented at | `GET` -| `/cluster/self/repository/<'active'|'archived'|'imported'>` +| `/api/v1/cluster/self/repository/<'active'|'archived'|'imported'>` | xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] | `GET` -| `/cluster/self/repository/active/` +| `/api/v1/cluster/self/repository/active/` | xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] | `GET` -| `/cluster/self/repository/<'active'|'archived'|'imported'>//info` +| `/api/v1/cluster/self/repository/<'active'|'archived'|'imported'>//info` | xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] | `POST` -| `/cluster/self/repository/active/` +| `/api/v1/cluster/self/repository/active/` | xref:rest-api:backup-create-repository.adoc[Create a Repository] | `POST` -| `/cluster/self/repository/<'archived'|'imported'>//restore` +| `/api/v1/cluster/self/repository/<'archived'|'imported'>//restore` | xref:rest-api:backup-restore-data.adoc[Restore Data] | `POST` -| `/cluster/self/repository/import` +| `/api/v1/cluster/self/repository/import` | xref:rest-api:backup-import-repository.adoc[Import a Repository] | `POST` -| `/cluster/self/repository/<'active'|'archived'|'imported'>//examine` +| `/api/v1/cluster/self/repository/<'active'|'archived'|'imported'>//examine` | xref:rest-api:backup-examine-data.adoc[Examine Backed-Up Data] | `POST` -| `/cluster/self/repository/active//backup` +| `/api/v1/cluster/self/repository/active//backup` | xref:rest-api:backup-trigger-backup.adoc[Perform an Immediate Backup] | `POST` -| `/cluster/self/repository/active//merge` +| `/api/v1/cluster/self/repository/active//merge` | xref:rest-api:backup-trigger-merge.adoc[Perform an Immediate Merge] | `POST` -| `/cluster/self/repository/active//archive` +| `/api/v1/cluster/self/repository/active//archive` | xref:rest-api:backup-archive-a-repository.adoc[Archive a Repository] | `POST` -| `/cluster/self/repository/active//pause` +| `/api/v1/cluster/self/repository/active//pause` | xref:rest-api:backup-pause-and-resume-tasks.adoc[Pause and Resume Tasks] | `POST` -| `/cluster/self/repository/active//resume` +| `/api/v1/cluster/self/repository/active//resume` | xref:rest-api:backup-pause-and-resume-tasks.adoc[Pause and Resume Tasks] | `DELETE` -| `/cluster/self/repository/<'archived'|'imported'>/` +| `/api/v1/cluster/self/repository/<'archived'|'imported'>/` | xref:rest-api:backup-delete-repository.adoc[Delete a Repository] | `DELETE` -| `/cluster/self/repository/<'archived'|'imported'>/?remove_repository` +| `/api/v1/cluster/self/repository/<'archived'|'imported'>/?remove_repository` | xref:rest-api:backup-delete-repository.adoc[Delete a Repository] | `DELETE` -| `/cluster/self/repository/active//backups/` +| `/api/v1/cluster/self/repository/active//backups/` | xref:rest-api:backup-delete-backups.adoc[Delete a Backup] |=== +[#plan] === Plan [cols="76,215,249"] @@ -103,27 +122,28 @@ | HTTP Method | URI | Documented at | `GET` -| `/cluster/plan` +| `/api/v1/cluster/plan` | xref:rest-api:backup-get-plan-info.adoc[Get Backup Plan Information] | `GET` -| `/cluster/plan/` +| `/api/v1/cluster/plan/` | xref:rest-api:backup-get-plan-info.adoc[Get Backup Plan Information] | `POST` -| `/cluster/plan/` +| `/api/v1/cluster/plan/` | xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans] | `PUT` -| `/cluster/plan/` +| `/api/v1/cluster/plan/` | xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans] | `DELETE` -| `/plan/` +| `/api/v1/plan/` | xref:rest-api:backup-delete-plan.adoc[Delete a Plan] |=== +[#task] === Task [cols="76,215,249"] @@ -131,15 +151,16 @@ | HTTP Method | URI | Documented at | `GET` -| `/cluster/self/repository/<'active'|'archived'|'imported'>//taskHistory` +| `/api/v1/cluster/self/repository/<'active'|'archived'|'imported'>//taskHistory` | xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] | `GET` -| `/cluster/self/repository/<'active'|'archived'|'imported'>//taskHistory?` +| `/api/v1/cluster/self/repository/<'active'|'archived'|'imported'>//taskHistory?` | xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] |=== +[#data] === Data [cols="76,215,249"] @@ -147,7 +168,7 @@ | HTTP Method | URI | Documented at | `DELETE` -| `/cluster/self/repository/active//backups/` +| `/api/v1/cluster/self/repository/active//backups/` | xref:rest-api:backup-delete-backups.adoc[Delete Backups] |=== From f58c1fc92f141de65eb228618a53c5270f5ceeac Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 14 Jun 2024 11:38:56 -0400 Subject: [PATCH 2/4] Added mWhat's New entry --- modules/introduction/partials/new-features-76_2.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc index d7dcb6445d..883c16b08f 100644 --- a/modules/introduction/partials/new-features-76_2.adoc +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -9,3 +9,7 @@ ** xref:rest-api:backup-get-task-info.adoc[`/api/v1/cluster/self/repository/{repo-state}/{task-name}/taskHistory`] ** xref:rest-api:backup-get-plan-info.adoc[`/api/v1/plan/`] +* You can now set the number of threads each Backup Service node uses when backing up data. +For example, if you find backups cause performance issues on your cluster, you can reduce the number of threads the Backup Service uses. +Reducing the number of threads also reduces the number of concurrent client connections the Backup Service makes to retrieve data. +See xref:learn:services-and-indexes/services/backup-service.adoc#threads[Thread Usage] for more information. \ No newline at end of file From 3405c4a30013a0fd2a0e8c7c161a3ba1982127da Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 18 Jun 2024 09:15:42 -0400 Subject: [PATCH 3/4] Updated based on Hyun-Ju's feedback and some additional minor edits. --- modules/rest-api/pages/backup-node-threads.adoc | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/modules/rest-api/pages/backup-node-threads.adoc b/modules/rest-api/pages/backup-node-threads.adoc index 35ec5eeb06..35d0c8f2cb 100644 --- a/modules/rest-api/pages/backup-node-threads.adoc +++ b/modules/rest-api/pages/backup-node-threads.adoc @@ -7,19 +7,19 @@ == HTTP Methods and URIs -.Get all overrides to the thread Backup Service settings: +.Get all overrides to the thread Backup Service settings [source, uri] ---- GET /api/v1/nodesThreadsMap ---- -.Overwrite all thread settings with new values: +.Overwrite all thread settings with new values [source, uri] ---- POST /api/v1/nodesThreadsMap ---- -.Update some thread settings: +.Update some thread settings [source, uri] ---- PATCH /api/v1/nodesThreadsMap @@ -27,7 +27,7 @@ PATCH /api/v1/nodesThreadsMap == Description -The `nodesThreadMap` endpoint lets you change the number of threads the Backup Service uses. +The `nodesThreadMap` endpoint lets you change the number of threads the Backup Service uses on a node. The default number of threads the Backup Service uses is based on the number of CPU cores in the node: stem:[\max(1, cpu\_cores \times 0.75)]. The number of threads also sets the number of concurrent client connections the service uses to retrieve data from nodes in the cluster. Each thread creates one connection. @@ -94,7 +94,9 @@ See xref:rest-api:rest-node-get-info.adoc[]. | string | `threads` -| The number of threads for the Backup Service to use. +a| The number of threads for the Backup Service to use. + +When set to `0`, the Backup Service uses the default number of threads based on the number of CPU cores in the node: stem:[\max(1, cpu\_cores \times 0.75)]. | integer |=== @@ -150,7 +152,7 @@ If you call the `GET` method before you have created a nodes threads map by call [#examples] == Examples -.Set a backup service node to use a single thread +.Set a backup service node to use a single thread, overwriting any existing overrides [source, console] ---- curl -s -u Administrator:password -X \ From 5ab3474d4908b59ab04dddbe50ae9f1de6ed281c Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Thu, 20 Jun 2024 13:31:14 -0400 Subject: [PATCH 4/4] Change based on Nour's feedback. --- .../pages/services-and-indexes/services/backup-service.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) 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 3a96355e79..149769b20f 100644 --- a/modules/learn/pages/services-and-indexes/services/backup-service.adoc +++ b/modules/learn/pages/services-and-indexes/services/backup-service.adoc @@ -206,9 +206,13 @@ The formula for the number of threads it uses is stem:[\max(1, cpu\_cores \times In some cases, you may find that the default number of threads the Backup Service is using is too high. Depending on resources, a large number of threads can cause performance issues or out-of-memory errors. -If your cluster is experiencing these issues during backup, you can change the number of threads a Backup Service node allocates using the `nodesThreadsMap` REST API endpoint. +If your cluster is experiencing these issues during backup, you can change the number of threads a Backup Service node uses. +You change this setting using the `nodesThreadsMap` REST API endpoint. See xref:rest-api:backup-node-threads.adoc[] for details on setting the number of threads the Backup Service uses. +Reducing the number of threads the Backup Service uses increases the time it takes to backup data. +You may want to experiment with different thread settings to find a balance between resource use and backup duration for your cluster. + [#see-also] == See Also