Docs Menu
Docs Home
/
MongoDB Cluster-to-Cluster Sync
/
Reference
/
mongosync API Endpoints

progress

On this page

  • Description
  • Request
  • Response
  • Successful Response
  • Error Response
  • Behavior
  • Endpoint Protection
  • Example
  • Request
  • Response

Description

Returns either an updated status of the synchronization process or an error.

Request

GET /api/v1/progress

Response

The progress endpoint returns either an updated status or an error.

Successful Response

If mongosync successfully gets the status of the sync process, all response fields are wrapped in a top-level progress object with the following fields:

Field
Type
Description
state
string
The current state of mongosync. For information on the possible states, see State Descriptions.
canCommit
boolean
If true, indicates that a commit request will succeed. This also means that the initial sync has completed and is applying change events.
canWrite
boolean

If true, indicates that writes are permitted on the destination cluster. Do not write to the destination cluster while canWrite is false.

Index validation continues until the commit is complete.

info
string

Provides extra information on the synchronization progress. Possible info values include:

  • "collection copy"

  • "change event application"

  • "waiting for commit to complete"

  • "commit completed"

lagTimeSeconds
integer

Time in seconds between the last applied event and time of the current latest event for this instance of mongosync.

Note

mongosync performs periodic no-op writes on the source cluster, which may prevent the value of the lagTimeSeconds field from reaching zero.

collectionCopy
object
Estimates the total amount of data being copied from collections and the amount that has already been copied to the destination cluster
collectionCopy .estimatedTotalBytes
integer

Estimated total number of bytes to be copied globally by all mongosync instances during the initial copying of collections.

mongosync approximates the estimated total number of bytes prior to migration and does not update this value during the synchronization process. This value does not reflect changes made to the source cluster during sync and is not an accurate indicator of migration progress. mongosync approximates the estimated total number of bytes prior to migration and does not update this value during the synchronization process. This value does not reflect changes made to the source cluster during sync and is not an accurate indicator of migration progress.

collectionCopy .estimatedCopiedBytes
integer

Estimated number of bytes which have been copied to the destination cluster by this mongosync instance during the initial copying of collections.

To calculate the total estimated progress as a percentage, add the value of the estimatedCopiedBytes field for each mongosync instance and divide the result by the value of the estimatedTotalBytes field . Then, multiply the result by 100.

The value of estimatedCopiedBytes may be larger than the value of the estimatedTotalBytes due to retried operations. A comparison of estimatedTotalBytes and estimatedCopiedBytes is not an accurate indicator of migration progress. The value of estimatedCopiedBytes may be larger than the value of the estimatedTotalBytes due to retried operations. A comparison of estimatedTotalBytes and estimatedCopiedBytes is not an accurate indicator of migration progress.

directionMapping
object
Describes the mapping direction for the synchronization, namely the source and destination clusters.
directionMapping .Source
string
Source cluster. Returned in the form <cluster name>: <host>:<port>.
directionMapping .Destination
string
Destination cluster. Returned in the form <cluster name>: <host>:<port>.
mongosyncID
string
The identifier string for the mongosync instance.
coordinatorID
string

The identifier string for the coordinator instance.

  • When mongosync is coordinated by another instance, this field shows the identifier string for the coordinator instance.

  • When mongosync is a coordinator or runs alone, this field returns the same value as its mongosyncID field.

  • When mongosync starts up, this field returns null until mongosync identifies the coordinator.

Error Response

If mongosync encounters an error, the progress endpoint returns the following field:

Field
Type
Description
error
string
If an error occurred, gives a detailed description of the error. This field is omitted when the call to the endpoint is successful

Behavior

  • When mongosync is in the IDLE state, all output fields except state and canCommit are null.

  • When mongosync is in the PAUSED state, the lagTimeSeconds field is null.

  • The endpoint does not auto-refresh. To get updated status, call the progress endpoint again.

    Note

    Starting in mongosync 1.7.3, mongosync can take at least two minutes to respond when you resume or restart a sync operation. During this time, any calls to the progress endpoint might fail. If a progress call fails, it is safe to retry.

Endpoint Protection

mongosync does not protect the progress endpoint. However, by default the API binds to localhost only and does not accept calls from other sources. Additionally, the progress call does not expose connection credentials or user data.

Example

The following example returns the status of the synchronization process.

Request

curl localhost:27182/api/v1/progress -XGET

Response

{
   "progress":
      {
         "state":"RUNNING",
         "canCommit":true,
         "canWrite":false,
         "info":"change event application",
         "lagTimeSeconds":0,
         "collectionCopy":
            {
               "estimatedTotalBytes":694,
               "estimatedCopiedBytes":694
            },
         "directionMapping":
            {
               "Source":"cluster0: localhost:27017",
               "Destination":"cluster1: localhost:27018"
            }
      }
}

Back

start

Next

pause