From 3e65149f3b453061ef0164424200779662f8079a Mon Sep 17 00:00:00 2001 From: Catalina A Date: Thu, 9 Jul 2026 11:36:39 +0300 Subject: [PATCH 1/6] [DOC] Update data retention API documentation for clarity and consistency --- api/server/v1/server.proto | 2 +- .../pmm-server-config/pmm-server-settings.md | 54 ++++++++++++++++++- .../docs/configure-pmm/advanced_settings.md | 6 +++ 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/api/server/v1/server.proto b/api/server/v1/server.proto index 51dc8b8f975..3e22fc27305 100644 --- a/api/server/v1/server.proto +++ b/api/server/v1/server.proto @@ -221,7 +221,7 @@ message ChangeSettingsRequest { optional bool enable_updates = 1; optional bool enable_telemetry = 2; MetricsResolutions metrics_resolutions = 3; - // A number of full days for Prometheus and QAN data retention. Should have a suffix in JSON: 2592000s, 43200m, 720h. + // A number of full days for Prometheus and QAN data retention. Must be specified in seconds in JSON, for example: 2592000s. google.protobuf.Duration data_retention = 4; optional string ssh_key = 5; optional common.StringArray aws_partitions = 6; diff --git a/documentation/api/pmm-server-config/pmm-server-settings.md b/documentation/api/pmm-server-config/pmm-server-settings.md index 5b356fd201d..f180a6869ae 100644 --- a/documentation/api/pmm-server-config/pmm-server-settings.md +++ b/documentation/api/pmm-server-config/pmm-server-settings.md @@ -1,5 +1,5 @@ --- -title: PMM Server Settings +title: Configure PMM Server settings slug: pmm-server-settings category: uri: pmm-server-maintenance @@ -8,4 +8,54 @@ privacy: view: anyone_with_link --- -This section will explain how to configure your PMM Server to get the most out of its functionality. +You can use the PMM Server Settings API to retrieve and update your PMM Server configuration programmatically. Use [Get settings](ref:getsettings) to check the current configuration, and [Change settings](ref:changesettings) to update it. + +## Get current settings + +```sh +curl -X GET https:///v1/server/settings \ + -H "Authorization: Basic " +``` + +## Change settings + +```sh +curl -X PUT https:///v1/server/settings \ + -H "Authorization: Basic " \ + -H "Content-Type: application/json" \ + -d '{"data_retention": "2592000s"}' +``` + +## Field reference + +### data_retention + +Use this field to set how long PMM retains Prometheus and QAN data. You must express the value in seconds. If you use hours or minutes, the request will fail with an error. + +| Format | Example | Supported | +|--------|---------|--------| +| Seconds | `2592000s` | ✔ | +| Minutes | `43200m` | ✘ | +| Hours | `720h` | ✘ | + +Common values: + +| Retention period | Value | +|-----------------|-------| +| 7 days | `604800s` | +| 30 days | `2592000s` | +| 90 days | `7776000s` | + +### metrics_resolutions + +Use this field to control how frequently PMM collects metrics. You can set high (`hr`), medium (`mr`), and low (`lr`) resolution intervals independently: + +```json +{ + "metrics_resolutions": { + "hr": "5s", + "mr": "10s", + "lr": "60s" + } +} +``` diff --git a/documentation/docs/configure-pmm/advanced_settings.md b/documentation/docs/configure-pmm/advanced_settings.md index 749d65eefd3..dd87c0ee019 100644 --- a/documentation/docs/configure-pmm/advanced_settings.md +++ b/documentation/docs/configure-pmm/advanced_settings.md @@ -6,6 +6,12 @@ **Data retention** specifies how long data is stored by PMM Server. By default, time-series data is stored for 30 days. You can adjust the data retention time to balance your system's available disk space with your metrics history requirements. +### Set data retention via the API + +If you configure data retention using the [Change Settings API](https://percona-pmm.readme.io/reference/changesettings) (`PUT /v1/server/settings`), express the value in seconds. Hours and minutes formats are not supported and will return an error. + +For example, to set 30-day retention: `"data_retention": "2592000s"` + ## Telemetry The **Telemetry** switch enables gathering and sending basic **anonymous** data to Percona, which helps us to determine where to focus the development and what is the uptake for each release of PMM. From 3fb254a56fa1af41d1de7cf4f12e949e57a3162a Mon Sep 17 00:00:00 2001 From: Catalina A Date: Thu, 9 Jul 2026 11:57:36 +0300 Subject: [PATCH 2/6] [DOC] Fix misleading data retention API documentation to prevent request failures --- documentation/docs/release-notes/3.9.0.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/docs/release-notes/3.9.0.md b/documentation/docs/release-notes/3.9.0.md index 72e6bcdaba3..7ca39cde384 100644 --- a/documentation/docs/release-notes/3.9.0.md +++ b/documentation/docs/release-notes/3.9.0.md @@ -73,7 +73,9 @@ For the full list of available collectors per database type, see [Connect MySQL - [PMM-15118](https://perconadev.atlassian.net/browse/PMM-15118): Fixed the **Oplog GB/Hour** panels in the **MongoDB ReplSet Summary**, **MongoDB Sharded Cluster Summary**, and **MongoDB Oplog Details** dashboards showing an empty metric name in the legend instead of the service name. -- [PMM-15114](https://perconadev.atlassian.net/browse/PMM-15114): Fixed the **Scanned and Moved Objects** panel in the **MongoDB Instance Summary** dashboard showing blank labels in the legend instead of the operation type (`scanned`, `scanned_objects`). +- [PMM-15114](https://perconadev.atlassian.net/browse/PMM-15114): Fixed the **Scanned and Moved Objects** panel in the **MongoDB Instance Summary** dashboard showing blank labels in the legend instead of the operation type (`scanned`, `scanned_objects`). + +- [PMM-13911](https://perconadev.atlassian.net/browse/PMM-13911): Fixed misleading API documentation that caused `data_retention` requests to fail. If you set data retention via the [Change Settings](https://percona-pmm.readme.io/reference/changesettings) API, use seconds only (for example, `2592000s` for 30 days). Hours and minutes are not accepted. From 0d76274b76a6d96b66830a7a92dd47de4af1fd6f Mon Sep 17 00:00:00 2001 From: Catalina A Date: Thu, 9 Jul 2026 14:45:38 +0300 Subject: [PATCH 3/6] removed extra entry --- documentation/docs/release-notes/3.9.0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/documentation/docs/release-notes/3.9.0.md b/documentation/docs/release-notes/3.9.0.md index 7ca39cde384..762f43a68a3 100644 --- a/documentation/docs/release-notes/3.9.0.md +++ b/documentation/docs/release-notes/3.9.0.md @@ -73,8 +73,6 @@ For the full list of available collectors per database type, see [Connect MySQL - [PMM-15118](https://perconadev.atlassian.net/browse/PMM-15118): Fixed the **Oplog GB/Hour** panels in the **MongoDB ReplSet Summary**, **MongoDB Sharded Cluster Summary**, and **MongoDB Oplog Details** dashboards showing an empty metric name in the legend instead of the service name. -- [PMM-15114](https://perconadev.atlassian.net/browse/PMM-15114): Fixed the **Scanned and Moved Objects** panel in the **MongoDB Instance Summary** dashboard showing blank labels in the legend instead of the operation type (`scanned`, `scanned_objects`). - - [PMM-13911](https://perconadev.atlassian.net/browse/PMM-13911): Fixed misleading API documentation that caused `data_retention` requests to fail. If you set data retention via the [Change Settings](https://percona-pmm.readme.io/reference/changesettings) API, use seconds only (for example, `2592000s` for 30 days). Hours and minutes are not accepted. From 4375303fbc9f21c26d96bc1c452e92d37e35fc19 Mon Sep 17 00:00:00 2001 From: Alex Demidoff Date: Fri, 10 Jul 2026 12:19:50 +0300 Subject: [PATCH 4/6] chore: regenerate swagger specs --- .../v1/json/client/server_service/change_settings_responses.go | 2 +- api/server/v1/json/v1.json | 2 +- api/server/v1/server.pb.go | 2 +- api/swagger/swagger-dev.json | 2 +- api/swagger/swagger.json | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api/server/v1/json/client/server_service/change_settings_responses.go b/api/server/v1/json/client/server_service/change_settings_responses.go index 1d956a34756..e1af786d165 100644 --- a/api/server/v1/json/client/server_service/change_settings_responses.go +++ b/api/server/v1/json/client/server_service/change_settings_responses.go @@ -195,7 +195,7 @@ type ChangeSettingsBody struct { // enable telemetry EnableTelemetry *bool `json:"enable_telemetry,omitempty"` - // A number of full days for Prometheus and QAN data retention. Should have a suffix in JSON: 2592000s, 43200m, 720h. + // A number of full days for Prometheus and QAN data retention. Must be specified in seconds in JSON, for example: 2592000s. DataRetention string `json:"data_retention,omitempty"` // ssh key diff --git a/api/server/v1/json/v1.json b/api/server/v1/json/v1.json index bf2ad5c8718..34bc7ced76a 100644 --- a/api/server/v1/json/v1.json +++ b/api/server/v1/json/v1.json @@ -406,7 +406,7 @@ "x-order": 2 }, "data_retention": { - "description": "A number of full days for Prometheus and QAN data retention. Should have a suffix in JSON: 2592000s, 43200m, 720h.", + "description": "A number of full days for Prometheus and QAN data retention. Must be specified in seconds in JSON, for example: 2592000s.", "type": "string", "x-order": 3 }, diff --git a/api/server/v1/server.pb.go b/api/server/v1/server.pb.go index b5772139c0a..3af6cdc2b52 100644 --- a/api/server/v1/server.pb.go +++ b/api/server/v1/server.pb.go @@ -1544,7 +1544,7 @@ type ChangeSettingsRequest struct { EnableUpdates *bool `protobuf:"varint,1,opt,name=enable_updates,json=enableUpdates,proto3,oneof" json:"enable_updates,omitempty"` EnableTelemetry *bool `protobuf:"varint,2,opt,name=enable_telemetry,json=enableTelemetry,proto3,oneof" json:"enable_telemetry,omitempty"` MetricsResolutions *MetricsResolutions `protobuf:"bytes,3,opt,name=metrics_resolutions,json=metricsResolutions,proto3" json:"metrics_resolutions,omitempty"` - // A number of full days for Prometheus and QAN data retention. Should have a suffix in JSON: 2592000s, 43200m, 720h. + // A number of full days for Prometheus and QAN data retention. Must be specified in seconds in JSON, for example: 2592000s. DataRetention *durationpb.Duration `protobuf:"bytes,4,opt,name=data_retention,json=dataRetention,proto3" json:"data_retention,omitempty"` SshKey *string `protobuf:"bytes,5,opt,name=ssh_key,json=sshKey,proto3,oneof" json:"ssh_key,omitempty"` AwsPartitions *common.StringArray `protobuf:"bytes,6,opt,name=aws_partitions,json=awsPartitions,proto3,oneof" json:"aws_partitions,omitempty"` diff --git a/api/swagger/swagger-dev.json b/api/swagger/swagger-dev.json index eae21cc28ae..80b380d0057 100644 --- a/api/swagger/swagger-dev.json +++ b/api/swagger/swagger-dev.json @@ -32365,7 +32365,7 @@ "x-order": 2 }, "data_retention": { - "description": "A number of full days for Prometheus and QAN data retention. Should have a suffix in JSON: 2592000s, 43200m, 720h.", + "description": "A number of full days for Prometheus and QAN data retention. Must be specified in seconds in JSON, for example: 2592000s.", "type": "string", "x-order": 3 }, diff --git a/api/swagger/swagger.json b/api/swagger/swagger.json index 1354228fd8e..6dac0658b98 100644 --- a/api/swagger/swagger.json +++ b/api/swagger/swagger.json @@ -31392,7 +31392,7 @@ "x-order": 2 }, "data_retention": { - "description": "A number of full days for Prometheus and QAN data retention. Should have a suffix in JSON: 2592000s, 43200m, 720h.", + "description": "A number of full days for Prometheus and QAN data retention. Must be specified in seconds in JSON, for example: 2592000s.", "type": "string", "x-order": 3 }, From 2eef7b2dc05fa74ef9f27af7063f87de358a32a6 Mon Sep 17 00:00:00 2001 From: Catalina A <94133018+catalinaadam@users.noreply.github.com> Date: Fri, 10 Jul 2026 12:22:27 +0300 Subject: [PATCH 5/6] Update documentation/api/pmm-server-config/pmm-server-settings.md Co-authored-by: Alex Demidoff --- documentation/api/pmm-server-config/pmm-server-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/api/pmm-server-config/pmm-server-settings.md b/documentation/api/pmm-server-config/pmm-server-settings.md index f180a6869ae..9b92c3d3bce 100644 --- a/documentation/api/pmm-server-config/pmm-server-settings.md +++ b/documentation/api/pmm-server-config/pmm-server-settings.md @@ -14,7 +14,7 @@ You can use the PMM Server Settings API to retrieve and update your PMM Server c ```sh curl -X GET https:///v1/server/settings \ - -H "Authorization: Basic " + -H "Authorization: Bearer glsa_xxxxx" ``` ## Change settings From a36a5ba492af067ed5653a17aefde6233f1f4cdd Mon Sep 17 00:00:00 2001 From: Catalina A Date: Fri, 10 Jul 2026 12:25:20 +0300 Subject: [PATCH 6/6] [DOC] Use Bearer token auth in API examples (PMM-13911) Replace Basic Auth with Service Account Token per reviewer feedback, consistent with the rest of the documentation. Co-Authored-By: Claude Sonnet 4.6 --- documentation/api/pmm-server-config/pmm-server-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/api/pmm-server-config/pmm-server-settings.md b/documentation/api/pmm-server-config/pmm-server-settings.md index 9b92c3d3bce..c3227ed7cd2 100644 --- a/documentation/api/pmm-server-config/pmm-server-settings.md +++ b/documentation/api/pmm-server-config/pmm-server-settings.md @@ -21,7 +21,7 @@ curl -X GET https:///v1/server/settings \ ```sh curl -X PUT https:///v1/server/settings \ - -H "Authorization: Basic " \ + -H "Authorization: Bearer glsa_xxxxx" \ -H "Content-Type: application/json" \ -d '{"data_retention": "2592000s"}' ```