在 Rust 用戶端程式庫中啟用遙測信號

Google Cloud 為 Rust 應用程式提供強大的監控、記錄與診斷功能。

Rust 用戶端程式庫會檢測追蹤記錄、指標和記錄資料。這項插碼功能為選擇性，您必須明確啟用。本文件說明可用的信號，以及如何啟用這些信號。

可用的信號

Rust 用戶端程式庫會產生下列信號：

  1. 每個邏輯用戶端要求都有 INFO 範圍。通常用戶端結構體中的單一方法呼叫會取得這類範圍 (例如，在 SecretManagerService 用戶端上呼叫 access_secret_version)。
  2. 直方圖指標，用於測量每個邏輯用戶端要求的經過時間。主要指標為 gcp.client.request.duration。
  3. 每個失敗的邏輯用戶端要求都會有 WARN 記錄。
  4. INFO 跨度，適用於每個低階 RPC 嘗試。通常，用戶端結構體中的單一方法會取得一個這類時距，但如果程式庫必須重試遠端程序呼叫 (RPC)，則可能會取得更多時距。
  5. DEBUG 記錄，瞭解每次失敗的低階嘗試。

這些時距和記錄會遵循 OpenTelemetry 語意慣例，並包含額外的Google Cloud 屬性。跨度和記錄都應適用於生產監控。

信號包括標準 OpenTelemetry 屬性 (例如 http.response.status_code 和 rpc.system.name) 和 Google Cloud專屬的自訂屬性，可能包括下列屬性和類似屬性：

  • gcp.client.service：服務名稱 (例如 pubsub 或 storage)。
  • gcp.client.repo：用戶端程式庫存放區 (例如 googleapis/google-cloud-rust)。
  • gcp.client.version：用戶端程式庫版本。
  • gcp.client.artifact：特定模組路徑 (例如 google-cloud-secretmanager)。
  • gcp.resource.destination.id：要執行動作的資源 ID。
  • gcp.errors.domain：可採取行動的錯誤記錄的錯誤網域。
  • gcp.errors.metadata.<key>：失敗要求的其他錯誤中繼資料鍵 (已扁平化)。

如需標準屬性的完整清單，請參閱 OpenTelemetry HTTP 和 gRPC 語意慣例。

程式庫也會為每個要求提供 DEBUG 範圍。包括完整要求主體、成功要求的回應主體，以及失敗要求的完整錯誤訊息和詳細資料。

在生產環境中啟用這些要求和回應之前，請先考量內容，因為要求或回應可能包含敏感資料。

這些 DEBUG 時距會使用用戶端程式庫 Crate，然後是 ::tracing 做為目標 (例如 google_cloud_secretmanager_v1::tracing)，並使用方法名稱做為時距名稱 (例如 access_secret_version)。您可以透過名稱、目標或兩者來設定篩選器。

啟用遙測功能

為保護機密資料，遙測信號預設為停用。

在 Rust 中，您必須設定用戶端來發出追蹤記錄、指標和記錄檔，並設定訂閱者和匯出工具，將這些信號傳送至外部服務。

如要設定用戶端，您可以設定下列環境變數：

export GOOGLE_CLOUD_RUST_LOGGING=true

或者，您也可以在使用用戶端建構工具的 .with_tracing() 方法建構用戶端時，透過程式明確啟用追蹤功能：

use google_cloud_secretmanager_v1::client::SecretManagerService;

let client = SecretManagerService::builder()
    .with_tracing()
    .build()
    .await?;

追蹤內容傳播

即使未使用 .with_tracing() 明確啟用追蹤記錄產生功能，Rust 用戶端程式庫也會自動將有效追蹤記錄內容傳播至Google Cloud 服務。

使用 tracing-opentelemetry 或 opentelemetry Crate 為用戶端程式庫提供追蹤內容。

匯出遙測資料

在用戶端程式庫中啟用遙測功能後，您必須設定應用程式，才能收集這項資料並匯出至可觀測性服務。Rust 用戶端程式庫原生使用 tracing 生態系統。

追蹤

如要將 Google Cloud 用戶端程式庫產生的 tracing 範圍匯出至 OpenTelemetry，您必須在應用程式中設定 Subscriber，將資料導向 OpenTelemetry 匯出工具 (例如 OTLP)。

使用 tracing-opentelemetry 和 opentelemetry-otlp Crate 設定匯出工具：

use google_cloud_secretmanager_v1::client::SecretManagerService;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample() -> anyhow::Result<()> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("example");

    // Create a tracing layer that sends data to an OpenTelemetry Collector running on localhost.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);

    // Register the subscriber globally
    let subscriber = Registry::default().with(telemetry);
    tracing::subscriber::set_global_default(subscriber)?;

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

指標

如要匯出指標，請先在應用程式中安裝全域 OpenTelemetry MeterProvider，然後再初始化用戶端。用戶端程式庫會自動使用這項設定，記錄及匯出指標資料。

如要進一步瞭解如何收集 OpenTelemetry 資料並匯出至 Cloud Monitoring 或 Cloud Trace，請參閱「選擇檢測方法」。

記錄

Rust 用戶端程式庫會使用 tracing Crate，在 WARN 和 DEBUG 層級發出可採取行動的錯誤記錄。匯出的記錄會包含追蹤記錄 ID 和時距 ID，只要使用適當的格式化工具，就能與追蹤記錄順暢地建立關聯。

如要將這些結構化記錄檔傳送至 Cloud Logging，請設定追蹤訂閱者，將事件格式設為 JSON，並輸出至標準輸出 (stdout)。如果您要部署至 Google Kubernetes Engine 或 Cloud Run 等環境，內建代理程式會自動擷取這些記錄檔。

以下範例會將訂閱者設定為只擷取及轉送 WARN 層級的記錄。

use google_cloud_secretmanager_v1::client::SecretManagerService;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

pub async fn sample() -> anyhow::Result<()> {
    // Enable all `WARN` logs to include failed client requests in all client libraries.
    let filter = tracing_subscriber::EnvFilter::new("warn");

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().json())
        .init();

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

如需在 JSON 格式器中設定 OpenTelemetry 追蹤記錄關聯資料 (例如 logging.googleapis.com/trace) 的詳細操作說明，請參閱以收集器為基礎的檢測範例總覽。