A newer version of this documentation is available.

View Latest

Metrics REST API (Static Page)

  • reference
    +

    Description of the Sync Gateway Metrics REST API, alternative representation as a static page

    Overview

    Version information

    Version : 3.1

    Host information

    {protocol}://{hostname}:4986

    Metrics API

    Component Description

    protocol

    The protocol to use (HTTP or HTTPS)

    Values: http, https
    Example: http

    hostname

    The hostname to use

    Example: localhost

    Resources

    This section describes the operations available with this REST API. The operations are grouped in the following categories.

    Default

    Table of Contents

    Get all Sync Gateway statistics

    GET /_expvar
    Description

    This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes.

    This includes per database stats, replication stats, and server stats.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Architect
    • Sync Gateway Dev Ops
    • External Stats Reader
    Produces
    • application/javascript

    Responses
    HTTP Code Description Schema

    200

    Returned statistics

    Prometheus

    Endpoints for use with Prometheus

    Debugging/monitoring runtime stats in Prometheus Exposition format

    GET /_metrics
    Description

    Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Architect
    • Sync Gateway Dev Ops
    • External Stats Reader
    Produces
    • text/plain

    Responses
    HTTP Code Description Schema

    200

    Successfully returned stats

    String

    Debugging/monitoring runtime stats in Prometheus Exposition format

    GET /metrics
    Description

    Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.

    Required Sync Gateway RBAC roles:

    • Sync Gateway Architect
    • Sync Gateway Dev Ops
    • External Stats Reader
    Produces
    • text/plain

    Responses
    HTTP Code Description Schema

    200

    Successfully returned stats

    String

    Server

    Table of Contents

    Check if API is available

    GET /_ping
    Description

    Returns OK status if API is available.

    Produces
    • text/plain

    Responses
    HTTP Code Description Schema

    200

    Returned status

    String

    Check if API is available

    HEAD /_ping
    Description

    Returns OK status if API is available.

    Responses
    HTTP Code Description Schema

    200

    Server is available

    Definitions

    This section describes the properties consumed and returned by this REST API.

    ExpVars

    Object

    Property Schema

    cmdline
    optional

    Built-in variables from the Go runtime, lists the command-line arguments

    Object

    memstats
    optional

    Dumps a large amount of information about the memory heap and garbage collector

    Object

    cb
    optional

    Variables reported by the Couchbase SDK (go_couchbase package)

    Object

    mc
    optional

    Variables reported by the low-level memcached API (gomemcached package)

    Object

    syncGateway_changeCache
    optional

    syncGateway_db
    optional

    syncgateway
    optional

    Monitoring stats

    GetExpvar200Response

    Object

    Property Schema

    cmdline
    optional

    Built-in variables from the Go runtime, lists the command-line arguments

    Object

    memstats
    optional

    Dumps a large amount of information about the memory heap and garbage collector

    Object

    cb
    optional

    Variables reported by the Couchbase SDK (go_couchbase package)

    Object

    mc
    optional

    Variables reported by the low-level memcached API (gomemcached package)

    Object

    syncGateway_changeCache
    optional

    syncGateway_db
    optional

    syncgateway
    optional

    Monitoring stats

    GetExpvar200ResponseSyncGatewayChangeCache

    Object

    Property Schema

    maxPending
    optional

    Max number of sequences waiting on a missing earlier sequence number

    Object

    lag-tap-0000ms
    optional

    Histogram of delay from doc save till it shows up in Tap feed

    Object

    lag-queue-0000ms
    optional

    Histogram of delay from Tap feed till doc is posted to changes feed

    Object

    lag-total-0000ms
    optional

    Histogram of total delay from doc save till posted to changes feed

    Object

    outOfOrder
    optional

    Number of out-of-order sequences posted

    Object

    view_queries
    optional

    Number of queries to channels view

    Object

    GetExpvar200ResponseSyncGatewayDb

    Object

    Property Schema

    channelChangesFeeds
    optional

    Number of calls to db.changesFeed, i.e. generating a changes feed for a single channel.

    Object

    channelLogAdds
    optional

    Number of entries added to channel logs

    Object

    channelLogAppends
    optional

    Number of times entries were written to channel logs using an APPEND operation

    Object

    channelLogCacheHits
    optional

    Number of requests for channel-logs that were fulfilled from the in-memory cache

    Object

    channelLogRewrites
    optional

    Number of times entries were written to channel logs using a SET operation (rewriting the entire log)

    Object

    channelLogRewriteCollisions
    optional

    Number of collisions while attempting to rewrite channel logs using SET

    Object

    document_gets
    optional

    Number of times a document was read from the database

    Object

    revisionCache_adds
    optional

    Number of revisions added to the revision cache

    Object

    revisionCache_hits
    optional

    Number of times a revision-cache lookup succeeded

    Object

    revisionCache_misses
    optional

    Number of times a revision-cache lookup failed

    Object

    revs_added
    optional

    Number of revisions added to the database (including deletions)

    Object

    sequence_gets
    optional

    Number of times the database's lastSequence was read

    Object

    sequence_reserves
    optional

    Number of times the database's lastSequence was incremented

    Object

    GetExpvar200ResponseSyncgateway

    Object

    Property Schema

    global
    optional

    Global Sync Gateway stats

    per_db
    optional

    This array contains stats for all databases declared in the config file -- see the Sync Gateway Statistics Schema for more details on the metrics collected and reported by Sync Gateway. The statistics for each {$db_name} database are grouped into:

    • cache related statistics
    • collections statistics
    • cbl_replication_push
    • cbl_replication_pull
    • database_related_statistics
    • delta_sync
    • gsi_views
    • security_related_statistics
    • shared_bucket_import
    • per_replication statistics for each replication_id

    per_replication
    optional

    An array of stats for each replication declared in the config file Deprecated @ 2.8: used only by inter-sync-gateway replications version 1.

    GetExpvar200ResponseSyncgatewayGlobal

    Object

    Property Schema

    resource_utilization
    optional

    Resource utilization stats

    GetExpvar200ResponseSyncgatewayGlobalResourceUtilization

    Object

    Property Schema

    admin_net_bytes_recv
    optional

    The total number of bytes received (since node start-up) on the network interface to which the Sync Gateway api.admin_interface is bound.

    Integer

    admin_net_bytes_sent
    optional

    The total number of bytes sent (since node start-up) on the network interface to which the Sync Gateway api.admin_interface is bound.

    Integer

    error_count
    optional

    The total number of errors logged.

    Integer

    go_memstats_heapalloc
    optional

    HeapAlloc is bytes of allocated heap objects. Allocated heap objects include all reachable objects, as well as unreachable objects that the garbage collector has not yet freed. Specifically, HeapAlloc increases as heap objects are allocated and decreases as the heap is swept and unreachable objects are freed. Sweeping occurs incrementally between GC cycles, so these two processes occur simultaneously, and as a result HeapAlloc tends to change smoothly (in contrast with the sawtooth that is typical of stop-the-world garbage collectors).

    Integer

    go_memstats_heapidle
    optional

    HeapIdle is bytes in idle (unused) spans. Idle spans have no objects in them. These spans could be (and may already have been) returned to the OS, or they can be reused for heap allocations, or they can be reused as stack memory. HeapIdle minus HeapReleased estimates the amount of memory that could be returned to the OS, but is being retained by the runtime so it can grow the heap without requesting more memory from the OS. If this difference is significantly larger than the heap size, it indicates there was a recent transient spike in live heap size.

    Integer

    go_memstats_heapinuse
    optional

    HeapInuse is bytes in in-use spans. In-use spans have at least one object in them. These spans an only be used for other objects of roughly the same size. HeapInuse minus HeapAlloc estimates the amount of memory that has been dedicated to particular size classes, but is not currently being used. This is an upper bound on fragmentation, but in general this memory can be reused efficiently.

    Integer

    go_memstats_heapreleased
    optional

    HeapReleased is bytes of physical memory returned to the OS. This counts heap memory from idle spans that was returned to the OS and has not yet been reacquired for the heap.

    Integer

    go_memstats_pausetotalns
    optional

    PauseTotalNs is the cumulative nanoseconds in GC stop-the-world pauses since the program started. During a stop-the-world pause, all goroutines are paused and only the garbage collector can run.

    Integer

    go_memstats_stackinuse
    optional

    StackInuse is bytes in stack spans. In-use stack spans have at least one stack in them. These spans can only be used for other stacks of the same size. There is no StackIdle because unused stack spans are returned to the heap (and hence counted toward HeapIdle).

    Integer

    go_memstats_stacksys
    optional

    StackSys is bytes of stack memory obtained from the OS. StackSys is StackInuse, plus any memory obtained directly from the OS for OS thread stacks (which should be minimal).

    Integer

    go_memstats_sys
    optional

    Sys is the total bytes of memory obtained from the OS. Sys is the sum of the XSys fields below. Sys measures the virtual address space reserved by the Go runtime for the heap, stacks, and other internal data structures. It's likely that not all of the virtual address space is backed by physical memory at any given moment, though in general it all was at some point.

    Integer

    goroutines_high_watermark
    optional

    Peak number of go routines since process start.

    Integer

    num_goroutines
    optional

    The total number of goroutines.

    Integer

    num_idle_kv_ops
    optional

    The total number of idle kv operations.

    Integer

    process_cpu_percent_utilization
    optional

    The CPU utilization as percentage value * 10. The extra 10 multiplier is a mistake left for backwards compatibility. Please consider using node_cpu_percent_utilization as of version 3.2. The CPU usage calculation is performed based on user and system CPU time, but it does not include components such as iowait. The derivation means that the values of process_cpu_percent_utilization and %Cpu, returned when running the top command, will differ.

    Float (float)

    node_cpu_percent_utilization
    optional

    The node CPU utilization as percentage value, since the last time this stat was called. The CPU usage calculation is performed based on user and system CPU time, but it does not include components such as iowait.

    Float (float)

    process_memory_resident
    optional

    The memory utilization (Resident Set Size) for the process, in bytes.

    Integer

    pub_net_bytes_recv
    optional

    The total number of bytes received (since node start-up) on the network interface to which the Sync Gateway api.public_interface is bound. By default, that is the number of bytes received on 127.0.0.1:4984 since node start-up

    Integer

    pub_net_bytes_sent
    optional

    The total number of bytes sent (since node start-up) on the network interface to which Sync Gateway api.public_interface is bound. By default, that is the number of bytes sent on 127.0.0.1:4984 since node start-up.

    Integer

    system_memory_total
    optional

    The total memory available on the system in bytes.

    Integer

    warn_count
    optional

    The total number of warnings logged.

    Integer

    uptime
    optional

    The total uptime.

    Integer

    GetExpvar200ResponseSyncgatewayPerDbInner

    Object

    Property Schema

    cache
    optional

    Object

    database
    optional

    Object

    per_replication
    optional

    Object

    collections
    optional

    Object

    security
    optional

    Object

    GetExpvar200ResponseSyncgatewayPerReplicationInner

    Object

    Property Schema

    $replication_id
    optional

    GetExpvar200ResponseSyncgatewayPerReplicationInnerReplicationId

    Object

    Property Schema

    sgr_active
    optional

    Whether the replication is active at this time. Deprecated @ 2.8: used only by inter-sync-gateway replications version 1.

    Boolean

    sgr_docs_checked_sent
    optional

    The total number of documents checked for changes since replication started. This represents the number of potential change notifications pushed by Sync Gateway. Constraints This is not necessarily the number of documents pushed, as a given target might already have the change. Used by versions 1 and 2.

    Integer

    sgr_num_attachments_transferred
    optional

    The total number of attachments transferred since replication started. Deprecated @ 2.8: used only by inter-sync-gateway replications version 1.

    Integer

    sgr_num_attachment_bytes_transferred
    optional

    The total number of attachment bytes transferred since replication started. Deprecated @ 2.8: used only by inter-sync-gateway replications version 1.

    Integer

    sgr_num_docs_failed_to_push
    optional

    The total number of documents that failed to be pushed since replication started. Used by versions 1 and 2.

    Integer

    sgr_num_docs_pushed
    optional

    The total number of documents that were pushed since replication started. Used by versions 1 and 2.

    Integer