本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 可觀測性
<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)或 [Amazon CloudWatch](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov))，然後對其採取行動。

根據預設，在 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")
}
```