Replication Monitoring and Statistics

    +

    Description — Monitoring inter-Sync Gateway replications
    Abstract — This content covers the retrieval of status and statistical data relating to replication.
    Related Content — Configuration Details | Admin REST API | Inter-Sync Gateway Replication

    Context Clarification

    This content relates only to inter-Sync Gateway replication in Sync Gateway 2.8+. For documentation on pre-2.8 inter-Sync Gateway replication (also known as SG Replicate) — see Inter-Sync Gateway Replication pre-2.8

    Overview

    Status Information

    Sync Gateway provides a replication status Admin REST API endpoint to enable effective monitoring of replications.

    Use the _replicationStatus(replicationID) endpoint to check the status of individual replications and-or the _replicationStatus endpoint to get status information on all replications, filtered by the querystring criteria.

    Sync Gateway Statistics

    Sync Gateway maintains a comprehensive set of statistics, including a replication-specific subset.

    You can access these statistics using the _expvars endpoint.

    Retrieving Replication Status Data

    Sync Gateway provides easy access to replication status data through the Admin REST API.

    You can obtain the replication status details for a specific replication, or for all replications across all nodes. This option can be useful, for example, to find any auto-generated replication_id details needed to enable further replication management activities.

    Replications always run on the node on which they are configured. Users can only access replications on the node from which they make the request.

    Retrieving Status Data for a Specific Replication

    Use the Admin REST API endpoint replicationStatus to easily access replication status data for a specific replication id. Status data is returned regardless of the node the replication is running (or ran) on.

    Action: Send a GET request to the _replicationStatus endpoint with the required replication_id

    Example 1. Get status data for a specified replication

    This example returns status information for replication id 'db1-rep-id2'.

    • Request

    • Response

    curl --location --request GET 'http://localhost:4985/db1/_replicationStatus/db1-rep-id2' \
    --header 'Content-Type: application/json' \
    [
      {
        "replication_id": "db1-rep-id2",
        "docs_read": 0,
        "docs_written": 10,
        "doc_write_failures": 0,
        "doc_write_conflict": 0,
        "status": "running",
        "rejected_by_remote": 0,
        "rejected_by_local": 0,
        "last_seq_pull": "8851",
        "last_seq_push": "10402"
    }
    ]

    Retrieving Status Data for All Replications

    Use the Admin REST API’s _replicationStatus endpoint to access replication status data for all replications run, or running, on any node within the cluster. The JSON response comprises an array of results, one per replication.

    You can easily filter the results using the query string: ?activeOnly=false&includeConfig=true&localOnly=false&includeError=true`

    Available query string filters comprise:

    • activeOnly - return only active replications (default=false)

    • localOnly - return replications from the local node only (default=false)

    • includeError - return replications even if their status is "error" (default=true)

    • includeConfig - return the replication definition details (configuration) as well as the status data. This will include remote configuration definitions if localOnly=false (default=false)

    Action: Send a GET request to the _replicationStatus endpoint with an optional query string

    Example 2. Get status data for all replications meeting criteria

    This example retrieves status data, from across all nodes, for all replications that meet the specified criteria. The results are returned in an array; one entry per replication.

    • Request

    • Response

    curl --location --request GET "http://localhost:4985/db1-local/_replicationStatus?activeOnly=false&includeConfig=true&localOnly=false&includeError=true" \ (1)
    --header 'Content-Type: application/json' \
    1 This example’s criteria selects replications with any status (including errors), on local and remote nodes. The returned status details also include replication definition details.
    [
      {
        "replication_id": "db1-rep-id1-pull",
        "docs_read": 0,
        "docs_written": 0,
        "doc_write_failures": 0,
        "doc_write_conflict": 0,
        "status": "running",
        "rejected_by_remote": 0,
        "rejected_by_local": 0,
        "config": { (1)
            "replication_id": "db1-rep-id1-pull",
            "cancel": true,
            "direction": "pull",
            "purge-on-removal": true,
            "remote": "http://user:****@example.com:4985/db1-remote",
            "filter":"sync_gateway/bychannel",
            "query_params": {
              "channels": ["channel1.user1"]
            },
            "continuous": true
        }
      },
      {
        "replication_id": "db1-rep-id2",
        "docs_read": 0,
        "docs_written": 0,
        "doc_write_failures": 0,
        "doc_write_conflict": 0,
        "status": "stopped",  (2)
        "rejected_by_remote": 0,
        "rejected_by_local": 0,
        "config": {
            "replication_id": "db1-rep-id2",
            "direction": "pull",
            "remote": "http://user:****@example.com:4985/db1-remote",
            "continuous": true
          }
      },
      {
        "replication_id": "db2-rep-id1",
        "docs_read": 0,
        "docs_written": 0,
        "doc_write_failures": 0,
        "doc_write_conflict": 0,
        "status": "error", (3)
        "rejected_by_remote": 0,
        "rejected_by_local": 0,
        "config": {
          "replication_id": "db2-rep-id1",
          "direction": "pull",
          "remote": "http://user:****@example2.com:4985/db2-remote",
          "continuous": true
        }
      }
    ]
    1 The configuration details included because includeConfig=true
    2 "Stopped" replications included because activeOnly=false
    3 "error" replications included because includeError=true

    Retrieving Sync Gateway Statistics

    Sync Gateway maintains a comprehensive set of metrics covering performance and resource utilization.

    The statistics schema includes replication metrics collected on a per-replication basis. These can be especially useful in monitoring the health of Sync Gateway nodes. An increasingly important activity as deployments scale to support cloud-to-edge use cases.

    Access to this data is provided through the Admin REST API endpoint /_expvars.

    See: View Statistics and Metrics for a full description of the available metrics.