From 6354c90a0ec528b62548493bc3b4c532724947e6 Mon Sep 17 00:00:00 2001 From: radoslawszulgo Date: Wed, 8 Apr 2026 14:21:06 +0200 Subject: [PATCH 1/7] PBM-1720 Improve documentation and implementation for S3 storage debug log levels (storage.s3.debugLogLevels) --- docs/reference/configuration-options.md | 42 +++++++++++++++++-------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index e32c3517..c4f069e6 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -155,25 +155,41 @@ The [storage class :octicons-link-external-16:](https://aws.amazon.com/s3/storag *Type*: string
*Required*: NO -Enables S3 debug logging for different types of S3 requests. S3 log messages are printed in the `pbm logs` output. +Enables AWS S3 debug logging for different types of AWS S3 requests. AWS S3 log messages are printed in the `pbm logs` output. Possible values: -Starting with version 2.10.0, PBM uses AWS SDK v2. The AWS SDK v1 values are deprecated. They are kept for backward compatibility. +- `Signing` - logs the request signing process +- `Retries` - logs each retry attempt when a request fails with a retryable error, including the retry count +- `Request` - logs outgoing HTTP request metadata (method, URL, headers) without the body +- `RequestWithBody` - logs outgoing HTTP requests, including the full request body +- `Response` - logs incoming HTTP response metadata (status code, headers) without the body +- `ResponseWithBody` - logs incoming HTTP responses, including the full response body +- `DeprecatedUsage` - logs deprecated usage of AWS S3 endpoints +- `RequestEventMessage` - logs individual event stream messages written/sent from the client to the AWS S3 (request events) +- `ResponseEventMessage` -logs individual event stream messages read/received by the client from the AWS S3 (response events) -Please find the mapping table below: +Additionally, for backward compatibility with PBM versions older than 2.10.0, following deprecated options are possible: -| AWS SDK v1 value | AWS SDK v2 value | -|------------------|------------------| -| `LogDebug` | `Request`
`Response`| -| `Signing` | `Signing`| -| `HTTPBody` | `RequestWithBody`
`ResponseWithBody`| -| `RequestRetries` | `DebugWithRequestRetries`| -| `RequestErrors` | `DebugWithRequestErrors`| -| `EventStreamBody`| `RequestWithBody`
`ResponseWithBody`| +| Deprecated value | Automatically translated into | +|------------------|---------------------------------------| +| `LogDebug` | `Request`,`Response` | +| `HTTPBody` | `RequestWithBody`, `ResponseWithBody` | +| `RequestRetries` | `Retries` | +| `RequestErrors` | `Response` | +| `EventStreamBody`| `RequestWithBody`, `ResponseWithBody` | +To specify several event types, separate them by comma. When undefined, no S3 debug logging is performed. -To specify several event types, separate them by comma. To lean more about the event types, see [the documentation :octicons-link-external-16:](https://pkg.go.dev/github.com/aws/aws-sdk-go@v1.40.7/aws#LogLevelType) +Note, this setting may result in excessive logging. By default, log entries are stored in a capped collection in your database. To redirect logs into a separate file, see [Logging configuration definition](../manage/logpath.md). -When undefined, no S3 debug logging is performed. +#### Example +Here's an example and recommended configuration when troubleshooting AWS S3 communication: + +```yaml +storage: + type: s3 + s3: + debugLogLevels: RequestWithBody, ResponseWithBody +``` ### storage.s3.insecureSkipTLSVerify From a42e404f035bacf81468ce2074f5dc7093ce0fa6 Mon Sep 17 00:00:00 2001 From: Radoslaw Szulgo Date: Wed, 8 Apr 2026 14:27:01 +0200 Subject: [PATCH 2/7] Update docs/reference/configuration-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/reference/configuration-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index c4f069e6..00ed49bd 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -165,7 +165,7 @@ Enables AWS S3 debug logging for different types of AWS S3 requests. AWS S3 log - `ResponseWithBody` - logs incoming HTTP responses, including the full response body - `DeprecatedUsage` - logs deprecated usage of AWS S3 endpoints - `RequestEventMessage` - logs individual event stream messages written/sent from the client to the AWS S3 (request events) -- `ResponseEventMessage` -logs individual event stream messages read/received by the client from the AWS S3 (response events) +- `ResponseEventMessage` - logs individual event stream messages read/received by the client from the AWS S3 (response events) Additionally, for backward compatibility with PBM versions older than 2.10.0, following deprecated options are possible: From 7a9da10598129d22fca5979c7a8e618fa925600b Mon Sep 17 00:00:00 2001 From: Radoslaw Szulgo Date: Wed, 8 Apr 2026 14:27:22 +0200 Subject: [PATCH 3/7] Update docs/reference/configuration-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/reference/configuration-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index 00ed49bd..de512921 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -167,7 +167,7 @@ Enables AWS S3 debug logging for different types of AWS S3 requests. AWS S3 log - `RequestEventMessage` - logs individual event stream messages written/sent from the client to the AWS S3 (request events) - `ResponseEventMessage` - logs individual event stream messages read/received by the client from the AWS S3 (response events) -Additionally, for backward compatibility with PBM versions older than 2.10.0, following deprecated options are possible: +Additionally, for backward compatibility with PBM versions older than 2.10.0, the following deprecated options are supported: | Deprecated value | Automatically translated into | |------------------|---------------------------------------| From b37c565289d53d236bad17943a3bfe142eedeb92 Mon Sep 17 00:00:00 2001 From: Radoslaw Szulgo Date: Wed, 8 Apr 2026 14:29:16 +0200 Subject: [PATCH 4/7] Update docs/reference/configuration-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/reference/configuration-options.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index de512921..563e00e7 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -160,13 +160,15 @@ Enables AWS S3 debug logging for different types of AWS S3 requests. AWS S3 log - `Signing` - logs the request signing process - `Retries` - logs each retry attempt when a request fails with a retryable error, including the retry count - `Request` - logs outgoing HTTP request metadata (method, URL, headers) without the body -- `RequestWithBody` - logs outgoing HTTP requests, including the full request body +- `RequestWithBody` - logs outgoing HTTP requests, including the full request body; may expose sensitive data such as object contents, credentials, tokens, or headers - `Response` - logs incoming HTTP response metadata (status code, headers) without the body -- `ResponseWithBody` - logs incoming HTTP responses, including the full response body +- `ResponseWithBody` - logs incoming HTTP responses, including the full response body; may expose sensitive data such as object contents, credentials, tokens, or headers - `DeprecatedUsage` - logs deprecated usage of AWS S3 endpoints - `RequestEventMessage` - logs individual event stream messages written/sent from the client to the AWS S3 (request events) -- `ResponseEventMessage` - logs individual event stream messages read/received by the client from the AWS S3 (response events) +- `ResponseEventMessage` -logs individual event stream messages read/received by the client from the AWS S3 (response events) +!!! warning + `RequestWithBody` and `ResponseWithBody` can log full HTTP payloads and related sensitive information. Enable them only temporarily for troubleshooting, and only in controlled environments where exposing object contents, credentials, tokens, or headers is acceptable. Additionally, for backward compatibility with PBM versions older than 2.10.0, the following deprecated options are supported: | Deprecated value | Automatically translated into | From 12d95385ffd32efa55106286f3afa1aa3f7b5986 Mon Sep 17 00:00:00 2001 From: radoslawszulgo Date: Wed, 8 Apr 2026 14:36:33 +0200 Subject: [PATCH 5/7] Update s3-storage file to consistency and cross-reference. --- docs/details/s3-storage.md | 5 ++++- docs/reference/configuration-options.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/details/s3-storage.md b/docs/details/s3-storage.md index 5ab60e0c..fec41818 100644 --- a/docs/details/s3-storage.md +++ b/docs/details/s3-storage.md @@ -119,7 +119,10 @@ serverSideEncryption: You can enable debug logging for different types of S3 requests in Percona Backup for MongoDB. Percona Backup for MongoDB prints S3 log messages in the `pbm logs` output so that you can debug and diagnose S3 request issues or failures. -To enable S3 debug logging, set the `storage.s3.DebugLogLevel` option in Percona Backup for MongoDB configuration. The supported values are: `LogDebug`, `Signing`, `HTTPBody`, `RequestRetries`, `RequestErrors`, `EventStreamBody`. +To enable S3 debug logging, set the `storage.s3.DebugLogLevel` option in Percona Backup for MongoDB configuration. The supported values are: `Signing`, `Retries`, `Request`, `RequestWithBody`, `Response`, `ResponseWithBody`, `DeprecatedUsage`, `RequestEventMessage`. Additionally, for backward compatibility with PBM versions older than 2.10.0, deprecated values are: `LogDebug`, `HTTPBody`, `RequestRetries`, `RequestErrors`, `EventStreamBody`. + +See [AWS S3 storage options](../reference/configuration-options.md#storage-s3-debugloglevel) for details and an example. + ### Storage classes diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index 563e00e7..f4b498d9 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -181,7 +181,7 @@ Additionally, for backward compatibility with PBM versions older than 2.10.0, th To specify several event types, separate them by comma. When undefined, no S3 debug logging is performed. -Note, this setting may result in excessive logging. By default, log entries are stored in a capped collection in your database. To redirect logs into a separate file, see [Logging configuration definition](../manage/logpath.md). +Note, this setting may result in excessive logging. By default, log entries are stored in a capped collection in your database. To redirect logs into a separate file, see [Logging configuration definition](../manage/logpath.md#logging-configuration-options). #### Example Here's an example and recommended configuration when troubleshooting AWS S3 communication: From 3a88a00ad42f4e64bbbc97638250654bf944e1b1 Mon Sep 17 00:00:00 2001 From: Radoslaw Szulgo Date: Wed, 8 Apr 2026 14:37:46 +0200 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Anastasia Alexandrova --- docs/reference/configuration-options.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index f4b498d9..53dd755c 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -168,7 +168,9 @@ Enables AWS S3 debug logging for different types of AWS S3 requests. AWS S3 log - `ResponseEventMessage` -logs individual event stream messages read/received by the client from the AWS S3 (response events) !!! warning + `RequestWithBody` and `ResponseWithBody` can log full HTTP payloads and related sensitive information. Enable them only temporarily for troubleshooting, and only in controlled environments where exposing object contents, credentials, tokens, or headers is acceptable. + Additionally, for backward compatibility with PBM versions older than 2.10.0, the following deprecated options are supported: | Deprecated value | Automatically translated into | From 99323dff5bcc7b39bc9b744d86ef7d5d1148a777 Mon Sep 17 00:00:00 2001 From: radoslawszulgo Date: Wed, 8 Apr 2026 15:38:38 +0200 Subject: [PATCH 7/7] fix whitespaces --- docs/reference/configuration-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index 53dd755c..7a18330c 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -165,7 +165,7 @@ Enables AWS S3 debug logging for different types of AWS S3 requests. AWS S3 log - `ResponseWithBody` - logs incoming HTTP responses, including the full response body; may expose sensitive data such as object contents, credentials, tokens, or headers - `DeprecatedUsage` - logs deprecated usage of AWS S3 endpoints - `RequestEventMessage` - logs individual event stream messages written/sent from the client to the AWS S3 (request events) -- `ResponseEventMessage` -logs individual event stream messages read/received by the client from the AWS S3 (response events) +- `ResponseEventMessage` - logs individual event stream messages read/received by the client from the AWS S3 (response events) !!! warning