From df18184a107eaded87f593c0c9fab3bc0e2c58c0 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Mon, 20 Jan 2025 11:36:28 -0500 Subject: [PATCH 1/4] CBG-4312 improve metrics documentation - remove /_metrics endpoint, which does not need public API documentation, as it never should have been implemented - change copy to match public docs for description - add links to upstream files --- docs/api/admin.yaml | 11 +++++++---- docs/api/components/schemas.yaml | 5 +++-- docs/api/metric.yaml | 18 ++++++++++++------ docs/api/paths/metric/_expvar.yaml | 8 ++++++-- docs/api/paths/metric/metrics.yaml | 8 +++----- docs/api/public.yaml | 12 ++++++++---- 6 files changed, 39 insertions(+), 23 deletions(-) diff --git a/docs/api/admin.yaml b/docs/api/admin.yaml index 7136a22fdb..135eeb6c48 100644 --- a/docs/api/admin.yaml +++ b/docs/api/admin.yaml @@ -8,8 +8,11 @@ openapi: 3.0.3 info: - title: Sync Gateway - description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server + 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. version: '3.3' license: name: Business Source License 1.1 (BSL) @@ -207,5 +210,5 @@ 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 diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 5cc7534516..f7284baf41 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -166,8 +166,9 @@ ExpVars: 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 diff --git a/docs/api/metric.yaml b/docs/api/metric.yaml index 990922052f..efc905880c 100644 --- a/docs/api/metric.yaml +++ b/docs/api/metric.yaml @@ -8,8 +8,12 @@ openapi: 3.0.3 info: - title: Sync Gateway - description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server + 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) @@ -30,8 +34,6 @@ servers: paths: /_ping: $ref: ./paths/common/_ping.yaml - /_metrics: - $ref: ./paths/metric/metrics.yaml /metrics: $ref: ./paths/metric/metrics.yaml /_expvar: @@ -39,6 +41,10 @@ paths: 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 diff --git a/docs/api/paths/metric/_expvar.yaml b/docs/api/paths/metric/_expvar.yaml index b57d9adcfe..518caea7fd 100644 --- a/docs/api/paths/metric/_expvar.yaml +++ b/docs/api/paths/metric/_expvar.yaml @@ -7,7 +7,7 @@ # software will be governed by the Apache License, Version 2.0, included in # the file licenses/APL2.txt. 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. @@ -18,9 +18,13 @@ get: * 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: schema: diff --git a/docs/api/paths/metric/metrics.yaml b/docs/api/paths/metric/metrics.yaml index 729260751d..9aade5e3c5 100644 --- a/docs/api/paths/metric/metrics.yaml +++ b/docs/api/paths/metric/metrics.yaml @@ -17,11 +17,9 @@ get: * 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 diff --git a/docs/api/public.yaml b/docs/api/public.yaml index 213a10e90e..3fee9b4e3a 100644 --- a/docs/api/public.yaml +++ b/docs/api/public.yaml @@ -8,8 +8,12 @@ openapi: 3.0.3 info: - title: Sync Gateway - description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server + 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. version: '3.3' license: name: Business Source License 1.1 (BSL) @@ -108,5 +112,5 @@ 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 From b4ec751e5576e944030730e54eca5d00a477072e Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Mon, 20 Jan 2025 12:35:56 -0500 Subject: [PATCH 2/4] Drop /_metrics to x-internal --- docs/api/metric.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/api/metric.yaml b/docs/api/metric.yaml index efc905880c..5e6533d956 100644 --- a/docs/api/metric.yaml +++ b/docs/api/metric.yaml @@ -34,6 +34,9 @@ servers: paths: /_ping: $ref: ./paths/common/_ping.yaml + /_metrics: + $ref: ./paths/metric/_metrics.yaml + x-internal: true /metrics: $ref: ./paths/metric/metrics.yaml /_expvar: From dcccaf5b6ff33b3e56d8724b1e264b286a479426 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Mon, 20 Jan 2025 12:44:35 -0500 Subject: [PATCH 3/4] Correct path --- docs/api/metric.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/metric.yaml b/docs/api/metric.yaml index 5e6533d956..07091722dc 100644 --- a/docs/api/metric.yaml +++ b/docs/api/metric.yaml @@ -35,7 +35,7 @@ paths: /_ping: $ref: ./paths/common/_ping.yaml /_metrics: - $ref: ./paths/metric/_metrics.yaml + $ref: ./paths/metric/metrics.yaml x-internal: true /metrics: $ref: ./paths/metric/metrics.yaml From f00dedbd19cb76acbeb05085ca7b4b877e908c86 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Thu, 30 Jan 2025 10:39:32 -0500 Subject: [PATCH 4/4] deduplicate admin /_expvar and metrics /_expvar fixup text --- docs/api/admin.yaml | 3 ++- docs/api/paths/admin/_expvar.yaml | 29 ----------------------------- docs/api/paths/metric/_expvar.yaml | 2 +- docs/api/paths/metric/metrics.yaml | 2 +- 4 files changed, 4 insertions(+), 32 deletions(-) delete mode 100644 docs/api/paths/admin/_expvar.yaml diff --git a/docs/api/admin.yaml b/docs/api/admin.yaml index 135eeb6c48..338f76b780 100644 --- a/docs/api/admin.yaml +++ b/docs/api/admin.yaml @@ -132,7 +132,8 @@ paths: '/{keyspace}/': $ref: './paths/admin/keyspace-.yaml' /_expvar: - $ref: ./paths/admin/_expvar.yaml + # use the same path as for metrics + $ref: ./paths/metric/_expvar.yaml /: $ref: ./paths/admin/-.yaml /_ping: diff --git a/docs/api/paths/admin/_expvar.yaml b/docs/api/paths/admin/_expvar.yaml deleted file mode 100644 index c3e53f154c..0000000000 --- a/docs/api/paths/admin/_expvar.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# Copyright 2022-Present Couchbase, Inc. -# -# Use of this software is governed by the Business Source License included -# in the file licenses/BSL-Couchbase.txt. As of the Change Date specified -# in that file, in accordance with the Business Source License, use of this -# software will be governed by the Apache License, Version 2.0, included in -# the file licenses/APL2.txt. -get: - summary: Get all Sync Gateway statistics - 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: Returned statistics - content: - application/javascript: - schema: - $ref: ../../components/schemas.yaml#/ExpVars - tags: - - Metrics - operationId: get__expvar diff --git a/docs/api/paths/metric/_expvar.yaml b/docs/api/paths/metric/_expvar.yaml index 518caea7fd..d1eb46e7dd 100644 --- a/docs/api/paths/metric/_expvar.yaml +++ b/docs/api/paths/metric/_expvar.yaml @@ -26,7 +26,7 @@ get: Successfully returned statistics. For details, see [JSON Metrics](stats-monitoring-json.html). content: - application/javascript: + application/json: schema: $ref: ../../components/schemas.yaml#/ExpVars operationId: get__expvar diff --git a/docs/api/paths/metric/metrics.yaml b/docs/api/paths/metric/metrics.yaml index 9aade5e3c5..e1f06dc580 100644 --- a/docs/api/paths/metric/metrics.yaml +++ b/docs/api/paths/metric/metrics.yaml @@ -6,7 +6,7 @@ # software will be governed by the Apache License, Version 2.0, included in # the file licenses/APL2.txt. get: - summary: Debugging/monitoring runtime stats in Prometheus Exposition format + summary: Get debugging and monitoring runtime stats in Prometheus Exposition format description: |- Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.