DOC-12841: Metrics REST API doc fixes

modules/ROOT/assets/attachments/bundled-admin.yaml

@@ -1,8 +1,11 @@
 openapi: 3.0.3
 info:
-  title: Sync Gateway
-  description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
   version: '3.2'
+  title: Sync Gateway Admin REST API
+  description: |-
+    # Introduction
+
+    The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode.
   license:
     name: Business Source License 1.1 (BSL)
     url: https://github.com/couchbase/sync_gateway/blob/master/LICENSE
@@ -45,8 +48,8 @@ tags:
   - name: Unsupported
     description: Endpoints that are not supported by Sync Gateway
 externalDocs:
-  description: Sync Gateway Quickstart | Couchbase Docs
-  url: https://docs.couchbase.com/sync-gateway/current/index.html
+  description: ⬆️ Admin REST API Overview
+  url: rest-api-admin.html
 paths:
   /{db}/_session:
     parameters:
@@ -3935,12 +3938,16 @@ paths:
                         type: object
                         properties:
                           size:
-                            description: The maximum number of revisions that can be stored in the revision cache.
+                            description: |-
+                              The maximum number of revisions that can be stored in the revision cache.
+                              Note when running with greater than 1 shard count we add 10% capacity overall to avoid early eviction when some shards fill up before others, so
+                              you may find that the capacity stat (revision_cache_num_items) will climb to the defined rev cache size + 10%.
                             type: string
                             default: 5000
                           max_memory_count_mb:
                             description: |-
                               The maximum amount of memory the revision cache should take up in MB, setting to 0 will disable any eviction based on memory at rev cache.
+                              There is a minimum value of 50 (50MB) for this config option.
                               When set this memory limit will work in in hand with revision cache size parameter. So you will potentially get eviction at revision cache both based off memory footprint and number of items in the cache.
                               **This is an Enterprise Edition feature only**
                             type: integer
@@ -6389,7 +6396,7 @@ paths:
       operationId: post_keyspace-
   /_expvar:
     get:
-      summary: Get all Sync Gateway statistics
+      summary: Get all Sync Gateway statistics in JSON format
       description: |-
         This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes.
 
@@ -6400,11 +6407,15 @@ paths:
         * Sync Gateway Architect
         * Sync Gateway Dev Ops
         * External Stats Reader
+      tags:
+        - JSON
       responses:
         '200':
-          description: Returned statistics
+          description: |-
+            Successfully returned statistics.
+            For details, see [JSON Metrics](stats-monitoring-json.html).
           content:
-            application/javascript:
+            application/json:
               schema:
                 type: object
                 properties: &ref_126
@@ -6537,6 +6548,9 @@ paths:
                               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
@@ -6565,8 +6579,9 @@ paths:
                                 description: The total uptime.
                       per_db:
                         description: |-
-                          This array contains stats for all databases declared in the config file -- see the [Sync Gateway Statistics Schema](./../stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway.
-                          The statistics for each {$db_name} database are grouped into:
+                          This array contains stats for all databases declared in the config file — 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
@@ -6637,8 +6652,6 @@ paths:
                                     Used by versions 1 and 2.
                                   type: integer
                         deprecated: true
-      tags:
-        - Metrics
       operationId: get__expvar
   /:
     get:

modules/ROOT/assets/attachments/bundled-metric.yaml

@@ -1,8 +1,12 @@
 openapi: 3.0.3
 info:
-  title: Sync Gateway
-  description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
   version: '3.2'
+  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.
   license:
     name: Business Source License 1.1 (BSL)
     url: https://github.com/couchbase/sync_gateway/blob/master/LICENSE
@@ -22,9 +26,13 @@ servers:
 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: Sync Gateway Quickstart | Couchbase Docs
-  url: https://docs.couchbase.com/sync-gateway/current/index.html
+  description: ⬆️ Metrics REST API Overview
+  url: rest-api-metrics.html
 paths:
   /_ping:
     get:
@@ -50,9 +58,9 @@ paths:
       summary: Check if API is available
       description: Returns OK status if API is available.
       operationId: head__ping
-  /_metrics:
-    get: &ref_0
-      summary: Debugging/monitoring runtime stats in Prometheus Exposition format
+  /metrics:
+    get:
+      summary: Get debugging and monitoring runtime stats in Prometheus Exposition format
       description: |-
         Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.
 
@@ -63,19 +71,15 @@ paths:
         * External Stats Reader
       responses:
         '200':
-          description: Successfully returned stats
-          content:
-            text/plain:
-              schema:
-                type: string
+          description: |-
+            Successfully returned statistics.
+            For details, see [Prometheus Metrics](stats-monitoring-prometheus.html).
       tags:
         - Prometheus
       operationId: get_metrics
-  /metrics:
-    get: *ref_0
   /_expvar:
     get:
-      summary: Get all Sync Gateway statistics
+      summary: Get all Sync Gateway statistics in JSON format
       description: |-
         This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes.
 
@@ -86,14 +90,18 @@ paths:
         * Sync Gateway Architect
         * Sync Gateway Dev Ops
         * External Stats Reader
+      tags:
+        - JSON
       responses:
         '200':
-          description: Returned statistics
+          description: |-
+            Successfully returned statistics.
+            For details, see [JSON Metrics](stats-monitoring-json.html).
           content:
-            application/javascript:
+            application/json:
               schema:
                 type: object
-                properties: &ref_1
+                properties: &ref_0
                   cmdline:
                     description: Built-in variables from the Go runtime, lists the command-line arguments
                     type: object
@@ -223,6 +231,9 @@ paths:
                               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
@@ -251,8 +262,9 @@ paths:
                                 description: The total uptime.
                       per_db:
                         description: |-
-                          This array contains stats for all databases declared in the config file -- see the [Sync Gateway Statistics Schema](./../stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway.
-                          The statistics for each {$db_name} database are grouped into:
+                          This array contains stats for all databases declared in the config file — 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
@@ -328,4 +340,4 @@ components:
   schemas:
     ExpVars:
       type: object
-      properties: *ref_1
+      properties: *ref_0

modules/ROOT/assets/attachments/bundled-public.yaml

@@ -1,8 +1,12 @@
 openapi: 3.0.3
 info:
-  title: Sync Gateway
-  description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
   version: '3.2'
+  title: Sync Gateway Public REST API
+  description: |-
+    # Introduction
+
+    Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server.
+    The Sync Gateway Public REST API is used for client replication.
   license:
     name: Business Source License 1.1 (BSL)
     url: https://github.com/couchbase/sync_gateway/blob/master/LICENSE
@@ -39,8 +43,8 @@ tags:
     description: Endpoints that are not supported by Sync Gateway
     x-capella: false
 externalDocs:
-  description: Sync Gateway Quickstart | Couchbase Docs
-  url: https://docs.couchbase.com/sync-gateway/current/index.html
+  description: ⬆️ Public REST API Overview
+  url: rest-api.html
 paths:
   /{db}/_session:
     parameters:

modules/ROOT/assets/overlays/admin.yaml

@@ -10,19 +10,12 @@ info:
 extends: ../attachments/bundled-admin.yaml
 
 actions:
-  - description: Update title and introduction
-    target: $.info
-    update:
-      title: Sync Gateway Admin REST API
-      description: |-
-        # Introduction
-
-        Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server.
-        The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode.
+  - description: Remove existing tags from the _expvar endpoint
+    target: $.paths['/_expvar'].get.tags
+    remove: true
 
-  - description: Update link to external docs
-    target: '$'
+  - description: Add the Metrics tag to the _expvar endpoint
+    target: $.paths['/_expvar'].get
     update:
-      externalDocs:
-        description: ⬆️ Admin REST API Overview
-        url: rest-api-admin.html
+      tags:
+        - Metrics

modules/ROOT/assets/overlays/metric.yaml

@@ -10,88 +10,11 @@ info:
 extends: ../attachments/bundled-metric.yaml
 
 actions:
-  - description: Update title and introduction
-    target: $.info
-    update:
-      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.
-
-  - description: Update link to external docs
-    target: '$'
-    update:
-      externalDocs:
-        description: ⬆️ Metrics REST API Overview
-        url: rest-api-metrics.html
-
-  - description: Add a tag for JSON metrics and description for the Server tag
-    target: '$'
-    update:
-      tags:
-        - name: JSON
-          description: Endpoints for use with JSON metrics
-        - name: Server
-          description: Endpoints for managing the REST API
-
-  - description: Add the JSON tag to the _expvar endpoint
-    target: $.paths['/_expvar'].get
-    update:
-      tags:
-        - JSON
-
-  - description: Update summary of the _expvar endpoint
-    target: $.paths['/_expvar'].get
-    update:
-      summary: Get all Sync Gateway statistics in JSON format
-
-  - description: Update description for the JSON metrics endpoint
-    target: $.paths['/_expvar'].get.responses.200
-    update:
-      description: |-
-          Successfully returned statistics.
-          For details, see [JSON Metrics](stats-monitoring-json.html).
-
-  - description: Remove the duplicate metrics endpoint
-    target: $.paths['/_metrics']
-    remove: true
-
-  - description: Update the description for the Sync Gateway `per_db` response
-    target: $.paths['/_expvar'].get.responses.200.content['application/javascript'].schema.properties.syncgateway.properties.per_db
-    update:
-      description: |-
-        This array contains stats for all databases declared in the config file — 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`
-
-  - description: Fix name of Prometheus method
-    target: $.paths['/metrics'].get
-    update:
-      summary: Get debugging and monitoring runtime stats in Prometheus Exposition format
-
   - description: Add Prometheus metrics
     target: $.paths['/metrics'].get.responses
     update:
       '200':
-        description: |-
-          Successfully returned statistics.
-          For details, see [Prometheus Metrics](stats-monitoring-prometheus.html).
         content:
           application/json:
             schema:
               $ref: metrics_metadata.json
-
-  - description: Remove the plain text Prometheus response.
-    target: $.paths['/metrics'].get.responses.200.content['text/plain']
-    remove: true

modules/ROOT/assets/overlays/public.yaml

@@ -10,19 +10,7 @@ info:
 extends: ../attachments/bundled-public.yaml
 
 actions:
-  - description: Update introduction
-    target: $.info
-    update:
-      title: Sync Gateway Public REST API
-      description: |-
-        # Introduction
-
-        Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server.
-        The Sync Gateway Public REST API is used for client replication.
-
-  - description: Update link to external docs
+  - description: Dummy action (no changes required)
     target: '$'
     update:
-      externalDocs:
-        description: ⬆️ Public REST API Overview
-        url: rest-api.html
+      x-overlaid: false