openapi: 3.0.3
info:
  title: Sync Gateway Metrics REST API
  description: >-
    # Introduction


    Sync Gateway manages access and synchronization between Couchbase Lite and
    Couchbase Server.

    The Sync Gateway Metrics REST API returns Sync Gateway metrics, in JSON or
    Prometheus-compatible formats, for performance monitoring and diagnostic
    purposes.
  version: '3.3'
  license:
    name: Business Source License 1.1 (BSL)
    url: 'https://github.com/couchbase/sync_gateway/blob/master/LICENSE'
servers:
  - url: '{protocol}://{hostname}:4986'
    description: Metrics API
    variables:
      protocol:
        description: The protocol to use (HTTP or HTTPS)
        default: http
        enum:
          - http
          - https
      hostname:
        description: The hostname to use
        default: localhost
tags:
  - name: Prometheus
    description: Endpoints for use with Prometheus
  - name: JSON
    description: Endpoints for use with JSON metrics
  - name: Server
    description: Endpoints for managing the REST API
externalDocs:
  description: ⬆️ Metrics REST API Overview
  url: rest-api-metrics.html
paths:
  /_ping:
    get:
      summary: Check if API is available
      operationId: get__ping
      tags:
        - Server
      description: Returns OK status if API is available.
      responses:
        '200':
          description: Returned status
          content:
            text/plain:
              schema:
                type: string
              example: OK
  /metrics:
    get:
      summary: >-
        Get debugging and monitoring runtime stats in Prometheus Exposition
        format
      operationId: get_metrics
      tags:
        - Prometheus
      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
      responses:
        '200':
          description: >-
            Successfully returned statistics.

            For details, see [Prometheus
            Metrics](stats-monitoring-prometheus.html).
          content:
            application/json:
              schema:
                $ref: metrics_metadata.json
  /_expvar:
    tags:
      - JSON
    get:
      summary: Get all Sync Gateway statistics in JSON format
      operationId: get__expvar
      tags:
        - JSON
      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
      responses:
        '200':
          description: |-
            Successfully returned statistics.
            For details, see [JSON Metrics](stats-monitoring-json.html).
          content:
            application/json:
              schema:
                type: object
                properties:
                  cmdline:
                    description: >-
                      Built-in variables from the Go runtime, lists the
                      command-line arguments
                    type: object
                  memstats:
                    description: >-
                      Dumps a large amount of information about the memory heap
                      and garbage collector
                    type: object
                  cb:
                    description: >-
                      Variables reported by the Couchbase SDK (go_couchbase
                      package)
                    type: object
                  mc:
                    description: >-
                      Variables reported by the low-level memcached API
                      (gomemcached package)
                    type: object
                  syncGateway_changeCache:
                    type: object
                    properties:
                      maxPending:
                        description: >-
                          Max number of sequences waiting on a missing earlier
                          sequence number
                        type: object
                      lag-tap-0000ms:
                        description: >-
                          Histogram of delay from doc save till it shows up in
                          Tap feed
                        type: object
                      lag-queue-0000ms:
                        description: >-
                          Histogram of delay from Tap feed till doc is posted to
                          changes feed
                        type: object
                      lag-total-0000ms:
                        description: >-
                          Histogram of total delay from doc save till posted to
                          changes feed
                        type: object
                      outOfOrder:
                        description: Number of out-of-order sequences posted
                        type: object
                      view_queries:
                        description: Number of queries to channels view
                        type: object
                  syncGateway_db:
                    type: object
                    properties:
                      channelChangesFeeds:
                        description: >-
                          Number of calls to db.changesFeed, i.e. generating a
                          changes feed for a single channel.
                        type: object
                      channelLogAdds:
                        description: Number of entries added to channel logs
                        type: object
                      channelLogAppends:
                        description: >-
                          Number of times entries were written to channel logs
                          using an APPEND operation
                        type: object
                      channelLogCacheHits:
                        description: >-
                          Number of requests for channel-logs that were
                          fulfilled from the in-memory cache
                        type: object
                      channelLogRewrites:
                        description: >-
                          Number of times entries were written to channel logs
                          using a SET operation (rewriting the entire log)
                        type: object
                      channelLogRewriteCollisions:
                        description: >-
                          Number of collisions while attempting to rewrite
                          channel logs using SET
                        type: object
                      document_gets:
                        description: Number of times a document was read from the database
                        type: object
                      revisionCache_adds:
                        description: Number of revisions added to the revision cache
                        type: object
                      revisionCache_hits:
                        description: Number of times a revision-cache lookup succeeded
                        type: object
                      revisionCache_misses:
                        description: Number of times a revision-cache lookup failed
                        type: object
                      revs_added:
                        description: >-
                          Number of revisions added to the database (including
                          deletions)
                        type: object
                      sequence_gets:
                        description: Number of times the database's lastSequence was read
                        type: object
                      sequence_reserves:
                        description: >-
                          Number of times the database's lastSequence was
                          incremented
                        type: object
                  syncgateway:
                    description: Monitoring stats
                    type: object
                    properties:
                      global:
                        description: Global Sync Gateway stats
                        type: object
                        properties:
                          resource_utilization:
                            description: Resource utilization stats
                            type: object
                            properties:
                              admin_net_bytes_recv:
                                type: integer
                                description: >-
                                  The total number of bytes received (since node
                                  start-up) on the network interface to which
                                  the Sync Gateway api.admin_interface is bound.
                              admin_net_bytes_sent:
                                type: integer
                                description: >-
                                  The total number of bytes sent (since node
                                  start-up) on the network interface to which
                                  the Sync Gateway api.admin_interface is bound.
                              error_count:
                                type: integer
                                description: The total number of errors logged.
                              go_memstats_heapalloc:
                                type: integer
                                description: >-
                                  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).
                              go_memstats_heapidle:
                                type: integer
                                description: >-
                                  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.
                              go_memstats_heapinuse:
                                type: integer
                                description: >-
                                  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.
                              go_memstats_heapreleased:
                                type: integer
                                description: >-
                                  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.
                              go_memstats_pausetotalns:
                                type: integer
                                description: >-
                                  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.
                              go_memstats_stackinuse:
                                type: integer
                                description: >-
                                  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).
                              go_memstats_stacksys:
                                type: integer
                                description: >-
                                  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).
                              go_memstats_sys:
                                type: integer
                                description: >-
                                  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.
                              goroutines_high_watermark:
                                type: integer
                                description: >-
                                  Peak number of go routines since process
                                  start.
                              num_goroutines:
                                type: integer
                                description: The total number of goroutines.
                              num_idle_kv_ops:
                                type: integer
                                description: The total number of idle kv operations.
                              num_idle_query_ops:
                                type: integer
                                description: The total number of idle query operations.
                              process_cpu_percent_utilization:
                                type: number
                                format: float
                                description: >-
                                  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.
                              node_cpu_percent_utilization:
                                type: number
                                format: float
                                description: >-
                                  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.
                              process_memory_resident:
                                type: integer
                                description: >-
                                  The memory utilization (Resident Set Size) for
                                  the process, in bytes.
                              pub_net_bytes_recv:
                                type: integer
                                description: >-
                                  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
                              pub_net_bytes_sent:
                                type: integer
                                description: >-
                                  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.
                              system_memory_total:
                                type: integer
                                description: >-
                                  The total memory available on the system in
                                  bytes.
                              warn_count:
                                type: integer
                                description: The total number of warnings logged.
                              uptime:
                                type: integer
                                description: The total uptime.
                      per_db:
                        description: >-
                          This array contains stats for all databases declared
                          in the config file &mdash; see [View Statistics and
                          Metrics](stats-monitoring.html) for more details on
                          the metrics collected and reported by Sync Gateway.


                          The statistics for each 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`
                        type: array
                        items:
                          type: object
                          properties:
                            cache:
                              type: object
                            database:
                              type: object
                            per_replication:
                              type: object
                            collections:
                              type: object
                            security:
                              type: object
                      per_replication:
                        description: >-
                          An array of stats for each replication declared in the
                          config file

                          **Deprecated @ 2.8**: used only by inter-sync-gateway
                          replications version 1.
                        type: array
                        items:
                          type: object
                          description: Stats for a given replication_id
                          properties:
                            $replication_id:
                              type: object
                              properties:
                                sgr_active:
                                  description: >-
                                    Whether the replication is active at this
                                    time.

                                    **Deprecated @ 2.8**: used only by
                                    inter-sync-gateway replications version 1.
                                  type: boolean
                                sgr_docs_checked_sent:
                                  description: >-
                                    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.
                                  type: integer
                                sgr_num_attachments_transferred:
                                  description: >-
                                    The total number of attachments transferred
                                    since replication started.

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

                                    **Deprecated @ 2.8**: used only by
                                    inter-sync-gateway replications version 1.
                                  type: integer
                                sgr_num_docs_failed_to_push:
                                  description: >-
                                    The total number of documents that failed to
                                    be pushed since replication started.

                                    Used by versions 1 and 2.
                                  type: integer
                                sgr_num_docs_pushed:
                                  description: >-
                                    The total number of documents that were
                                    pushed since replication started.

                                    Used by versions 1 and 2.
                                  type: integer
                        deprecated: true
components:
  schemas:
    ExpVars:
      type: object
      properties:
        cmdline:
          description: >-
            Built-in variables from the Go runtime, lists the command-line
            arguments
          type: object
        memstats:
          description: >-
            Dumps a large amount of information about the memory heap and
            garbage collector
          type: object
        cb:
          description: Variables reported by the Couchbase SDK (go_couchbase package)
          type: object
        mc:
          description: >-
            Variables reported by the low-level memcached API (gomemcached
            package)
          type: object
        syncGateway_changeCache:
          type: object
          properties:
            maxPending:
              description: >-
                Max number of sequences waiting on a missing earlier sequence
                number
              type: object
            lag-tap-0000ms:
              description: Histogram of delay from doc save till it shows up in Tap feed
              type: object
            lag-queue-0000ms:
              description: >-
                Histogram of delay from Tap feed till doc is posted to changes
                feed
              type: object
            lag-total-0000ms:
              description: >-
                Histogram of total delay from doc save till posted to changes
                feed
              type: object
            outOfOrder:
              description: Number of out-of-order sequences posted
              type: object
            view_queries:
              description: Number of queries to channels view
              type: object
        syncGateway_db:
          type: object
          properties:
            channelChangesFeeds:
              description: >-
                Number of calls to db.changesFeed, i.e. generating a changes
                feed for a single channel.
              type: object
            channelLogAdds:
              description: Number of entries added to channel logs
              type: object
            channelLogAppends:
              description: >-
                Number of times entries were written to channel logs using an
                APPEND operation
              type: object
            channelLogCacheHits:
              description: >-
                Number of requests for channel-logs that were fulfilled from the
                in-memory cache
              type: object
            channelLogRewrites:
              description: >-
                Number of times entries were written to channel logs using a SET
                operation (rewriting the entire log)
              type: object
            channelLogRewriteCollisions:
              description: >-
                Number of collisions while attempting to rewrite channel logs
                using SET
              type: object
            document_gets:
              description: Number of times a document was read from the database
              type: object
            revisionCache_adds:
              description: Number of revisions added to the revision cache
              type: object
            revisionCache_hits:
              description: Number of times a revision-cache lookup succeeded
              type: object
            revisionCache_misses:
              description: Number of times a revision-cache lookup failed
              type: object
            revs_added:
              description: Number of revisions added to the database (including deletions)
              type: object
            sequence_gets:
              description: Number of times the database's lastSequence was read
              type: object
            sequence_reserves:
              description: Number of times the database's lastSequence was incremented
              type: object
        syncgateway:
          description: Monitoring stats
          type: object
          properties:
            global:
              description: Global Sync Gateway stats
              type: object
              properties:
                resource_utilization:
                  description: Resource utilization stats
                  type: object
                  properties:
                    admin_net_bytes_recv:
                      type: integer
                      description: >-
                        The total number of bytes received (since node start-up)
                        on the network interface to which the Sync Gateway
                        api.admin_interface is bound.
                    admin_net_bytes_sent:
                      type: integer
                      description: >-
                        The total number of bytes sent (since node start-up) on
                        the network interface to which the Sync Gateway
                        api.admin_interface is bound.
                    error_count:
                      type: integer
                      description: The total number of errors logged.
                    go_memstats_heapalloc:
                      type: integer
                      description: >-
                        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).
                    go_memstats_heapidle:
                      type: integer
                      description: >-
                        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.
                    go_memstats_heapinuse:
                      type: integer
                      description: >-
                        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.
                    go_memstats_heapreleased:
                      type: integer
                      description: >-
                        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.
                    go_memstats_pausetotalns:
                      type: integer
                      description: >-
                        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.
                    go_memstats_stackinuse:
                      type: integer
                      description: >-
                        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).
                    go_memstats_stacksys:
                      type: integer
                      description: >-
                        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).
                    go_memstats_sys:
                      type: integer
                      description: >-
                        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.
                    goroutines_high_watermark:
                      type: integer
                      description: Peak number of go routines since process start.
                    num_goroutines:
                      type: integer
                      description: The total number of goroutines.
                    num_idle_kv_ops:
                      type: integer
                      description: The total number of idle kv operations.
                    num_idle_query_ops:
                      type: integer
                      description: The total number of idle query operations.
                    process_cpu_percent_utilization:
                      type: number
                      format: float
                      description: >-
                        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.
                    node_cpu_percent_utilization:
                      type: number
                      format: float
                      description: >-
                        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.
                    process_memory_resident:
                      type: integer
                      description: >-
                        The memory utilization (Resident Set Size) for the
                        process, in bytes.
                    pub_net_bytes_recv:
                      type: integer
                      description: >-
                        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
                    pub_net_bytes_sent:
                      type: integer
                      description: >-
                        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.
                    system_memory_total:
                      type: integer
                      description: The total memory available on the system in bytes.
                    warn_count:
                      type: integer
                      description: The total number of warnings logged.
                    uptime:
                      type: integer
                      description: The total uptime.
            per_db:
              description: >-
                This array contains stats for all databases declared in the
                config file &mdash; see [View Statistics and
                Metrics](stats-monitoring.html) for more details on the metrics
                collected and reported by Sync Gateway.


                The statistics for each 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`
              type: array
              items:
                type: object
                properties:
                  cache:
                    type: object
                  database:
                    type: object
                  per_replication:
                    type: object
                  collections:
                    type: object
                  security:
                    type: object
            per_replication:
              description: >-
                An array of stats for each replication declared in the config
                file

                **Deprecated @ 2.8**: used only by inter-sync-gateway
                replications version 1.
              type: array
              items:
                type: object
                description: Stats for a given replication_id
                properties:
                  $replication_id:
                    type: object
                    properties:
                      sgr_active:
                        description: >-
                          Whether the replication is active at this time.

                          **Deprecated @ 2.8**: used only by inter-sync-gateway
                          replications version 1.
                        type: boolean
                      sgr_docs_checked_sent:
                        description: >-
                          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.
                        type: integer
                      sgr_num_attachments_transferred:
                        description: >-
                          The total number of attachments transferred since
                          replication started.

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

                          **Deprecated @ 2.8**: used only by inter-sync-gateway
                          replications version 1.
                        type: integer
                      sgr_num_docs_failed_to_push:
                        description: >-
                          The total number of documents that failed to be pushed
                          since replication started.

                          Used by versions 1 and 2.
                        type: integer
                      sgr_num_docs_pushed:
                        description: >-
                          The total number of documents that were pushed since
                          replication started.

                          Used by versions 1 and 2.
                        type: integer
              deprecated: true

