本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 可观测性
<a name="observability"></a>

可观测性是指可以根据系统发出的数据推断出其当前状态的程度。发出的数据通常称为遥测。

 适用于 Kotlin 的 AWS SDK 可以提供所有三种常见的遥测信号：指标、跟踪和日志。您可以连接[https://docs.aws.amazon.com/smithy-kotlin/api/latest/telemetry-api/aws.smithy.kotlin.runtime.telemetry/-telemetry-provider/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/telemetry-api/aws.smithy.kotlin.runtime.telemetry/-telemetry-provider/index.html)以将遥测数据发送到可观测性后端（例如或 [AWS X-Ray](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools)A [ma](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov) zon CloudWatch），然后对其进行操作。

默认情况下，SDK 中仅启用日志功能，禁用其他遥测信号。本主题介绍如何启用和配置遥测输出。

**重要**  
`TelemetryProvider`目前是一个实验性 API，必须选择加入才能使用。

## 配置 `TelemetryProvider`
<a name="observability-conf-telemetry-provider"></a>

您可以在应用程序`TelemetryProvider`中为所有服务客户端或单个客户端全局配置。以下示例使用假设`getConfiguredProvider()`函数来演示 `TelemetryProvider` API 操作。本[遥测提供程序](observability-telemetry-providers.md)节介绍了 SDK 提供的实现信息。如果不支持提供商，则可以实现自己的支持或[在上打开功能请求 GitHub](https://github.com/awslabs/aws-sdk-kotlin/issues/new/choose)。

### 配置默认的全局遥测提供程序
<a name="observability-conf-telemetry-provider-global"></a>

默认情况下，每个服务客户端都尝试使用全局可用的遥测提供程序。这样，您只需设置一次提供程序，所有客户端都会使用它。在实例化任何服务客户端之前，只能执行一次。

要使用全局遥测提供程序，请先更新您的项目依赖项以添加遥测默认模块，如以下 Gradle 代码段所示。

（您可以导航到该{{X.Y.Z}}链接以查看可用的最新版本。）

```
dependencies {
    implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
    implementation("aws.smithy.kotlin:telemetry-defaults")
    ...
}
```

然后在创建服务客户端之前设置全局遥测提供商，如以下代码所示。

```
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")
}
```

### 为特定服务客户端配置遥测提供程序
<a name="observability-conf-telemetry-provider-client"></a>

您可以为单个服务客户端配置特定的遥测提供程序（而不是全局遥测提供程序）。如以下示例所示。

```
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")
}
```