feat!: rename SdkLogMode to LogMode and enable its resolution from environment (#831)

Author: lauzadis

.changes/19e30aaf-5796-40b3-8a83-a5f04641981c.json

@@ -0,0 +1,8 @@
+{
+    "id": "19e30aaf-5796-40b3-8a83-a5f04641981c",
+    "type": "feature",
+    "description": "Enable resolving LogMode from environment",
+    "issues": [
+        "https://github.com/awslabs/aws-sdk-kotlin/issues/432"
+    ]
+}

.changes/86dde223-330a-49e2-b162-05fdb41c2848.json

@@ -0,0 +1,5 @@
+{
+    "id": "86dde223-330a-49e2-b162-05fdb41c2848",
+    "type": "feature",
+    "description": "BREAKING: rename SdkLogMode to LogMode"
+}

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/core/RuntimeTypes.kt

@@ -174,7 +174,7 @@ object RuntimeTypes {
     object SmithyClient : RuntimeTypePackage(KotlinDependency.SMITHY_CLIENT) {
         val SdkClient = symbol("SdkClient")
         val AbstractSdkClientBuilder = symbol("AbstractSdkClientBuilder")
-        val SdkLogMode = symbol("SdkLogMode")
+        val LogMode = symbol("LogMode")
         val SdkClientConfig = symbol("SdkClientConfig")
         val SdkClientFactory = symbol("SdkClientFactory")
         val SdkClientOption = symbol("SdkClientOption")

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/ServiceClientConfigGenerator.kt

@@ -42,7 +42,7 @@ class ServiceClientConfigGenerator(
      */
     private fun detectDefaultProps(context: CodegenContext, shape: ServiceShape): List<ConfigProperty> = buildList {
         add(RuntimeConfigProperty.ClientName)
-        add(RuntimeConfigProperty.SdkLogMode)
+        add(RuntimeConfigProperty.LogMode)
         if (context.protocolGenerator?.applicationProtocol?.isHttpProtocol == true) {
             add(RuntimeConfigProperty.HttpClientEngine)
             add(RuntimeConfigProperty.HttpInterceptors)

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/util/RuntimeConfigProperty.kt

@@ -118,13 +118,12 @@ object RuntimeConfigProperty {
         additionalImports = listOf(RuntimeTypes.Core.Retries.StandardRetryStrategy)
     }
 
-    val SdkLogMode = ConfigProperty {
+    val LogMode = ConfigProperty {
         symbol = buildSymbol {
-            name = RuntimeTypes.SmithyClient.SdkLogMode.name
-            namespace = RuntimeTypes.SmithyClient.SdkLogMode.namespace
-            defaultValue = "SdkLogMode.Default"
-            nullable = false
+            name = RuntimeTypes.SmithyClient.LogMode.name
+            namespace = RuntimeTypes.SmithyClient.LogMode.namespace
         }
+        propertyType = ConfigPropertyType.RequiredWithDefault("LogMode.Default")
 
         baseClass = RuntimeTypes.SmithyClient.SdkClientConfig
         builderBaseClass = buildSymbol {

codegen/smithy-kotlin-codegen/src/test/kotlin/software/amazon/smithy/kotlin/codegen/rendering/ServiceClientConfigGeneratorTest.kt

@@ -53,9 +53,9 @@ public class Config private constructor(builder: Builder) : HttpAuthConfig, Http
     public val endpointProvider: EndpointProvider = requireNotNull(builder.endpointProvider) { "endpointProvider is a required configuration property" }
     override val idempotencyTokenProvider: IdempotencyTokenProvider = builder.idempotencyTokenProvider ?: IdempotencyTokenProvider.Default
     override val interceptors: kotlin.collections.List<aws.smithy.kotlin.runtime.http.interceptors.HttpInterceptor> = builder.interceptors
+    override val logMode: LogMode = builder.logMode ?: LogMode.Default
     override val retryPolicy: RetryPolicy<Any?> = builder.retryPolicy ?: StandardRetryPolicy.Default
     override val retryStrategy: RetryStrategy = builder.retryStrategy ?: StandardRetryStrategy()
-    override val sdkLogMode: SdkLogMode = builder.sdkLogMode
     override val tracer: Tracer = builder.tracer ?: DefaultTracer(LoggingTraceProbe, clientName)
 """
         contents.shouldContainWithDiff(expectedProps)
@@ -106,17 +106,6 @@ public class Config private constructor(builder: Builder) : HttpAuthConfig, Http
          */
         override var interceptors: kotlin.collections.MutableList<aws.smithy.kotlin.runtime.http.interceptors.HttpInterceptor> = kotlin.collections.mutableListOf()
 
-        /**
-         * The policy to use for evaluating operation results and determining whether/how to retry.
-         */
-        override var retryPolicy: RetryPolicy<Any?>? = null
-
-        /**
-         * The [RetryStrategy] implementation to use for service calls. All API calls will be wrapped by the
-         * strategy.
-         */
-        override var retryStrategy: RetryStrategy? = null
-
         /**
          * Configure events that will be logged. By default clients will not output
          * raw requests or responses. Use this setting to opt-in to additional debug logging.
@@ -127,7 +116,18 @@ public class Config private constructor(builder: Builder) : HttpAuthConfig, Http
          * performance considerations when dumping the request/response body. This is primarily a tool for
          * debug purposes.
          */
-        override var sdkLogMode: SdkLogMode = SdkLogMode.Default
+        override var logMode: LogMode? = null
+
+        /**
+         * The policy to use for evaluating operation results and determining whether/how to retry.
+         */
+        override var retryPolicy: RetryPolicy<Any?>? = null
+
+        /**
+         * The [RetryStrategy] implementation to use for service calls. All API calls will be wrapped by the
+         * strategy.
+         */
+        override var retryStrategy: RetryStrategy? = null
 
         /**
          * The tracer that is responsible for creating trace spans and wiring them up to a tracing backend (e.g.,
@@ -148,7 +148,7 @@ public class Config private constructor(builder: Builder) : HttpAuthConfig, Http
             "import ${KotlinDependency.CORE.namespace}.client.IdempotencyTokenConfig",
             "import ${KotlinDependency.CORE.namespace}.client.IdempotencyTokenProvider",
             "import ${KotlinDependency.CORE.namespace}.client.SdkClientConfig",
-            "import ${KotlinDependency.CORE.namespace}.client.SdkLogMode",
+            "import ${KotlinDependency.CORE.namespace}.client.LogMode",
         )
         expectedImports.forEach {
             contents.shouldContainWithDiff(it)
@@ -237,10 +237,8 @@ public class Config private constructor(builder: Builder) {
         val testCtx = model.newTestContext()
         val writer = createWriter()
         val customIntegration = object : KotlinIntegration {
-            private val overriddenLogMode = RuntimeConfigProperty.SdkLogMode.toBuilder().apply {
-                symbol = symbol!!.toBuilder().apply {
-                    defaultValue("SdkLogMode.LogRequest") // replaces SdkLogMode.Default
-                }.build()
+            private val overriddenLogMode = RuntimeConfigProperty.LogMode.toBuilder().apply {
+                propertyType = ConfigPropertyType.RequiredWithDefault("LogMode.LogRequest") // replaces LogMode.Default
             }.build()
 
             override fun additionalServiceConfigProps(ctx: CodegenContext): List<ConfigProperty> = listOf(
@@ -255,85 +253,20 @@ public class Config private constructor(builder: Builder) {
         ServiceClientConfigGenerator(serviceShape, detectDefaultProps = true).render(renderingCtx, renderingCtx.writer)
         val contents = writer.toString()
 
-        val expectedBuilderProps = """
-        /**
-         * A reader-friendly name for the client.
-         */
-        override var clientName: String = "Test"
-
-        /**
-         * Override the default HTTP client engine used to make SDK requests (e.g. configure proxy behavior, timeouts, concurrency, etc).
-         * NOTE: The caller is responsible for managing the lifetime of the engine when set. The SDK
-         * client will not close it when the client is closed.
-         */
-        override var httpClientEngine: HttpClientEngine? = null
-
-        /**
-         * Register new or override default [HttpAuthScheme]s configured for this client. By default, the set
-         * of auth schemes configured comes from the service model. An auth scheme configured explicitly takes
-         * precedence over the defaults and can be used to customize identity resolution and signing for specific
-         * authentication schemes.
-         */
-        override var authSchemes: kotlin.collections.List<aws.smithy.kotlin.runtime.http.auth.HttpAuthScheme> = emptyList()
-
-        public var customProp: Int? = null
-
-        /**
-         * The endpoint provider used to determine where to make service requests. **This is an advanced config
-         * option.**
-         *
-         * Endpoint resolution occurs as part of the workflow for every request made via the service client.
-         *
-         * The inputs to endpoint resolution are defined on a per-service basis (see [EndpointParameters]).
-         */
-        public var endpointProvider: EndpointProvider? = null
-
-        /**
-         * Override the default idempotency token generator. SDK clients will generate tokens for members
-         * that represent idempotent tokens when not explicitly set by the caller using this generator.
-         */
-        override var idempotencyTokenProvider: IdempotencyTokenProvider? = null
-
-        /**
-         * Add an [aws.smithy.kotlin.runtime.client.Interceptor] that will have access to read and modify
-         * the request and response objects as they are processed by the SDK.
-         * Interceptors added using this method are executed in the order they are configured and are always
-         * later than any added automatically by the SDK.
-         */
-        override var interceptors: kotlin.collections.MutableList<aws.smithy.kotlin.runtime.http.interceptors.HttpInterceptor> = kotlin.collections.mutableListOf()
-
-        /**
-         * The policy to use for evaluating operation results and determining whether/how to retry.
-         */
-        override var retryPolicy: RetryPolicy<Any?>? = null
-
-        /**
-         * The [RetryStrategy] implementation to use for service calls. All API calls will be wrapped by the
-         * strategy.
-         */
-        override var retryStrategy: RetryStrategy? = null
-
-        /**
-         * Configure events that will be logged. By default clients will not output
-         * raw requests or responses. Use this setting to opt-in to additional debug logging.
-         *
-         * This can be used to configure logging of requests, responses, retries, etc of SDK clients.
-         *
-         * **NOTE**: Logging of raw requests or responses may leak sensitive information! It may also have
-         * performance considerations when dumping the request/response body. This is primarily a tool for
-         * debug purposes.
-         */
-        override var sdkLogMode: SdkLogMode = SdkLogMode.LogRequest
-
-        /**
-         * The tracer that is responsible for creating trace spans and wiring them up to a tracing backend (e.g.,
-         * a trace probe). By default, this will create a standard tracer that uses the service name for the root
-         * trace span and delegates to a logging trace probe (i.e.,
-         * `DefaultTracer(LoggingTraceProbe, "<service-name>")`).
-         */
-        override var tracer: Tracer? = null
-"""
-        contents.shouldContainWithDiff(expectedBuilderProps)
+        // Expect logMode config value to override default to LogMode.Request
+        val expectedConfigValues = """
+    override val clientName: String = builder.clientName
+    override val httpClientEngine: HttpClientEngine = builder.httpClientEngine ?: DefaultHttpEngine().manage()
+    override val authSchemes: kotlin.collections.List<aws.smithy.kotlin.runtime.http.auth.HttpAuthScheme> = builder.authSchemes
+    public val customProp: Int? = builder.customProp
+    public val endpointProvider: EndpointProvider = requireNotNull(builder.endpointProvider) { "endpointProvider is a required configuration property" }
+    override val idempotencyTokenProvider: IdempotencyTokenProvider = builder.idempotencyTokenProvider ?: IdempotencyTokenProvider.Default
+    override val interceptors: kotlin.collections.List<aws.smithy.kotlin.runtime.http.interceptors.HttpInterceptor> = builder.interceptors
+    override val logMode: LogMode = builder.logMode ?: LogMode.LogRequest
+    override val retryPolicy: RetryPolicy<Any?> = builder.retryPolicy ?: StandardRetryPolicy.Default
+    override val retryStrategy: RetryStrategy = builder.retryStrategy ?: StandardRetryStrategy()
+    override val tracer: Tracer = builder.tracer ?: DefaultTracer(LoggingTraceProbe, clientName)"""
+        contents.shouldContainWithDiff(expectedConfigValues)
     }
 
     @Test

docs/design/client-configuration.md

@@ -76,7 +76,7 @@ public interface BazClient : SdkClient { // 1
     }
 
     public class Config private constructor(builder: Builder) : SdkClientConfig, HttpClientConfig {  // 6
-        override val sdkLogMode: SdkLogMode = builder.sdkLogMode  // 7
+        override val logMode: LogMode = builder.logMode  // 7
         override val httpClientEngine: HttpClientEngine? = builder.httpClientEngine
         val bazSpecificConfig: String? = builder.bazSpecificConfig
 
@@ -93,7 +93,7 @@ public interface BazClient : SdkClient { // 1
             /**
              * Description
              */
-            override var sdkLogMode: SdkLogMode = SdkLogMode.Default
+            override var logMode: LogMode = LogMode.Default
 
             /**
              * Description
@@ -130,12 +130,12 @@ codegen.
 ```kotlin
 // explicit using DSL syntax inherited from companion `SdkClientFactory`
 val c1 = BazClient { // this: BazClient.Config.Builder
-    sdkLogMode = SdkLogMode.LogRequest
+    logMode = LogMode.LogRequest
 }
 
 // use of a builder explicitly, this could be passed around for example
 val c2 = BazClient.builder().apply { // this: BazClient.Builder
-    config.sdkLogMode = SdkLogMode.LogRequest
+    config.logMode = LogMode.LogRequest
 }.build()
 
 // "vended" using common code
@@ -162,7 +162,7 @@ private object ClientVendingMachine {
             }
             else -> {
                 // always available from generic bounds:
-                config.sdkLogMode
+                config.logMode
             }
         }
         return builder.build()
@@ -239,10 +239,10 @@ public interface SdkClient : Closeable {
  */
 public interface SdkClientConfig {
     /**
-     * Controls the events that will be logged by the SDK, see [Builder.sdkLogMode].
+     * Controls the events that will be logged by the SDK, see [Builder.logMode].
      */
-    public val sdkLogMode: SdkLogMode
-        get() = SdkLogMode.Default
+    public val logMode: LogMode
+        get() = LogMode.Default
 
     public interface Builder<TConfig : SdkClientConfig> : Buildable<TConfig> {
         /**
@@ -255,7 +255,7 @@ public interface SdkClientConfig {
          * performance considerations when dumping the request/response body. This is primarily a tool for
          * debug purposes.
          */
-        public var sdkLogMode: SdkLogMode
+        public var logMode: LogMode
     }
 }
 ```

docs/design/per-op-config.md

@@ -26,11 +26,11 @@ interface ServiceClient : SdkClient {
     }
 
     class Config private constructor(builder: Builder) {
-        val logMode: SdkLogMode = builder.logMode ?: SdkLogMode.Default
+        val logMode: LogMode = builder.logMode ?: LogMode.Default
         val httpEngine: HttpClientEngine = builder.httpEngine
 
         class Builder {
-            var logMode: SdkLogMode? = null
+            var logMode: LogMode? = null
             val httpEngine: HttpClientEngine? = null
             fun build(): Config = Config(this)
         }
@@ -66,14 +66,14 @@ suspend fun main() {
     client.operationA { /* ... */ }
 
     client.withConfig {
-        logMode = SdkLogMode.LogRequestWithBody
+        logMode = LogMode.LogRequestWithBody
     }.use { // for one-off or explicitly-scoped operation(s), a use {} block is most convenient
         it.operationA { /* ... */ }
     }
 
     launch {
         doBackgroundRoutine(client.withConfig {
-            logMode = SdkLogMode.LogResponse
+            logMode = LogMode.LogResponse
         })
 
         doBackgroundRoutine2(client.withConfig {
@@ -125,7 +125,7 @@ suspend fun main() {
     val requestA = OperationARequest { /* ... */ }
     client.operationA(requestA)
     client.operationA(requestA, client.config.copy {
-        logMode = SdkLogMode.LogRequestWithBody
+        logMode = LogMode.LogRequestWithBody
     })
 
     val requestB = OperationBRequest { /* ... */ }
@@ -134,7 +134,7 @@ suspend fun main() {
         // existing builder extension - build request here
     }
     client.operationB(requestB) {
-        logMode = SdkLogMode.LogResponseWithBody
+        logMode = LogMode.LogResponseWithBody
     }
 }
 ```
@@ -175,7 +175,7 @@ suspend fun main() {
         it.operationA {
             requestValue = 2
             withConfig {
-                logMode = SdkLogMode.LogRequestWithBody
+                logMode = LogMode.LogRequestWithBody
             }
         }
     }
@@ -214,7 +214,7 @@ suspend fun main() {
     client.operationA { /* ... */ }
 
     client.withConfig({
-        logMode = SdkLogMode.LogRequestWithBody + SdkLogMode.LogResponseWithBody
+        logMode = LogMode.LogRequestWithBody + LogMode.LogResponseWithBody
     }) {
         client.operationA { /* ... */ }
     }

runtime/protocol/http-client/common/src/aws/smithy/kotlin/runtime/http/operation/SdkOperationExecution.kt

@@ -6,8 +6,8 @@
 package aws.smithy.kotlin.runtime.http.operation
 
 import aws.smithy.kotlin.runtime.InternalApi
-import aws.smithy.kotlin.runtime.client.SdkLogMode
-import aws.smithy.kotlin.runtime.client.sdkLogMode
+import aws.smithy.kotlin.runtime.client.LogMode
+import aws.smithy.kotlin.runtime.client.logMode
 import aws.smithy.kotlin.runtime.http.HttpHandler
 import aws.smithy.kotlin.runtime.http.auth.SignHttpRequest
 import aws.smithy.kotlin.runtime.http.interceptors.InterceptorExecutor
@@ -346,18 +346,18 @@ private class HttpCallMiddleware : Middleware<SdkHttpRequest, HttpCall> {
  * default middleware that logs requests/responses
  */
 private suspend fun httpTraceMiddleware(request: SdkHttpRequest, next: Handler<SdkHttpRequest, HttpCall>): HttpCall {
-    val logMode = request.context.sdkLogMode
+    val logMode = request.context.logMode
     val logger = coroutineContext.getLogger("httpTraceMiddleware")
 
-    if (logMode.isEnabled(SdkLogMode.LogRequest) || logMode.isEnabled(SdkLogMode.LogRequestWithBody)) {
-        val formattedReq = dumpRequest(request.subject, logMode.isEnabled(SdkLogMode.LogRequestWithBody))
+    if (logMode.isEnabled(LogMode.LogRequest) || logMode.isEnabled(LogMode.LogRequestWithBody)) {
+        val formattedReq = dumpRequest(request.subject, logMode.isEnabled(LogMode.LogRequestWithBody))
         logger.debug { "HttpRequest:\n$formattedReq" }
     }
 
     var call = next.call(request)
 
-    if (logMode.isEnabled(SdkLogMode.LogResponse) || logMode.isEnabled(SdkLogMode.LogResponseWithBody)) {
-        val (resp, formattedResp) = dumpResponse(call.response, logMode.isEnabled(SdkLogMode.LogResponseWithBody))
+    if (logMode.isEnabled(LogMode.LogResponse) || logMode.isEnabled(LogMode.LogResponseWithBody)) {
+        val (resp, formattedResp) = dumpResponse(call.response, logMode.isEnabled(LogMode.LogResponseWithBody))
         call = call.copy(response = resp)
         logger.debug { "HttpResponse:\n$formattedResp" }
     } else {