DOC-13717 rest api for app telemetry by ggray-cb · Pull Request #4088 · couchbase/docs-server

ggray-cb · 2026-02-13T22:16:37Z

This PR adds documentation for the Server /settings/appTelemetry REST API endpoint.

Here's a list of the changes in this PR, with links to a preview. You will need the Docs Team credentials on Confluence to access the preview.

Added new Application Telemetry page that explains getting and configuring telemetry settings.
Added a short section to Configure Prometheus to Collect Couchbase Metrics explaining that you can add application metrics to the Prometheus endpoint by enabling application telemetry. It seemed like the right place to mention that.

Note: I've made some assumptions about the maxScrapeClientsPerNode and scrapeIntervalSeconds settings, so be sure to pay special attention to their descriptions.

Copilot

Pull request overview

Adds Couchbase Server documentation for the /settings/appTelemetry REST API and cross-links it from Prometheus monitoring docs and navigation.

Changes:

Adds a new REST API reference page for Application Telemetry (/settings/appTelemetry) with GET/POST examples and parameter descriptions.
Updates Prometheus monitoring docs to mention enabling application telemetry to expose SDK/application metrics.
Updates shared REST API curl parameter partial and adds the new page to the REST API navigation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

File	Description
modules/rest-api/partials/user-pw-host-port-params.adoc	Updates the shared parameter definitions for host/port used by REST API curl examples.
modules/rest-api/pages/application-telemetry.adoc	New REST API reference page for application telemetry status and configuration.
modules/manage/pages/monitor/set-up-prometheus-for-monitoring.adoc	Adds a section describing how application telemetry affects Prometheus metrics output.
modules/ROOT/nav.adoc	Adds the new REST API page to the documentation navigation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-13T22:19:53Z

modules/rest-api/partials/user-pw-host-port-params.adoc

+`host`::
+Hostname or IP address of a Couchbase Server node.

-`PORT`::
+`port`::
 Port number for the REST API. 


The parameter-name placeholders were changed to host/port, but many existing REST API pages still use {HOST}/{PORT} in their curl examples (for example, disk-usage-limits.adoc). This makes the shared parameter list inconsistent with the rest of the docs; consider reverting to HOST/PORT (or documenting both) and aligning placeholder casing across pages.

Copilot · 2026-02-13T22:19:54Z

modules/rest-api/pages/application-telemetry.adoc

+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+     -X GET 'http[s]://{host}:{port}/settings/appTelemetry' 


This curl example uses {host}/{port} placeholders, but most REST API docs use {HOST}/{PORT}. Consider switching to the established placeholder casing (and matching whatever is documented in user-pw-host-port-params.adoc) to keep examples consistent.

Suggested change

-X GET 'http[s]://{host}:{port}/settings/appTelemetry'

-X GET 'http[s]://{HOST}:{PORT}/settings/appTelemetry'

Copilot · 2026-02-13T22:19:54Z

modules/rest-api/pages/application-telemetry.adoc

+
+* `enabled`: whether application telemetry is enabled or not.
+* `maxScrapeClientsPerNode`: the maximum number of clients from which a single node can scrape telemetry data at the same time.
+* `scrapeIntervalSeconds`: how often clients scrape telemetry data from the nodes, in seconds.


The response-field description for scrapeIntervalSeconds says "how often clients scrape telemetry data from the nodes", but earlier the page describes Couchbase Server scraping/pulling telemetry data from SDK clients. Update this description so the directionality is consistent (nodes/server scrape clients).

Suggested change

* `scrapeIntervalSeconds`: how often clients scrape telemetry data from the nodes, in seconds.

* `scrapeIntervalSeconds`: how often each node scrapes telemetry data from connected clients, in seconds.

Copilot · 2026-02-13T22:19:54Z

modules/rest-api/pages/application-telemetry.adoc

+
+[#gey-state-example]


Anchor ID looks like a typo: gey-state-example (missing the 't' in 'get'). If this is meant to be "get-state-example", rename it to avoid broken/unclear anchors.

Suggested change

[#gey-state-example]

[#get-state-example]

Copilot · 2026-02-13T22:19:54Z

modules/rest-api/pages/application-telemetry.adoc

+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+  -X POST http://{host}:{port}/settings/encryptionKeys \


The POST curl syntax points at /settings/encryptionKeys, but this page and the endpoint definition above describe /settings/appTelemetry. Update the example URL so it posts to the correct endpoint.

Suggested change

-X POST http://{host}:{port}/settings/encryptionKeys \

-X POST http://{host}:{port}/settings/appTelemetry \

Copilot · 2026-02-13T22:19:55Z

modules/rest-api/pages/application-telemetry.adoc

+
+`maxScrapeClientsPerNode` (integer, optional)::
+Set the maximum number of clients from which a single node can scrape telemetry data at the same time.
+If the number of client telemetry connections reaches this threshold, the node rejects new telemetry connections until the number of connect clients drops.


Typo in this sentence: "number of connect clients" should be "number of connected clients".

Suggested change

If the number of client telemetry connections reaches this threshold, the node rejects new telemetry connections until the number of connect clients drops.

If the number of client telemetry connections reaches this threshold, the node rejects new telemetry connections until the number of connected clients drops.

Copilot · 2026-02-13T22:19:55Z

modules/rest-api/pages/application-telemetry.adoc

+** xref:cxx-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[C++ SDK]
+** xref:go-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Go SDK]
+** xref:java-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Java SDK]
+** xref:kotlin-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Python SDK]


The Python SDK link uses the kotlin-sdk component in the xref target. This should likely be python-sdk (or the link text should be changed to Kotlin) to avoid a broken/misdirected cross-reference.

Suggested change

** xref:kotlin-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Python SDK]

** xref:python-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Python SDK]

Copilot · 2026-02-13T22:19:55Z

modules/manage/pages/monitor/set-up-prometheus-for-monitoring.adoc

+
+You can enable application telemetry to have Couchbase Server collect metrics from your applications that use the Couchbase SDKs. 
+When you enable application telemetry, Couchbase Server collects telemetry data from your applications. 
+It the reports the collected data as metrics through the same Prometheus endpoint that it uses to report its own metrics. 


Typo: "It the reports" should be "It then reports" (or similar).

Suggested change

It the reports the collected data as metrics through the same Prometheus endpoint that it uses to report its own metrics.

It then reports the collected data as metrics through the same Prometheus endpoint that it uses to report its own metrics.

ingenthr

Nice work on this @ggray-cb . We're getting a number of questions about this functionality, so it'll be great to see it in the docs.

I had a few small comments and @shivaniguptacb may want to review. Also, it looks like copilot caught a few important things (like the kotlin/python ambiguity).

ingenthr · 2026-02-13T23:11:11Z

modules/rest-api/pages/application-telemetry.adoc

+Valid values are from `1` to `1024`. 
+
+
+The default value is `1024`.


Are there any sentinel values like 0 which indicate unlimited?

How would a user know when the limit is being hit?

@avsej or @timofey-barmin may know this off the top of their heads.

ingenthr · 2026-02-13T23:21:37Z

modules/rest-api/pages/application-telemetry.adoc

+
+* xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[]
+
+* See the SDK Telemetry from the Server section of the Collecting Information and Logging page in the documentation for the SDK you use.


Somewhere in here we should mention the SDK-API level required to get AppTelemetry from the SDK. @RichardSmedley might have a good way to communicate this.

To get details, most users will need to update both their SDK, and the cluster, and enable it. As currently written, the SDK side requirement is possibly missed.

Another requirement which we may want to mention is that this feature requires the management port to be exposed from cluster to client (typically port 8091/18091, but can be different with alt-address).

shivaniguptasf · 2026-02-13T23:55:55Z

Nice work!
One small thing - I didn't see a mention that in 8.0 it is disabled by default. Might want to add that both to the Server Monitoring page, and to the REST API reference page that you added.

ggray-cb added 4 commits February 13, 2026 15:27

First draft

8aaa876

some minor fixups

b452601

Some touchups

856141f

Added anchor

60b3226

ggray-cb requested review from Copilot, ingenthr and shivaniguptasf February 13, 2026 22:16

Copilot started reviewing on behalf of ggray-cb February 13, 2026 22:17 View session

Copilot AI reviewed Feb 13, 2026

View reviewed changes

ingenthr requested changes Feb 13, 2026

View reviewed changes

	-X GET 'http[s]://{host}:{port}/settings/appTelemetry'
	-X GET 'http[s]://{HOST}:{PORT}/settings/appTelemetry'

	* `scrapeIntervalSeconds`: how often clients scrape telemetry data from the nodes, in seconds.
	* `scrapeIntervalSeconds`: how often each node scrapes telemetry data from connected clients, in seconds.

	-X POST http://{host}:{port}/settings/encryptionKeys \
	-X POST http://{host}:{port}/settings/appTelemetry \

	If the number of client telemetry connections reaches this threshold, the node rejects new telemetry connections until the number of connect clients drops.
	If the number of client telemetry connections reaches this threshold, the node rejects new telemetry connections until the number of connected clients drops.

	** xref:kotlin-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Python SDK]
	** xref:python-sdk:howtos:collecting-information-and-logging.adoc#sdk-telemetry-from-the-server[Python SDK]

	It the reports the collected data as metrics through the same Prometheus endpoint that it uses to report its own metrics.
	It then reports the collected data as metrics through the same Prometheus endpoint that it uses to report its own metrics.


		* xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[]

		* See the SDK Telemetry from the Server section of the Collecting Information and Logging page in the documentation for the SDK you use.

Conversation

ggray-cb commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

ingenthr left a comment

Choose a reason for hiding this comment

Uh oh!

ingenthr Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

ingenthr Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

shivaniguptasf commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants