本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在適用於 Rust 的 AWS SDK 中設定可觀測性功能
可觀測性是從系統發出的資料推斷系統目前狀態的程度。發出的資料通常稱為遙測。
**Topics**
+ [日誌](logging.md)
# 在適用於 Rust 的 AWS SDK 中設定和使用記錄
適用於 Rust 的 AWS SDK 使用[追蹤](http://tracing.rs/)架構進行記錄。若要啟用記錄，請新增`tracing-subscriber`木箱，並在 Rust 應用程式中初始化木箱。日誌包括時間戳記、日誌層級和模組路徑，有助於偵錯 API 請求和 SDK 行為。使用 `RUST_LOG`環境變數來控制日誌詳細程度，並視需要依模組篩選。
## 如何在適用於 Rust 的 AWS SDK 中啟用記錄
1. 在專案目錄的命令提示中，新增[追蹤訂閱者](https://crates.io/crates/tracing-subscriber)目錄做為相依性：
```
$ cargo add tracing-subscriber --features tracing-subscriber/env-filter
```
這會將 木箱新增至 `Cargo.toml` 檔案的 `[dependencies]`區段。
1. 初始化訂閱者。通常先在 `main`函數中完成此操作，然後再呼叫任何適用於 Rust 的 SDK 操作：
```
use aws_config::BehaviorVersion;
type BoxError = Box;
#[tokio::main]
async fn main() -> Result<(), BoxError> {
tracing_subscriber::fmt::init(); // Initialize the subscriber.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
let _resp = s3.list_buckets()
.send()
.await?;
Ok(())
}
```
1. 使用`RUST_LOG`環境變數開啟記錄。若要啟用記錄資訊的顯示，請在命令提示字元中，將`RUST_LOG`環境變數設定為您要記錄的層級。下列範例會將記錄設定為 `debug`層級：
------
#### [ Linux/macOS ]
```
$ RUST_LOG=debug
```
------
#### [ Windows ]
如果您使用的是 VSCode，終端機視窗通常會預設為 PowerShell。驗證您正在使用的提示類型。
```
C:\> set RUST_LOG=debug
```
------
#### [ PowerShell ]
```
PS C:\> $ENV:RUST_LOG="debug"
```
------
1. 執行程式：
```
$ cargo run
```
您應該會在主控台或終端機視窗中看到其他輸出。
如需詳細資訊，請參閱 文件中的[使用環境變數篩選事件](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables)`tracing-subscriber`。
## 解譯日誌輸出
按照上一節中的步驟開啟記錄後，預設會將其他日誌資訊列印為標準輸出。
如果您使用的是預設日誌輸出格式 （由追蹤模組稱為「完整」)，您在日誌輸出中看到的資訊如下所示：
```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```
每個項目都包含下列項目：
+ 日誌項目的時間戳記。
+ 項目的日誌層級。這是一個字詞，例如 `INFO`、 `DEBUG`或 `TRACE`。
+ 產生日誌項目的巢狀[範圍](https://docs.rs/tracing/latest/tracing/span/index.html)集，以冒號 ("：") 分隔。這可協助您識別日誌項目的來源。
+ Rust 模組路徑，其中包含產生日誌項目的程式碼。
+ 記錄訊息文字。
追蹤模組的標準輸出格式使用 ANSI 逸出碼來將輸出著色。篩選或搜尋輸出時，請記住這些逸出序列。
**注意**
`sdk_invocation_id` 出現在巢狀範圍集合中的 是由 SDK 產生的唯一 ID 用戶端，以協助關聯日誌訊息。它與在來自 的回應中找到的請求 ID 無關 AWS 服務。
## 微調您的記錄層級
如果您使用支援環境篩選的木箱，例如 `tracing_subscriber`，您可以依模組控制日誌的詳細資訊。
您可以為每個模組開啟相同的記錄層級。下列會將`trace`每個模組的記錄層級設定為 ：
```
$ RUST_LOG=trace cargo run
```
您可以開啟特定模組的追蹤層級記錄。在下列範例中，只有來自 的日誌`aws_smithy_runtime`會傳入 `trace`層級。
```
$ RUST_LOG=aws_smithy_runtime=trace
```
您可以為多個模組指定不同的日誌層級，方法是使用逗號分隔它們。下列範例會將`aws_config`模組設定為`trace`關卡記錄，並將`aws_smithy_runtime`模組設定為`debug`關卡記錄。
```
$ RUST_LOG=aws_config=trace,aws_smithy_runtime=debug cargo run
```
下表說明您可以用來篩選日誌訊息的一些模組：
| 字首 | 描述 |
| --- | --- |
| `aws_smithy_runtime` | 請求和回應線路記錄 |
| `aws_config` | 登入資料載入 |
| `aws_sigv4` | 請求簽署和正式請求 |
了解您需要在日誌輸出中包含哪些模組的一種方法是先記錄所有項目，然後在日誌輸出中尋找所需資訊的木箱名稱。然後，您可以相應地設定環境變數，然後再次執行您的程式。