Manage Backup Service Threads

    • Couchbase Server 7.6.2
      +
      You can change the number of threads a Backup Service node uses when backing up data.

      HTTP Methods and URIs

      Get all overrides to the thread Backup Service settings
      GET /api/v1/nodesThreadsMap
      Overwrite all thread settings with new values
      POST /api/v1/nodesThreadsMap
      Update some thread settings
      PATCH /api/v1/nodesThreadsMap

      Description

      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: \(\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 Thread Usage for more information about how the number of threads affects the Backup Service.

      Curl Syntax

      Get the current thread overrides
      curl -u $USER:$PASSWORD -X GET \
           http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreads
      Overwrite all thread settings
       curl -u Administrator:password -X POST \
            http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreadsMap \
            -d <nodes_thread_map>
      Update/set some thread settings
       curl -u Administrator:password -X PATCH \
            http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreadsMap \
            -d <nodes_thread_map>
      Table 1. POST Parameters
      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.

      Node Threads Map

      Node Thread Map Schema
      {"nodes_threads_map": {
          <backup_node_uuid>:<threads>, . . .
          }
      }
      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 Getting Information on Nodes.

      string

      threads

      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: \(\max(1, cpu\_cores \times 0.75)\).

      integer

      Responses

      Value Description

      200 OK

      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 Examples for details.

      403 Forbidden

      User does not have the proper permission to call the API endpoint.

      In addition, the call returns a JSON object similar to the following:

      {
        "message": "Forbidden. User needs one of the following permissions",
        "permissions": [
          "ro_admin"
        ]
      }

      404 Not Found

      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:

      {
          "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

      Set a backup service node to use a single thread, overwriting any existing overrides
      curl -s -u Administrator:password -X \
           POST http://localhost:8097/api/v1/nodesThreadsMap \
           -d '{"nodes_threads_map":{"cb5c77719df4f33131251afdca00531a":1}}'
      Get the thread settings
      curl -s -u Administrator:password -X \
           GET http://node3:8097/api/v1/nodesThreadsMap | jq

      The previous example returns output similar to the following:

      {
        "cb5c77719df4f33131251afdca00531a": 1
      }

      See Also

      • For a an overview of the Backup Service, see Backup Service.

      • For a step-by-step guide to configure and use the Backup Service using the Couchbase Server Web Console, see Manage Backup and Restore.

      • See Thread Usage for more information about how the number of threads affects the Backup Service.