BREAKING: Tracing Configuration

[aajtodd]

An upcoming release of the AWS SDK for Kotlin changes the configuration API for tracing. This change
unifies and expands the observability configuration for the SDK.

NOTE: If you do not set a custom Tracer when configuring a service client OR rely on the log message format emitted by
the SDK then this change does not affect you.

Release date

This feature will ship with the v0.29.0-beta release planned for 07/20/2023.

What's changing

1. The Tracer type (as well as the associated TraceProbe type) has been removed and replaced with a unified
   TelemetryProvider type covering traces, metrics, and logs.

2. You will also notice a change to the format of the log records emitted by the SDK.

• Span names are no longer part of the log record
• The operation being invoked and the invocation ID (previously sdkRequestId) are now MDC entries.

Assuming log4j with the following pattern:

<PatternLayout pattern="%d{DEFAULT_MICROS} %-5p %c %X - %encode{%m}{CRLF}%n"/>

Previous log output:

2023-07-17 13:08:59,677328 TRACE aws.smithy.kotlin.runtime.http.operation.SerializeHandler {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74: request serialized in 4.849458ms
2023-07-17 13:08:59,686439 TRACE aws.smithy.kotlin.runtime.auth.awscredentials.CachedCredentialsProvider {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1: refreshing credentials cache
2023-07-17 13:08:59,688228 TRACE aws.smithy.kotlin.runtime.identity.IdentityProviderChain {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: Attempting to resolve identity from aws.sdk.kotlin.runtime.auth.credentials.EnvironmentCredentialsProvider@46baf579
2023-07-17 13:08:59,688971 TRACE aws.sdk.kotlin.runtime.auth.credentials.EnvironmentCredentialsProvider {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: Attempting to load credentials from env vars AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
2023-07-17 13:08:59,690600 DEBUG aws.smithy.kotlin.runtime.identity.IdentityProviderChain {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: unable to resolve identity from aws.sdk.kotlin.runtime.auth.credentials.EnvironmentCredentialsProvider@46baf579: Missing value for environment variable `AWS_ACCESS_KEY_ID`
2023-07-17 13:08:59,691831 TRACE aws.smithy.kotlin.runtime.identity.IdentityProviderChain {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: Attempting to resolve identity from aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider@4bd2f0dc
2023-07-17 13:08:59,698010 DEBUG aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: Loading credentials from profile `dev-admin-west`
2023-07-17 13:08:59,701652 DEBUG aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: Resolving credentials from process
2023-07-17 13:09:00,356793 DEBUG aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider {} - S3-ListBuckets-f3e79819-ef88-449a-af82-fb7595fd9f74/Attempt-1/ResolveIdentityChain: Obtained credentials from profile; expiration=2023-07-18T00:07:57Z

New log output:

2023-06-21 12:13:20,047048 TRACE aws.smithy.kotlin.runtime.http.operation.SerializeHandler {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - request serialized in 4.851666ms
2023-06-21 12:13:20,058737 TRACE aws.smithy.kotlin.runtime.auth.awscredentials.CachedCredentialsProvider {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - refreshing credentials cache
2023-06-21 12:13:20,060550 TRACE aws.smithy.kotlin.runtime.identity.IdentityProviderChain {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - Attempting to resolve identity from aws.sdk.kotlin.runtime.auth.credentials.EnvironmentCredentialsProvider@7fae4d4a
2023-06-21 12:13:20,061289 TRACE aws.sdk.kotlin.runtime.auth.credentials.EnvironmentCredentialsProvider {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - Attempting to load credentials from env vars AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
2023-06-21 12:13:20,062793 DEBUG aws.smithy.kotlin.runtime.identity.IdentityProviderChain {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - unable to resolve identity from aws.sdk.kotlin.runtime.auth.credentials.EnvironmentCredentialsProvider@7fae4d4a: Missing value for environment variable `AWS_ACCESS_KEY_ID`
2023-06-21 12:13:20,064008 TRACE aws.smithy.kotlin.runtime.identity.IdentityProviderChain {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - Attempting to resolve identity from aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider@4dd94a58
2023-06-21 12:13:20,070404 DEBUG aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - Loading credentials from profile `dev-admin-west`
2023-06-21 12:13:20,074683 DEBUG aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - Resolving credentials from process
2023-06-21 12:13:20,500891 DEBUG aws.sdk.kotlin.runtime.auth.credentials.ProfileCredentialsProvider {rpc=S3.ListBuckets, sdkInvocationId=089896c5-efef-4545-baa2-b08680e9b62c} - Obtained credentials from profile; expiration=2023-06-21T22:53:42Z

How to migrate

Previously, telemetry signals (traces, metrics, logs) were all routed through a single API, Tracer. The default Tracer implementation allowed registering a TraceProbe which acted as a sink for all telemetry signals.

How to migrate to the new TelemetryProvider API is going to be use case specific depending on the telemetry signals of interest and how they are being processed.

NOTE: The SDK provides an experimental implementation of TelemetryProvider backed by OpenTelemetry that can be used to export telemetry data using OpenTelemetry.

Additional resources

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you encounter a bug with these changes, please file an issue.

The AWS SDK for Kotlin Developer Guide will be expanded to cover telemetry configuration, metrics emitted, etc. Check back soon for updates.