Fix up S3 repo logging docs #4301
Conversation
✅ Vale Linting ResultsNo issues found on modified lines! |
🔍 Preview links for changed docs |
The docs about verbose logging from the AWS Java SDK only apply to the EOL v1 SDK that we stopped using in 9.1. This commit adjusts the documentation to reflect the new logger names from 9.1 onwards. However, due to elastic/elasticsearch#137556 there was no way to enable this logging at all in 9.1.0-9.1.8 and 9.2.0-9.2.2.
DaveCTurner
force-pushed
the
2025/12/11/repo-s3-logging
branch
from
4bd6582 to
90bef4e
Compare
|
I don't like how it renders the tab headers but I'm not sure what to do about that - any advice? 
|
|
Yeah ok nested tabs seem slightly nicer to use, still not ideal but better than what I had before 
|
shainaraskas
left a comment
shainaraskas
left a comment
There was a problem hiding this comment.
Given the differences between these tabs, I think that we can probably approach this in a more lightweight way to make maintaining this procedure a little more straightforward. Let me know what you think.
| Collect the {{es}} logs covering the time period of the failed analysis from all nodes in your cluster and share them with the supplier of your storage system along with the analysis response so they can use them to determine the problem. Refer to [Logging AWS SDK for Java Calls](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-logging.html) for further information, including details about other loggers that can be used to obtain even more verbose logs. | ||
| ::::: | ||
|
|
||
| :::::{applies-item} { "stack": "ga 9.1" } |
There was a problem hiding this comment.
I suggest using just one tab for 9.1+, and simplify the note:
:::{warning}
In the following patch versions of {{es}}, it is not possible to obtain more detailed logs from the AWS Java SDK. Use the logs from the storage system itself, or upgrade to a newer version of {{es}}.
* 9.1.0 to 9.1.9
* 9.2.0 to 9.2.3
:::
officially (and this was true prior to this docs system as well), we don't really document patch-level changes like this, because features shouldn't really be introduced in patches per semver. If you think this note is critical and would avoid significant support debt, we can definitely still include it.
There was a problem hiding this comment.
We could if you're sure but my concern is that we'd then have this warning in place for the rest of the 9.x series and as time passes it will become relevant to fewer and fewer users. Users are already pretty bad at ignoring even relevant admonitions so I don't think it's good psychology to have irrelevant ones too.
This isn't a new feature, it's a bug fix. I know we generally don't call out bugs but I think it'll cause frustration to try these instructions in a version with the bug and see no results nor any error and it won't be a great user experience to contact support and be pointed to the known-and-fixed bug report hidden in the release notes.
There was a problem hiding this comment.
we can tag the admonition with 9.1 and 9.2 to draw the relevant users' eyes as well. that's best done with the ranges thing we are juuuust waiting to be merged, but this syntax below should work right now
I believe people will likely just try do do this without seeing the admonition anyway, so the admonition is more there to catch them when it errors out and they read a little more deeply.
:::{warning}
:applies_to: {"stack": "ga 9.1, ga 9.2"}
In the following patch versions of {{es}}, it is not possible to obtain more detailed logs from the AWS Java SDK. Use the logs from the storage system itself, or upgrade to a newer version of {{es}}.
* 9.1.0 to 9.1.9
* 9.2.0 to 9.2.3
:::
There was a problem hiding this comment.
when it errors out
Sadly it doesn't error out, it just silently does nothing at all in the buggy versions so you can't tell whether you've done the config right or not.
But ok I'll trim this down to a 9.1-only tab with the warning and we can refine it soon. I guess eventually we could reduce it from a warning to a notice once these buggy versions are far enough behind us.
| ```console | ||
| PUT /_cluster/settings | ||
| { | ||
| "persistent": { | ||
| "logger.software.amazon.awssdk.request": "DEBUG" | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
as an even more lightweight alternative, consider just creating tabs for the code snippet, and skipping the logger name in the preamble
The docs about verbose logging from the AWS Java SDK only apply to the
EOL v1 SDK that we stopped using in 9.1. This commit adjusts the
documentation to reflect the new logger names from 9.1 onwards.
However, due to elastic/elasticsearch#137556 there was no way to enable
this logging at all in 9.1.0-9.1.8 and 9.2.0-9.2.2.