Endpoint docs & aws-config spans (#1087)

* Add more details to custom endpoint docs

* Cleanup aws-config spans

* Cleanup aws-config spans

* Cleanups & update changelog

CHANGELOG.next.toml

@@ -10,3 +10,15 @@
 # references = ["smithy-rs#920"]
 # meta = { "breaking" = false, "tada" = false, "bug" = false }
 # author = "rcoh"
+
+[[aws-sdk-rust]]
+message = "Convert several `info` spans to `debug` in aws-config"
+references = ["smithy-rs#1087"]
+meta = { "breaking" = false, "tada" = false, "bug" = false }
+author = "rcoh"
+
+[[smithy-rs]]
+message = "Improve docs on `Endpoint::{mutable, immutable}`"
+references = ["smithy-rs#1087"]
+meta = { "breaking" = false, "tada" = false, "bug" = false }
+author = "rcoh"

aws/rust-runtime/aws-config/src/default_provider.rs

@@ -420,9 +420,11 @@ pub mod timeout_config {
 /// Typically, this module is used via [`load_from_env`](crate::load_from_env) or [`from_env`](crate::from_env). It should only be used directly
 /// if you need to set custom configuration options like [`region`](credentials::Builder::region) or [`profile_name`](credentials::Builder::profile_name).
 pub mod credentials {
+    use aws_types::credentials;
     use std::borrow::Cow;
 
     use aws_types::credentials::{future, ProvideCredentials};
+    use tracing::Instrument;
 
     use crate::environment::credentials::EnvironmentVariableCredentialsProvider;
     use crate::meta::credentials::{CredentialsProviderChain, LazyCachingCredentialsProvider};
@@ -481,14 +483,21 @@ pub mod credentials {
         pub fn builder() -> Builder {
             Builder::default()
         }
+
+        async fn credentials(&self) -> credentials::Result {
+            self.0
+                .provide_credentials()
+                .instrument(tracing::info_span!("provide_credentials", provider = %"default_chain"))
+                .await
+        }
     }
 
     impl ProvideCredentials for DefaultCredentialsChain {
         fn provide_credentials<'a>(&'a self) -> future::ProvideCredentials<'a>
         where
             Self: 'a,
         {
-            self.0.provide_credentials()
+            future::ProvideCredentials::new(self.credentials())
         }
     }
 

aws/rust-runtime/aws-config/src/imds/region.rs

@@ -68,7 +68,7 @@ impl ProvideRegion for ImdsRegionProvider {
     fn region(&self) -> future::ProvideRegion {
         future::ProvideRegion::new(
             self.region()
-                .instrument(tracing::info_span!("imds_load_region")),
+                .instrument(tracing::debug_span!("imds_load_region")),
         )
     }
 }

aws/rust-runtime/aws-config/src/meta/credentials/chain.rs

@@ -76,7 +76,7 @@ impl CredentialsProviderChain {
 
     async fn credentials(&self) -> credentials::Result {
         for (name, provider) in &self.providers {
-            let span = tracing::info_span!("load_credentials", provider = %name);
+            let span = tracing::debug_span!("load_credentials", provider = %name);
             match provider.provide_credentials().instrument(span).await {
                 Ok(credentials) => {
                     tracing::info!(provider = %name, "loaded credentials");

aws/rust-runtime/aws-config/src/meta/credentials/lazy_caching.rs

@@ -77,6 +77,7 @@ impl ProvideCredentials for LazyCachingCredentialsProvider {
         future::ProvideCredentials::new(async move {
             // Attempt to get cached credentials, or clear the cache if they're expired
             if let Some(credentials) = cache.yield_or_clear_if_expired(now).await {
+                tracing::debug!("loaded credentials from cache");
                 Ok(credentials)
             } else {
                 // If we didn't get credentials from the cache, then we need to try and load.

aws/rust-runtime/aws-config/src/profile/credentials.rs

@@ -46,9 +46,9 @@ impl ProvideCredentials for ProfileFileCredentialsProvider {
     where
         Self: 'a,
     {
-        future::ProvideCredentials::new(self.load_credentials().instrument(tracing::info_span!(
+        future::ProvideCredentials::new(self.load_credentials().instrument(tracing::debug_span!(
             "load_credentials",
-            provider = "Profile"
+            provider = %"Profile"
         )))
     }
 }
@@ -185,7 +185,7 @@ impl ProfileFileCredentialsProvider {
         let mut creds = match inner_provider
             .base()
             .provide_credentials()
-            .instrument(tracing::info_span!("load_base_credentials"))
+            .instrument(tracing::debug_span!("load_base_credentials"))
             .await
         {
             Ok(creds) => {
@@ -200,7 +200,7 @@ impl ProfileFileCredentialsProvider {
         for provider in inner_provider.chain().iter() {
             let next_creds = provider
                 .credentials(creds, &self.client_config)
-                .instrument(tracing::info_span!("load_assume_role", provider = ?provider))
+                .instrument(tracing::debug_span!("load_assume_role", provider = ?provider))
                 .await;
             match next_creds {
                 Ok(next_creds) => {
@@ -403,7 +403,7 @@ impl Builder {
 
     /// Builds a [`ProfileFileCredentialsProvider`]
     pub fn build(self) -> ProfileFileCredentialsProvider {
-        let build_span = tracing::info_span!("build_profile_provider");
+        let build_span = tracing::debug_span!("build_profile_provider");
         let _enter = build_span.enter();
         let conf = self.provider_config.unwrap_or_default();
         let mut named_providers = self.custom_providers.clone();

aws/rust-runtime/aws-config/src/web_identity_token.rs

@@ -161,7 +161,7 @@ impl WebIdentityTokenCredentialsProvider {
             &conf.role_arn,
             &conf.session_name,
         )
-        .instrument(tracing::info_span!(
+        .instrument(tracing::debug_span!(
             "load_credentials",
             provider = "WebIdentityToken"
         ))

rust-runtime/aws-smithy-http/src/endpoint.rs

@@ -51,8 +51,9 @@ pub enum InvalidEndpoint {
 impl Endpoint {
     /// Create a new endpoint from a URI
     ///
-    /// Certain protocols will attempt to prefix additional information onto an endpoint. If you
-    /// wish to ignore these prefixes (for example, when communicating with localhost), set `immutable` to `true`.
+    /// Certain services will augment the endpoint with additional metadata. For example,
+    /// S3 can prefix the host with the bucket name. If your endpoint does not support this,
+    /// (for example, when communicating with localhost), use [`Endpoint::immutable`].
     pub fn mutable(uri: Uri) -> Self {
         Endpoint {
             uri,
@@ -67,6 +68,11 @@ impl Endpoint {
     /// use http::Uri;
     /// let endpoint = Endpoint::immutable(Uri::from_static("http://localhost:8000"));
     /// ```
+    ///
+    /// Certain services will augment the endpoint with additional metadata. For example,
+    /// S3 can prefix the host with the bucket name. This constructor creates an endpoint which will
+    /// ignore those mutations. If you want an endpoint which will obey mutation requests, use
+    /// [`Endpoint::mutable`] instead.
     pub fn immutable(uri: Uri) -> Self {
         Endpoint {
             uri,

tools/ci-cdk/canary-lambda/src/main.rs

@@ -13,7 +13,10 @@ use std::pin::Pin;
 use std::time::Duration;
 use tokio::task::JoinHandle;
 use tokio::time::timeout;
-use tracing::info;
+use tracing::{info, info_span, Instrument};
+use tracing_subscriber::layer::SubscriberExt;
+use tracing_subscriber::EnvFilter;
+use tracing_texray::TeXRayLayer;
 
 /// Conditionally include the module based on the $version feature gate
 ///
@@ -47,11 +50,22 @@ mod transcribe_canary;
 
 #[tokio::main]
 async fn main() -> Result<(), Error> {
-    tracing_subscriber::fmt::init();
+    let subscriber = tracing_subscriber::registry()
+        .with(EnvFilter::from_default_env())
+        .with(tracing_subscriber::fmt::layer())
+        .with(
+            TeXRayLayer::new()
+                // by default, all metadata fields will be printed. If this is too noisy,
+                // filter only the fields you care about
+                //.only_show_fields(&["name", "operation", "service"]),
+        );
+    tracing::subscriber::set_global_default(subscriber).unwrap();
     let local = env::args().any(|arg| arg == "--local");
     let main_handler = LambdaMain::new().await;
     if local {
-        let result = lambda_main(main_handler.clients).await?;
+        let result = lambda_main(main_handler.clients)
+            .instrument(tracing_texray::examine(info_span!("run_canaries")))
+            .await?;
         if result
             .as_object()
             .expect("is object")

tools/ci-cdk/canary-lambda/write-cargo-toml.py

@@ -7,6 +7,7 @@
 # Generates a Cargo.toml with the given AWS SDK version for this canary
 
 import argparse
+import sys
 
 BASE_MANIFEST = """
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
@@ -38,9 +39,10 @@
 thiserror = "1"
 tokio = { version = "1", features = ["full"] }
 tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["fmt"] }
+tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter"] }
 uuid = { version = "0.8", features = ["v4"] }
 tokio-stream = "0"
+tracing-texray = "0.1.1"
 """
 
 notable_versions = [