Encourage AWS SDK logging to be enabled to help with future issues and include in examples and best practices guides

[jeffbski-rga]

Describe the issue

We were stuck when trying to get to the bottom of an AbortError when using the lib-storage Upload to make a multi-part upload for S3. The AbortError gave us no indication of what the real problem was. After discussing with AWS, they suggested turning on the AWS SDK logging so we could get the requestIds that they could use to look in there system for more details.

Since we were not logging that value already, we looked for an easy way to get the value from the SDK logged and we came across the logging configuration. Enabling the logging we instantly found the requestIds but also the real cause of the error which was a RequestTimeout. #6763 Then we were able to determine that the problem came from upgrading from V2 to V3 but not changing the httpOptions.timeout to requestHandler.socketTimeout.

So AWS SDK logging was a real help and should be encouraged as a best practice by default, at least in regards to the error (and maybe warn) logging. Info is likely too much for normal use, but could be good for troubleshooting temporarily.

The developer guide for Logging AWS SDK for Javascript Calls was helpful in pointing us in the right direction, but I felt the document could be improved since it was very minimal. It would be good to indicate that production use should like likely include the error and possibly warn params, but that info should be used sparingly or maybe only temporarily for troubleshooting. Showing examples of the output would be helpful as well. The article suggests that you could even customize what is logged by providing your own logging functions, but an example would help one know what to do. Nice example in the @smithy/types Logger interface would be helpful too if one is coming from there.

I think enabling SDK client logging for errors should be a best practice and thus indicated in examples and developer guides. It is helpful to know that having the requestId could be useful for troubleshooting the errors with AWS.

If you want to limit the repetitiveness in examples then at least have a comment and link to a page where the config is specified with example and good explanations.

Links

• https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/logging-sdk-calls.html
• https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-types/Interface/Logger/
• Example docs which do not include logging (just a sampling since most examples exclude it)
  • https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#new-in-v35210
  • https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/javascript_s3_code_examples.html
  • https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/s3/client.js
  • https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/s3/actions/put-object.js
  • https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-storage/