docs: add FAQ/troubleshooting and operation timing guide #2434
Conversation
content/en/docs/faq/_index.md
Outdated
| ### How should I configure operation timeouts? | ||
|
|
||
| Much like the previous question, it depends. **The answer to this question, | ||
| however, should almost NEVER be based on pure empirical observation** - e.g. "I |
There was a problem hiding this comment.
hmm i think if were going to make a fairly strong statement like this, we should provide an example of what an alternative configuration would look like thats not a pure empirical observation.
content/en/docs/faq/_index.md
Outdated
| made 1000 calls to this operation, it took at most 5 seconds so I will set the | ||
| timeout based on that with a safety factor of 2x to 10 seconds". Environment | ||
| conditions can change and these types of assumptions can become wrong without | ||
| warning, leaving you open to the possibility of self-induced production pain. |
There was a problem hiding this comment.
lol self-induced production pain might be a bit strongly negative for a public consumer-facing doc
content/en/docs/faq/_index.md
Outdated
|
|
||
| We are unable to assist with extended or timed-out operation calls due to | ||
| extended HTTP round-trip times. An HTTP round-trip is defined as the time | ||
| between the first byte of the request being sent and the last byte of the |
There was a problem hiding this comment.
is it really the last byte? and not like time to first byte? i dont have any indication otherwise its just when i did a quick google search a couple of the top hits dont seem to specify exactly whether its time to first or last byte received.
https://www.cloudflare.com/learning/cdn/glossary/round-trip-time-rtt/
https://aws.amazon.com/what-is/rtt-in-networking/
do you happen to have a source on that? ideally something from the Go folks?
There was a problem hiding this comment.
For us it really depends on whether the response body is being forwarded, I'll try to clarify.
content/en/docs/faq/_index.md
Outdated
| attempting to read the response. | ||
|
|
||
| This can occur for several reasons: | ||
| * You did not consume the response body for time after the response itself was |
There was a problem hiding this comment.
for time after grammar/phrasing seems off here
| The SDK retries any errors matching the `connection reset` pattern by default. | ||
| However, this error can still occur in a context **outside** of the retry loop: | ||
| certain service operations directly forward the API's HTTP response body to the | ||
| caller to be consumed from the wire directly via `io.ReadCloser` (e.g. |
There was a problem hiding this comment.
nit: i think consumed from the wire directly may be more clarified if you contrasted it with the normal case
| If you change it, be sure to change the signature of the function it returns as | ||
| well. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
can you put go formatting here as well like the above formatted code
|
|
||
| func timeSpan(ctx context.Context, name string, consumer func(string)) func() { | ||
| start := time.Now() | ||
| return func() { |
There was a problem hiding this comment.
for my own curiosity, whats the advantage of using a higher-order function here? when it looks like all use cases in this code sample of where timeSpan is called, it immediately calls the returned function
There was a problem hiding this comment.
It's not immediately called because of defer, I've clarified how it's used in a doc comment.
There was a problem hiding this comment.
i meant the second set of parentheses (i.e. the second invocation). the second invocation is called immediately after the first invocation. i understand the first invocation is delayed by defer.
but the comment clears it up, thanks.
lucix-aws
force-pushed
the
doc-troubleshooting
branch
from
aa70a99 to
39e6ee4
Compare
No description provided.