工作階段

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

工作階段會為 Spanner 資料庫服務的資料庫作業提供環境。它可以用來執行讀取、寫入或修改 Spanner 資料庫中資料的交易。每個工作階段都適用於單一資料庫。

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

管理工作階段成效

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

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

使用工作階段集區

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

工作階段是為長期使用做準備，因此當用於資料庫作業之後，用戶端應將該工作階段傳回集區以重複使用。

使用多工工作階段

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

最佳化 gRPC 管道設定

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

gRPC 管道總覽

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

建立 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

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，才適用這些最佳做法。如果您使用 Google Spanner 用戶端程式庫，請參閱使用 Google 用戶端程式庫的最佳做法。

建立工作階段集區並調整大小

如要判斷用戶端程序中工作階段集區的最佳大小，請將預期並行的交易數量設定為最小值，然後將最大值設定為最初的測試數量，例如 100 如果最大的數量不合適，請再增加。增加作用中的工作階段數量會使用 Spanner 資料庫服務額外的資源，所以如果無法清理未使用的工作階段，效能會下降。針對 RPC API 的使用者，建議每個 gRPC 管道不要超過 100 個工作階段。

處理已刪除的工作階段

你可以透過下列三種方式刪除工作階段：

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

嘗試使用已刪除的工作階段會導致 NOT_FOUND。如果您遇到這個問題，請建立並使用新的工作階段，接著新增工作階段至集區，再將已刪除的工作階段從集區中移除。

保持閒置工作階段的運作

Spanner 資料庫服務會保留捨棄未使用工作階段的權利。如果您確定需要保持閒置工作階段的運作，例如預期資料庫的近期使用量會大增，即可避免捨棄閒置工作階段。請執行價格低廉的作業來讓工作階段保持運作，例如執行 SQL 查詢 SELECT 1。如果您有近期內不需使用的閒置工作階段，請允許 Spanner 捨棄該工作階段，然後下次需要時再建立一個新工作階段。

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

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

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

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

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

無防重播功能的寫入交易可能會套用一次以上的異動。如果異動非冪等，套用一次以上的異動可能會導致執行失敗。舉例來說，即使嘗試寫入前並沒有任何資料列，插入作業仍可能因 ALREADY_EXISTS 而失敗。這會發生在後端伺服器提交修改作業，但無法成功與用戶端進行通訊的情況。在這種事件中，系統會重新嘗試異動而導致 ALREADY_EXISTS 失敗。

當實作自有的用戶端資料庫或使用 REST API 時，請參考下列因應此情境的一些可能方法：

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

維持穩定的連線

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

監控執行中的工作階段

利用 REST API 或 RPC API，即可從指令列使用 ListSessions 指令來監控資料庫裡的運作中工作階段。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 用戶端程式庫。

• 依附於上述用戶端程式庫的 Spanner 生態系統工具，例如 PGAdapter、JDBC、Hibernate、database/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 錯誤。

啟用多工工作階段

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

• 2.41.0 以上版本的 C++。
• 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. 在「指標」下拉式選單中，依 generic 篩選。

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

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

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

   下圖顯示選取多工處理工作階段的「篩選」選項。

如要進一步瞭解如何搭配使用 OpenTelemetry 和 Spanner，請參閱「Leveraging OpenTelemetry to democratize Spanner Observability」和「Examine latency in a Spanner component with OpenTelemetry」。

疑難排解

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

• Session not found
• RESOURCE_EXHAUSTED

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