工作階段

本頁面說明 Spanner 工作階段的進階概念，包括建立用戶端程式庫、使用 REST 或 RPC API，或使用 Google 用戶端程式庫時，工作階段的最佳做法。

工作階段會提供 Spanner 資料庫服務的資料庫作業背景資訊。工作階段用於執行交易，以讀取、寫入或修改 Spanner 資料庫中的資料。每個工作階段都適用於單一資料庫。

工作階段一次可以執行單一或多個交易。執行多筆交易時，工作階段稱為「多工工作階段」。獨立讀取、寫入和查詢作業會在內部使用一項交易。

管理工作階段成效

工作階段是資料庫作業的背景資訊，因此管理方式會直接影響應用程式的延遲時間和資源用量。您可以透過下列三種方式管理工作階段效能：

• 使用工作階段集區。
• 使用多工工作階段。
• 最佳化 gRPC 管道設定。

使用工作階段集區

建立工作階段會增加延遲時間，因為每個新工作階段都需要往返 Spanner 資料庫服務。如要縮短延遲時間，請使用工作階段集區，也就是可供使用的可用工作階段集合。集區不會為每項作業建立工作階段，而是傳回現有工作階段，並在作業完成後回收，以便重複使用。這會將工作階段建立延遲時間分散到多項作業，而非完全消除。集區會儲存現有工作階段、在收到要求時傳回適當類型的工作階段，並清除未使用的工作階段。

工作階段應長期存在，因此在工作階段用於資料庫作業後，用戶端應將工作階段傳回集區，以便重複使用。

使用多工工作階段

多工工作階段可讓您在單一工作階段中提出多項並行要求，進而減少後端負擔和資源消耗。詳情請參閱「多工工作階段」。

最佳化 gRPC 管道設定

調整 gRPC 通道集區，減少高流量期間因 gRPC 通道壅塞而導致的高尾延遲時間 (p95/p99)。在支援的用戶端程式庫中，動態管道集區會隨著負載變化自動調整管道集區大小。這有助於減少與壅塞相關的尾端延遲，並避免通道佈建不足或過度佈建。

gRPC 管道總覽

Spanner 用戶端會使用 gRPC 通道進行通訊。一個 gRPC 通道大致相當於一個 TCP 連線。一個 gRPC 通道最多可處理 100 項並行要求。也就是說，應用程式需要的 gRPC 管道數量，至少必須等於應用程式執行的並行要求數量除以 100。

建立 Spanner 用戶端時，該用戶端會建立 gRPC 管道集區。

使用 Google 用戶端程式庫的最佳做法

以下說明使用 Spanner 的 Google 用戶端程式庫時的最佳做法。

設定集區中的工作階段和 gRPC 管道數量

管理工作階段和 gRPC 管道的方式取決於用戶端程式庫。支援多工工作階段的用戶端程式庫 (例如 Go 和 Java 用戶端程式庫) 不需要設定工作階段集區，並可透過動態管道集區管理 gRPC 管道集區。其他用戶端程式庫則使用工作階段集區，其中包含預設的工作階段數量下限和上限，以及預設的 gRPC 管道數量。預設值適用於大多數情況。以下各節說明每種程式設計語言的預設值和設定選項。

MinSessions: 100
MaxSessions: 400
NumChannels: 4

MinSessions: 100
MaxSessions: 400
NumChannels: 4

// Use 16 gRPC channels instead of the default of four.
client, err := spanner.NewClient(ctx,
    "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    option.WithGRPCConnectionPool(16),
)

client, err := spanner.NewClientWithConfig(ctx,
    "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    spanner.ClientConfig{
        DynamicChannelPoolConfig: spanner.DynamicChannelPoolConfig{
            DCPEnabled: true,
        },
    })

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setProjectId("PROJECT_ID")
        .enableDynamicChannelPool()
        .build();

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setProjectId("PROJECT_ID")
        .enableDynamicChannelPool()
        .setGcpChannelPoolOptions(
            GcpChannelPoolOptions.newBuilder()
                .setMaxSize(15)
                .setMinSize(3)
                .setInitSize(5)
                // setDynamicScaling(minRpcPerChannel, maxRpcPerChannel,
                // scaleDownInterval): scale up as soon as a channel's load
                // exceeds 30 concurrent RPCs. Scale-up is event-driven, so
                // the pool grows immediately as load rises. Scale-down is
                // periodic: a channel is removed only after it stays under
                // 10 concurrent RPCs across the check that runs every 5
                // minutes.
                .setDynamicScaling(10, 30, Duration.ofMinutes(5))
                .build())
        .build();

MinSessions: 25
MaxSessions: 100

MaxChannels: 10
ConcurrentRequestsPerChannel: 25

const {Spanner} = require('@google-cloud/spanner');
    // Note: Ensure grpcGcp is initialized
const customGcpApiConfig = {
  channelPool: {
    maxSize: 20, // Overriding default 10
    maxConcurrentStreamsLowWatermark: 50 // Overriding default 25
  }
};
const spanner = new Spanner({
  'grpc.gcpApiConfig': grpcGcp.createGcpApiConfig(customGcpApiConfig)
});

MinSessions: 1
MaxSessions: 500

MinSessions: 10
MaxSessions: 100

如果程式設計語言的用戶端程式庫支援多工工作階段，請使用這類工作階段。多工工作階段不需要任何設定，單一多工工作階段可以執行任意數量的並行交易。

應用程式使用的工作階段數量，等於應用程式執行的並行交易數量。只有在預期單一應用程式執行個體執行的並行交易數量，超過預設工作階段集區可處理的數量時，才應修改預設工作階段集區設定。

對於高度並行的應用程式，建議採取下列做法：

1. 將 MinSessions 設為單一用戶端預期執行的並行交易數量。
2. 將 MaxSessions 設為單一用戶端可執行的並行交易數量上限。
3. 如果預期的並行數量在應用程式生命週期內不會有太大變化，請設定 MinSessions=MaxSessions。這可防止工作階段集區擴充或縮減。擴充或縮減工作階段集區也會耗用部分資源。
4. 將 NumChannels 設為 MaxSessions / 100。一個 gRPC 管道最多可同時處理 100 項要求。如果發現尾端延遲時間 (p95/p99 延遲時間) 偏高，請提高這個值，因為這可能代表 gRPC 管道壅塞。

增加有效工作階段數量會使用 Spanner 資料庫服務和用戶端程式庫中的額外資源。如果工作階段數量超過應用程式實際需求，系統效能可能會降低。

增加工作階段集區，而非增加用戶端數量

應用程式的工作階段集區大小，決定了單一應用程式執行個體可執行的並行交易數量。不建議將工作階段集區大小增加到超過單一應用程式執行個體可處理的並行上限。如果應用程式收到的要求數量突然增加，超過集區中的工作階段數量，要求就會排入佇列，等待工作階段可用。

用戶端程式庫使用的資源如下：

1. 每個 gRPC 通道都會使用一個 TCP 連線。
2. 每個 gRPC 叫用都需要一個執行緒。用戶端程式庫使用的執行緒數量上限，等於應用程式執行的並行查詢數量上限。這些執行緒會優先於應用程式用於自身商業邏輯的任何執行緒。

不建議將工作階段集區的大小，增加到超過單一應用程式執行個體可處理的執行緒數量上限。請改為增加應用程式執行個體數量。

管理寫入工作階段片段

對於某些用戶端程式庫，Spanner 會保留一部分工作階段用於讀寫交易，稱為寫入工作階段比例。如果應用程式用盡所有讀取工作階段，Spanner 就會使用讀寫工作階段，即使是唯讀交易也一樣。讀寫工作階段需要 spanner.databases.beginOrRollbackReadWriteTransaction。如果使用者具備 spanner.databaseReader IAM 角色，呼叫就會失敗，Spanner 則會傳回以下錯誤訊息：

generic::permission_denied: Resource %resource% is missing IAM permission:
spanner.databases.beginOrRollbackReadWriteTransaction

針對保有讀取/寫入工作階段片段的用戶端程式庫，即可以設定寫入工作階段的片段。

建立用戶端程式庫或使用 REST/RPC 的最佳做法

以下說明在 Spanner 用戶端程式庫中實作工作階段，或搭配 REST 或 RPC API 使用工作階段的最佳做法。

這些最佳做法僅適用於開發用戶端程式庫，或使用 REST/RPC API 的情況。如果您使用 Spanner 的 Google 用戶端程式庫，請參閱「使用 Google 用戶端程式庫的最佳做法」。

建立工作階段集區並設定大小

如要判斷用戶端程序的工作階段集區最佳大小，請將下限設為預期的並行交易數量，並將上限設為初始測試數量，例如 100。如果最大的數量不合適，請再增加。增加活躍工作階段數量會使用 Spanner 資料庫服務的額外資源，因此如果未清除未使用的工作階段，可能會降低效能。如果使用者使用 RPC API，建議每個 gRPC 管道的工作階段不超過 100 個。

處理已刪除的工作階段

刪除課程的方式有三種：

• 用戶端可刪除工作階段。
• 如果工作階段閒置超過 1 小時，Spanner 資料庫服務可能會刪除該工作階段。
• 如果工作階段超過 28 天，Spanner 資料庫服務可能會刪除該工作階段。

如果嘗試使用已刪除的工作階段，會導致 NOT_FOUND。如果遇到這項錯誤，請建立並使用新的工作階段、將新工作階段新增至集區，然後從集區中移除已刪除的工作階段。

保持閒置工作階段的運作

Spanner 資料庫服務保留權利捨棄未使用的工作階段。如果您確定需要保持閒置工作階段的運作，例如預期資料庫的近期使用量會大增，即可避免捨棄閒置工作階段。執行低成本作業 (例如執行 SQL 查詢 SELECT 1)，讓工作階段保持運作。如果閒置工作階段近期內不會用到，請讓 Spanner 捨棄該工作階段，並在下次需要時建立新的工作階段。

保持工作階段運作的其中一個情境，是處理資料庫的常態尖峰需求。如果每天從上午 9:00 到下午 6:00 都是資料庫重度使用的狀態，您必須在這個期間保持一些閒置工作階段的運作，因為在用量高峰時可能會需要這些工作階段。下午 6 點後，您可以讓 Spanner 捨棄閒置工作階段。在每天上午 9:00 前，建立一些新的工作階段，為預期的需求做好準備。

另一種情況是，您有一個使用 Spanner 的應用程式，但必須避免連線負擔。您也可以保持一組工作階段的運作，避免連線負擔。

針對用戶端程式庫的使用者隱藏工作階段詳細資料

如果您要建立用戶端程式庫，請勿向用戶端程式庫使用者公開工作階段。讓用戶端可以進行資料庫呼叫，而無需涉及建立與維護工作階段的複雜事務。如需隱藏用戶端程式庫消費者工作階段詳細資料的用戶端程式庫範例，請參閱 Java 適用的 Spanner 用戶端程式庫。

處理非冪等的寫入交易錯誤

如果寫入交易沒有重放攻擊防護機制，可能會多次套用異動。如果異動不具冪等性，多次套用異動可能會導致失敗。舉例來說，即使在嘗試寫入前資料列不存在，插入作業仍可能失敗，並顯示 ALREADY_EXISTS。這會發生在後端伺服器修訂異動，但無法成功與用戶端進行通訊的情況。在這種情況下，系統可能會重試異動，導致 ALREADY_EXISTS 失敗。

在實作用戶端程式庫或使用 REST API 時，您可以透過下列方式解決這個問題：

• 建立寫入作業的結構使其成為冪等。
• 使用具備防重播的寫入作業。
• 實作執行「upsert」邏輯的方法：如果是新資料，則插入；如果已存在，則更新。
• 替用戶端處理錯誤。

維持穩定的連線

如要獲得最佳效能，用來託管工作階段的連線必須保持穩定。如果託管工作階段的連線有所變更，Spanner 可能會取消工作階段中的有效交易，並在更新工作階段中繼資料時，對資料庫造成少量額外負載。偶而發生的少數連線變更是沒有問題的，但仍須避免同時變更大量連線的狀況。如果您在用戶端和 Spanner 之間使用 Proxy，請務必維持每個工作階段的連線穩定性。

監控進行中的工作階段

您可以使用 ListSessions 指令，透過指令列、REST API 或 RPC API 監控資料庫中的有效工作階段。ListSessions 會顯示特定資料庫的使用中工作階段。如果您需要找出工作階段洩漏的原因，這項功能就非常實用。(工作階段洩漏是指系統建立工作階段，但未將工作階段傳回工作階段集區供重複使用的事件)。

ListSessions 可讓您查看有效活動時段的中繼資料，包括活動時段的建立時間和上次使用時間。分析這項資料，有助於您在排解工作階段問題時找到正確方向。如果大多數使用中的工作階段最近都沒有 approximate_last_use_time，可能表示應用程式未正確重複使用工作階段。如要進一步瞭解 approximate_last_use_time 欄位，請參閱 RPC API 參考資料。

如要進一步瞭解如何使用 ListSessions，請參閱 REST API 參考資料、RPC API 參考資料或 gcloud 指令列工具參考資料。

自動清理工作階段洩漏

如果工作階段集區中的所有工作階段都已用完，每筆新交易都會等待工作階段傳回集區。如果建立工作階段後，未將工作階段傳回工作階段集區重複使用，就稱為工作階段外洩。發生工作階段洩漏時，等待開啟工作階段的交易會無限期卡住，並封鎖應用程式。工作階段外洩通常是由有問題的交易造成，這些交易執行時間極長且未提交。

您可以設定工作階段集區，自動解決這些閒置交易。啟用用戶端程式庫自動解決閒置轉換問題的功能後，系統會找出可能導致工作階段外洩的問題交易，將其從工作階段集區中移除，並以新的工作階段取代。

記錄功能也有助於找出這些有問題的交易。如果啟用記錄功能，當工作階段集區使用率超過 95% 時，系統預設會分享警告記錄。如果工作階段用量超過 95%，則必須提高工作階段集區允許的工作階段數量上限，否則可能會發生工作階段外洩。警告記錄包含執行時間超過預期的交易堆疊追蹤，可協助找出工作階段集區使用率偏高的原因。系統會根據記錄匯出工具設定推送警告記錄。

啟用用戶端程式庫，自動解決閒置交易

您可以啟用用戶端程式庫，傳送警告記錄並自動解決閒置交易，也可以啟用用戶端程式庫，僅接收警告記錄。

 final SessionPoolOptions sessionPoolOptions = SessionPoolOptions.newBuilder().setWarnAndCloseIfInactiveTransactions().build()

 final Spanner spanner =
         SpannerOptions.newBuilder()
             .setSessionPoolOption(sessionPoolOptions)
             .build()
             .getService();
 final DatabaseClient client = spanner.getDatabaseClient(databaseId);

 final SessionPoolOptions sessionPoolOptions = SessionPoolOptions.newBuilder().setWarnIfInactiveTransactions().build()

 final Spanner spanner =
         SpannerOptions.newBuilder()
             .setSessionPoolOption(sessionPoolOptions)
             .build()
             .getService();
 final DatabaseClient client = spanner.getDatabaseClient(databaseId);

 client, err := spanner.NewClientWithConfig(
     ctx, database, spanner.ClientConfig{SessionPoolConfig: spanner.SessionPoolConfig{
         InactiveTransactionRemovalOptions: spanner.InactiveTransactionRemovalOptions{
         ActionOnInactiveTransaction: spanner.WarnAndClose,
         }
     }},
 )
 if err != nil {
     return err
 }
 defer client.Close()

 customLogger := log.New(os.Stdout, "spanner-client: ", log.Lshortfile)
 // Create a logger instance using the golang log package
 cfg := spanner.ClientConfig{
         Logger: customLogger,
     }
 client, err := spanner.NewClientWithConfig(ctx, db, cfg)

多工工作階段

多工工作階段可讓您在單一工作階段中建立大量並行要求。多工工作階段是您在多個 gRPC 管道中使用的 ID。不會造成任何額外的瓶頸。多工工作階段具有下列優點：

• 工作階段管理通訊協定更簡單，因此後端資源消耗量減少。例如，他們會避免與工作階段擁有權維護和垃圾收集相關的工作階段維護活動。
• 長期工作階段，閒置時不需要 keep-alive 要求。

多工工作階段支援下列項目：

• C++、Go、Java、Node.js、PHP、Python、Ruby 和 Rust 用戶端程式庫。

• 依賴上述用戶端程式庫的 Spanner 生態系統工具，例如 PGAdapter、JDBC、Hibernate、資料庫/SQL 驅動程式、dbAPI 驅動程式和 GORM。

• 依賴 Java 和 Go 用戶端程式庫的 Spanner 生態系統工具，例如 PGAdapter、JDBC、Hibernate、資料庫或 SQL 驅動程式，以及 GORM。您可以使用 OpenTelemetry 指標，查看現有工作階段集區和多工工作階段之間的流量分配情形。OpenTelemetry 有一個指標篩選器 is_multiplexed，設為 true 時會顯示多工工作階段。

所有類型的交易都支援多工工作階段。

用戶端程式庫每 7 天會輪替多工工作階段，避免在過時的工作階段傳送交易。

部分用戶端程式庫預設會啟用多工工作階段。其他功能則必須使用環境變數啟用。詳情請參閱「啟用多工工作階段」。

注意事項

如果您嘗試提交空白的讀取或寫入交易主體，或每個查詢或 DML 陳述式都失敗的交易，則多工工作階段有幾種情況需要考量。多工工作階段要求您在每個修訂要求中，加入伺服器產生的預先修訂權杖。對於包含查詢或 DML 的交易，伺服器必須至少有一次成功的查詢或 DML 交易，才能將有效的權杖傳回用戶端程式庫。如果沒有任何成功的查詢或 DML 交易，用戶端程式庫會在修訂前隱含新增 SELECT 1。

如果多工工作階段只有異動，且其中一項異動涉及結構定義中「不存在」的資料表或資料欄，則在該工作階段執行讀取或寫入交易時，用戶端可能會傳回 INVALID_ARGUMENT 錯誤，而非 NOT_FOUND 錯誤。

啟用多工工作階段

下列用戶端程式庫預設會啟用多工工作階段：

• C++ 2.41.0 以上版本。
• Go 1.85.0 以上版本。
• 6.98.0 以上版本的 Java。
• Node.js 8.3.0 以上版本。
• PHP 2.0.0 以上版本。
• Python 3.57.0 以上版本。
• Ruby 2.30.0 以上版本。

如要在舊版 Node.js、Java 和 Go 用戶端程式庫中使用多工工作階段，必須先設定環境變數來啟用。

如要啟用多工工作階段，請將 GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS 環境變數設為 TRUE。這個旗標也會啟用 ReadOnly 交易的多工工作階段支援。

export GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS=TRUE

如要為多工工作階段啟用分區作業支援，請將 GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS_PARTITIONED_OPS 環境變數設為 TRUE。

export GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS_PARTITIONED_OPS=TRUE

如要為多工工作階段啟用讀寫交易支援，請將 GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS_FOR_RW 環境變數設為 TRUE。

export GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS_FOR_RW=True

您必須將 GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS 設為 TRUE，才能在多工工作階段中支援交易。

查看一般和多工工作階段的流量

OpenTelemetry 包含 is_multiplexed 篩選器，可顯示多工工作階段的流量。將這個篩選器設為 true，即可查看多工工作階段；設為 false，則可查看一般工作階段。

1. 按照 Spanner OpenTelemetry 的「事前準備」一節中的程序，設定 Spanner 的 OpenTelemetry。

2. 前往「Metrics Explorer」。

   前往 Metrics Explorer

3. 在「Metric」(指標) 下拉式選單中，篩選 generic。

4. 按一下「Generic Task」(一般工作)，然後依序前往「Spanner」>「Spanner/num_acquired_sessions」。

5. 在「篩選器」欄位中，選取下列其中一個選項：

   a. is_multiplexed = false：查看一般工作階段。 b. is_multiplexed = true：查看多工工作階段。

   下圖顯示已選取多工工作階段的「Filter」(篩選器) 選項。

如要進一步瞭解如何搭配使用 OpenTelemetry 和 Spanner，請參閱「運用 OpenTelemetry 普及 Spanner 觀測能力」和「使用 OpenTelemetry 檢查 Spanner 元件的延遲時間」。

疑難排解

應用程式可能遇到的常見工作階段相關錯誤包括：

• Session not found
• RESOURCE_EXHAUSTED

詳情請參閱「工作階段錯誤」。