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 e32c3517..7a18330c 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -155,25 +155,45 @@ 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; 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; 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) -Please find the mapping table below: +!!! warning -| AWS SDK v1 value | AWS SDK v2 value | -|------------------|------------------| -| `LogDebug` | `Request`
`Response`| -| `Signing` | `Signing`| -| `HTTPBody` | `RequestWithBody`
`ResponseWithBody`| -| `RequestRetries` | `DebugWithRequestRetries`| -| `RequestErrors` | `DebugWithRequestErrors`| -| `EventStreamBody`| `RequestWithBody`
`ResponseWithBody`| + `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: -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) +| Deprecated value | Automatically translated into | +|------------------|---------------------------------------| +| `LogDebug` | `Request`,`Response` | +| `HTTPBody` | `RequestWithBody`, `ResponseWithBody` | +| `RequestRetries` | `Retries` | +| `RequestErrors` | `Response` | +| `EventStreamBody`| `RequestWithBody`, `ResponseWithBody` | -When undefined, no S3 debug logging is performed. +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#logging-configuration-options). + +#### Example +Here's an example and recommended configuration when troubleshooting AWS S3 communication: + +```yaml +storage: + type: s3 + s3: + debugLogLevels: RequestWithBody, ResponseWithBody +``` ### storage.s3.insecureSkipTLSVerify