Skip to content

Commit fe1b341

Browse files
author
Zelda Hessler
authored
add detailed error explanations page (#3734)
I was speaking to several customers that found our connection poisoning terminology confusing. To address this, I've changed the messaging and I've also created a new section in the docs that explains some errors in greater detail. To direct users to these explanations, I've added a link to the `tracing::info!` call. I propose that we consider doing the same any time we identify error messaging that - must be kept succinct to avoid logging too much info - must be more understandable to our users. ---- _By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._
1 parent dc1ffb8 commit fe1b341

File tree

3 files changed

+43
-4
lines changed

3 files changed

+43
-4
lines changed
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Detailed Error Explanations
2+
3+
This page collects detailed explanations for some errors. If you encounter an
4+
error and are interested in learning more about what it means and why it occurs,
5+
check here.
6+
7+
**If you can't find the explanation on this page, please file an issue asking
8+
for it to be added.**
9+
10+
## "Connection encountered an issue and should not be re-used. Marking it for closure"
11+
12+
The SDK clients each maintain their own connection pool (_except when they share
13+
an `HttpClient`_). By the convention of some services, when a request fails due
14+
to a [transient error](#transient-errors), that connection should not be re-used
15+
for a retry. Instead, it should be dropped and a new connection created instead.
16+
This prevents clients from repeatedly sending requests over a failed connection.
17+
18+
This feature is referred to as "connection poisoning" internally.
19+
20+
## Transient Errors
21+
22+
When requests to a service time out, or when a service responds with a 500, 502,
23+
503, or 504 error, it's considered a 'transient error'. Transient errors are
24+
often resolved by making another request.
25+
26+
When retrying transient errors, the SDKs may avoid re-using connections to
27+
overloaded or otherwise unavailable service endpoints, choosing instead to
28+
establish a new connection. This behavior is referred to internally as
29+
"connection poisoning" and is configurable.
30+
31+
To configure this behavior, set the [reconnect_mode][reconnect-mode] in an SDK
32+
client config's [RetryConfig].
33+
34+
[file an issue]: https://github.com/smithy-lang/smithy-rs/issues/new?assignees=&labels=&projects=&template=blank_issue.md
35+
[RetryConfig]: https://docs.rs/aws-types/latest/aws_types/sdk_config/struct.RetryConfig.html
36+
[reconnect-mode]: https://docs.rs/aws-types/latest/aws_types/sdk_config/struct.RetryConfig.html#method.with_reconnect_mode

rust-runtime/aws-smithy-runtime-api/src/client/connection.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ pub struct ConnectionMetadata {
2121
impl ConnectionMetadata {
2222
/// Poison this connection, ensuring that it won't be reused.
2323
pub fn poison(&self) {
24-
tracing::info!("smithy connection was poisoned");
24+
tracing::info!(
25+
see_for_more_info = "https://smithy-lang.github.io/smithy-rs/design/client/detailed_error_explanations.html",
26+
"Connection encountered an issue and should not be re-used. Marking it for closure"
27+
);
2528
(self.poison_fn)()
2629
}
2730

rust-runtime/aws-smithy-runtime/src/client/http/connection_poisoning.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,14 +81,14 @@ impl Intercept for ConnectionPoisoningInterceptor {
8181
reconnect_mode == ReconnectMode::ReconnectOnTransientError;
8282

8383
if error_is_transient && connection_poisoning_is_enabled {
84-
debug!("received a transient error, poisoning the connection...");
84+
debug!("received a transient error, marking the connection for closure...");
8585

8686
if let Some(captured_connection) = captured_connection.and_then(|conn| conn.get()) {
8787
captured_connection.poison();
88-
debug!("the connection was poisoned")
88+
debug!("the connection was marked for closure")
8989
} else {
9090
error!(
91-
"unable to poison the connection because no connection was found! The underlying HTTP connector never set a connection."
91+
"unable to mark the connection for closure because no connection was found! The underlying HTTP connector never set a connection."
9292
);
9393
}
9494
}

0 commit comments

Comments
 (0)