Observability

Observability is the extent to which a system's current state can be inferred from the data it emits. The data emitted is commonly referred to as telemetry.

The AWS SDK for Kotlin can provide all three common telemetry signals: metrics, traces, and logs. You can wire up a TelemetryProvider to send telemetry data to an observability backend (such as AWS X-Ray or Amazon CloudWatch) and then act on it.

By default, only logging is enabled and other telemetry signals are disabled in the SDK. This topic explains how to enable and configure telemetry output.

Important

TelemetryProvider is currently an experimental API that must be opted in to use.

Configure a TelemetryProvider

You can configure a TelemetryProvider in your application globally for all service clients or for individual clients. The following examples use a hypothetical getConfiguredProvider() function to demonstrate the TelemetryProvider API operations. The Telemetry providers section describes information for implementations provided by the SDK. If a provider isn’t supported, you can implement your own support or open a feature request on GitHub.

Configure the default global telemetry provider

By default, every service client attempts to use the globally available telemetry provider. This way, you can set the provider once, and all clients will use it. This should be done only once, before you instantiate any service clients.

To use the global telemetry provider, first update your project dependencies to add the telemetry defaults module as shown in the following Gradle snippet.

val smithyKotlinVersion = "1.2.2"

dependencies {
    implementation("aws.smithy.kotlin:telemetry-defaults:$smithyKotlinVersion")
    ...
}

Then set the global telemetry provider before creating a service client as shown in the following code.

import aws.sdk.kotlin.services.s3.S3Client
import aws.smithy.kotlin.runtime.telemetry.GlobalTelemetryProvider
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val myTelemetryProvider = getConfiguredProvider()
    GlobalTelemetryProvider.set(myTelemetryProvider)

    S3Client.fromEnvironment().use { s3 ->
        …
    }     
}

fun getConfiguredProvider(): TelemetryProvider {
    TODO("TODO - configure a provider")
}

Configure a telemetry provider for a specific service client

You can configure an individual service client with a specific telemetry provider (other than the global one). This is shown in the following example.

import aws.sdk.kotlin.services.s3.S3Client
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    S3Client.fromEnvironment{
        telemetryProvider = getConfiguredProvider()
    }.use { s3 ->
        ...
    }
}

fun getConfiguredProvider(): TelemetryProvider {
    TODO("TODO - configure a provider")
}