設定效能擷取功能

MySQL  |  PostgreSQL  |  SQL Server

效能擷取功能可在效能降低時擷取執行個體的詳細指標，協助您診斷資料庫的暫時性問題。如要使用效能擷取功能，請為執行個體啟用這項功能，並設定觸發詳細指標快照的門檻。

設定效能擷取觸發條件的指南

設定效能擷取觸發條件時，請注意下列規範。

• 下列效能擷取觸發條件預設為停用：

  • 高 CPU 使用率
  • 記憶體用量偏高
  • 交易鎖定等待
  • 信號燈等待
  • 觀看記錄清單長度

  如果您為其中一個觸發條件設定門檻，但之後想停用觸發條件，請將門檻值設為 0。

• 為避免過度擷取，請根據歷來成效資料設定觸發條件門檻。

  建議您將門檻設在歷史範圍的較高位置 (例如高於正常每日尖峰工作負載)。

  如果門檻設定過低或太接近一般工作負載，代理程式可能會反覆觸發擷取作業。這可能會導致：

  • 費用較高且記錄負擔較重：不必要的記錄檔可能會迅速增加 Cloud Logging 費用。
  • 延長冷卻睡眠模式：如果執行個體重複違反相同門檻，系統會觸發適應性冷卻退避機制。這會將效能擷取功能設為24 小時睡眠模式，暫停所有觸發檢查和診斷。如果發生實際的重大事件，您可能會在睡眠模式期間遺失重要的診斷資料。

事前準備

設定效能擷取功能前，請先完成下列工作。

必要的角色

如要取得修改執行個體及啟用效能擷取功能所需的權限，請要求管理員授予您專案的下列 IAM 角色：

• Cloud SQL 管理員 (roles/cloudsql.admin)
• Compute 檢視者 (roles/compute.viewer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

啟用效能擷取功能

您可以在建立 Cloud SQL 執行個體時啟用效能擷取功能，也可以在更新現有執行個體時啟用。

如要啟用效能擷取功能，請為執行個體啟用查詢洞察。啟用查詢洞察後，執行個體會使用基本成效擷取設定，以及任何以門檻為準的觸發條件預設值。如果是選用的門檻觸發條件，系統會停用這些觸發條件。

如要在現有執行個體上啟用查詢洞察和效能擷取功能，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 在「自訂執行個體」部分，按一下「顯示設定選項」。
4. 展開「查詢洞察」。
5. 勾選「啟用查詢洞察」核取方塊。
6. 在「啟用其他功能」部分，確認已勾選「擷取效能」核取方塊。
7. 按一下 [儲存]。

注意： Google Cloud 控制台只提供啟用或停用效能擷取的選項。如要設定效能擷取觸發條件或探測設定參數，請使用 gcloud CLI 或 Cloud SQL Admin API。

設定效能擷取功能

使用 gcloud CLI 或 Cloud SQL Admin API 建立或編輯執行個體時，可以設定效能擷取功能，例如定義具體的觸發門檻。修改效能擷取設定或效能擷取觸發門檻，不會重新啟動執行個體，也不會導致執行個體進入維護模式。

以下程序說明如何編輯現有執行個體，以設定效能擷取作業。

gcloud

如要在現有 Cloud SQL 執行個體上設定效能擷取功能，請執行下列指令：

gcloud sql instances patch INSTANCE_NAME \
  --performance-capture-config="enabled=true,PROBE_CONFIGURATION,PERFORMANCE_CAPTURE_THRESHOLDS"

請為 performance-capture-config 旗標加上 enabled=true。 針對相同旗標，您可以為 PROBE_CONFIGURATION 和 PERFORMANCE_CAPTURE_THRESHOLDS 指定選用設定。

您也可以使用 gcloud sql instances patch 指令，修改現有執行個體的效能擷取門檻設定值。

設定效能指標的探測間隔和連續探測次數

您可以將 PROBE_CONFIGURATION 替換成下列一或多個標記設定。如未設定旗標，監控代理程式會使用預設值。

• probing-interval-seconds=SECONDS：介於 20 和 86400 之間的整數。指標探測之間的時間間隔 (以秒為單位)。例如：30、60、100。 預設值為 30。
• probe-threshold=PROBES：必須連續超過門檻的次數，才會觸發效能擷取作業。有效範圍為 1 至 20。 預設值為 3。

設定效能擷取門檻

您可以將 PERFORMANCE_CAPTURE_THRESHOLDS 替換為下列一或多個旗標設定。如果沒有為旗標設定值，監控代理程式會使用門檻的預設值。如要進一步瞭解這些標記設定的觸發條件，請參閱「效能擷取觸發條件」。

• running-threads-threshold=THREADS：無論是主要或副本執行個體，都必須有超過門檻的最低有效執行緒數量。例如：10。不得小於 10。 如未設定，預設值會根據執行個體大小而定。 預設值為 MIN(600, cpuCount * 20)。
• seconds-behind-source-threshold=SECONDS：針對唯讀副本，以秒為單位，表示超過門檻的最低複製延遲時間。必須大於 1。 預設值為 900。
• transaction-duration-threshold=SECONDS：未提交交易的持續時間 (以秒為單位)，之後系統會追蹤交易並納入成效擷取記錄。例如，300。值不得小於 60。 預設值為 3600。您也可以選擇自動結束長時間執行的交易。
• cpu-utilization-threshold-percent=CPU_PERCENTAGE：整體 CPU 使用率百分比持續超過。例如，90。最小值為 10，最大值為 99。預設值為 0，也就是停用。
• memory-usage-threshold-percent=MEMORY_PERCENTAGE：整體記憶體用量百分比持續超過此值。例如，90。最小值為 10，最大值為 99。預設值為 0，也就是停用。
• transaction-lock-wait-threshold-count=TRANSACTION_COUNT：允許交易處於 `LOCK WAIT` 狀態的門檻。例如，50。最小值為 10，最大值為 10000。預設值為 0，也就是停用。
• semaphore-wait-threshold-count=SEMAPHORE_THREAD_COUNT： 等待 SHOW ENGINE INNODB STATUS 指令中 InnoDB 信號燈的執行緒數量門檻。 例如：20。最小值為 10，最大值為 10000。預設值為 0，也就是停用。
• history-list-length-threshold-count=HISTORY_LIST_LENGTH_COUNT： 資料庫允許的 InnoDB 歷程記錄清單長度 (HLL) 計數門檻。 例如，100000。最小值為 10000，最大值為 10000000。預設值為 0，也就是停用。

REST v1

使用任何要求資料之前，請先修改下列項目的值：

針對 performanceCaptureConfig 欄位，請加入下列旗標設定。如未設定旗標值，效能擷取功能會使用門檻的預設值。如要進一步瞭解這些標記設定的觸發條件，請參閱「效能擷取觸發條件」。

• PERFORMANCE_CAPTURE_ENABLED：設為 true，為執行個體啟用效能擷取功能。
• PROBING_INTERVAL_SECONDS：介於 30 和 86400 之間的整數。 指標探測之間的時間間隔 (以秒為單位)。預設值為 30。
• PROBE_THRESHOLD：超過門檻的次數必須達到這個值，才會觸發效能擷取作業。有效範圍為 1 至 20。預設值為 3。
• RUNNING_THREADS_THRESHOLD：主要執行個體中，超過門檻的有效執行緒數量下限。例如：10。不得小於 10。 如未設定，預設值會根據執行個體大小而定。 預設值為 MIN(600, cpuCount * 20)。
• SECONDS_BEHIND_SOURCE_THRESHOLD：唯讀副本的最低複製延遲時間 (以秒為單位)，超過此時間即視為超過門檻。必須大於 1。預設值為 900。
• TRANSACTION_DURATION_THRESHOLD：未提交交易的持續時間 (以秒為單位)，之後系統會追蹤交易並納入成效擷取記錄。例如，300。值不得小於 60。 預設值為 3600。如要設定自動終止長時間執行的交易，可以在 performanceCaptureConfig 欄位中加入其他設定。詳情請參閱「自動結束長時間執行的交易」。
• CPU_UTILIZATION_THRESHOLD_PERCENT：整體 CPU 使用率百分比持續超過。例如，90。最小值為 10，最大值為 99。預設值為 0，也就是停用。
• MEMORY_USAGE_THRESHOLD_PERCENT：整體記憶體用量百分比持續超過此值。例如，90。最小值為 10，最大值為 99。預設值為 0，也就是停用。
• TRANSACTION_LOCK_WAIT_THRESHOLD_COUNT： 允許交易處於 LOCK WAIT 狀態的門檻。 例如：50。最小值為 10，最大值為 10000。預設值為 0，也就是停用。
• SEMAPHORE_WAIT_THRESHOLD_COUNT： 等待 SHOW ENGINE INNODB STATUS 指令中 InnoDB 信號燈的執行緒數量門檻。 例如：20。最小值為 10，最大值為 10000。預設值為 0，也就是停用。
• HISTORY_LIST_LENGTH_THRESHOLD_COUNT： 資料庫允許的 InnoDB 歷程記錄清單長度 (HLL) 計數門檻。 例如，100000。最小值為 10000，最大值為 10000000。預設值為 0，也就是停用。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "performanceCaptureConfig": {
     "enabled": PERFORMANCE_CAPTURE_ENABLED,
     "probingIntervalSeconds": PROBING_INTERVAL_SECONDS,
     "probeThreshold": PROBE_THRESHOLD,
     "runningThreadsThreshold": RUNNING_THREADS_THRESHOLD,
     "secondsBehindSourceThreshold": SECONDS_BEHIND_SOURCE_THRESHOLD,
     "transactionDurationThreshold": TRANSACTION_DURATION_THRESHOLD,
     "cpuUtilizationThresholdPercent": CPU_UTILIZATION_THRESHOLD_PERCENT,
     "memoryUsageThresholdPercent": MEMORY_USAGE_THRESHOLD_PERCENT,
     "transactionLockWaitThresholdCount": TRANSACTION_LOCK_WAIT_THRESHOLD_COUNT,
     "semaphoreWaitThresholdCount": SEMAPHORE_WAIT_THRESHOLD_COUNT,
     "historyListLengthThresholdCount": HISTORY_LIST_LENGTH_THRESHOLD_COUNT
  },
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2025-11-10T22:19:33.735Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

使用任何要求資料之前，請先修改下列項目的值：

針對 performanceCaptureConfig 欄位，請加入下列旗標設定。如果沒有為這些旗標設定值，監控代理程式就會使用門檻的預設值。如要進一步瞭解這些標記設定的觸發條件，請參閱「效能擷取觸發條件」。

• PERFORMANCE_CAPTURE_ENABLED：設為 true，為執行個體啟用效能擷取功能。
• PROBING_INTERVAL_SECONDS：介於 30 和 86400 之間的整數。 指標探測之間的時間間隔 (以秒為單位)。預設值為 30。
• PROBE_THRESHOLD：超過門檻的次數必須達到這個值，才會觸發效能擷取作業。有效範圍為 1 至 20。預設值為 3。
• RUNNING_THREADS_THRESHOLD：主要執行個體中，超過門檻的有效執行緒數量下限。例如：10。不得小於 10。 如未設定，預設值會根據執行個體大小而定。 預設值為 MIN(600, cpuCount * 20)。
• SECONDS_BEHIND_SOURCE_THRESHOLD：唯讀副本的最低複製延遲時間 (以秒為單位)，超過此時間即視為超過門檻。必須大於 1。預設值為 900。
• TRANSACTION_DURATION_THRESHOLD：未提交交易的持續時間 (以秒為單位)，之後系統會追蹤交易並納入成效擷取記錄。例如，300。值不得小於 60。預設值為 3600。如要設定自動終止長時間執行的交易，可以在 performanceCaptureConfig 欄位中加入其他設定。詳情請參閱「自動結束長時間執行的交易」。
• CPU_UTILIZATION_THRESHOLD_PERCENT：整體 CPU 使用率百分比持續超過。例如，90。最小值為 10，最大值為 99。預設值為 0，也就是停用。
• MEMORY_USAGE_THRESHOLD_PERCENT：整體記憶體用量百分比持續超過此值。例如，90。最小值為 10，最大值為 99。預設值為 0，也就是停用。
• TRANSACTION_LOCK_WAIT_THRESHOLD_COUNT： 允許交易處於 LOCK WAIT 狀態的門檻。 例如：50。最小值為 10，最大值為 10000。預設值為 0，也就是停用。
• SEMAPHORE_WAIT_THRESHOLD_COUNT： 等待 SHOW ENGINE INNODB STATUS 指令中 InnoDB 信號燈的執行緒數量門檻。 例如：20。最小值為 10，最大值為 10000。預設值為 0，也就是停用。
• HISTORY_LIST_LENGTH_THRESHOLD_COUNT： 資料庫允許的 InnoDB 歷程記錄清單長度 (HLL) 計數門檻。 例如，100000。最小值為 10000，最大值為 10000000。預設值為 0，也就是停用。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "performanceCaptureConfig": {
     "enabled": PERFORMANCE_CAPTURE_ENABLED,
     "probingIntervalSeconds": PROBING_INTERVAL_SECONDS,
     "probeThreshold": PROBE_THRESHOLD,
     "runningThreadsThreshold": RUNNING_THREADS_THRESHOLD,
     "secondsBehindSourceThreshold": SECONDS_BEHIND_SOURCE_THRESHOLD,
     "transactionDurationThreshold": TRANSACTION_DURATION_THRESHOLD,
     "cpuUtilizationThresholdPercent": CPU_UTILIZATION_THRESHOLD_PERCENT,
     "memoryUsageThresholdPercent": MEMORY_USAGE_THRESHOLD_PERCENT,
     "transactionLockWaitThresholdCount": TRANSACTION_LOCK_WAIT_THRESHOLD_COUNT,
     "semaphoreWaitThresholdCount": SEMAPHORE_WAIT_THRESHOLD_COUNT,
     "historyListLengthThresholdCount": HISTORY_LIST_LENGTH_THRESHOLD_COUNT
  },
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2025-11-10T22:19:33.735Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

自動結束長時間執行的交易

您可以利用效能擷取功能，終止任何超過預先定義時間長度的交易，避免查詢失控，導致執行個體不穩定。

如要將 MySQL 適用的 Cloud SQL 資料庫設定為自動終止長時間執行的交易，請使用 gcloud CLI 或 Cloud SQL Admin API。

gcloud

如要啟用自動終止長時間執行的交易，請設定交易的門檻限制。如要設定自動結束交易，請執行下列指令：

gcloud sql instances patch INSTANCE_NAME \
  --performance-capture-config="transaction-kill-threshold-seconds=SECONDS"

更改下列內容：

• INSTANCE_NAME：執行個體的名稱。
• SECONDS：長時間執行的交易自動結束的時間限制，單位為秒。這個限制值不得小於您為 transaction-duration-threshold 或 transactionDurationThreshold 觸發條件設定的值。

您也可以指定要自動終止的交易類型 (預設為 READ_ONLY_TRANSACTIONS)，並自訂要排除的特定交易使用者或主辦人清單。如要設定這些選項，請執行下列指令：

gcloud sql instances patch INSTANCE_NAME \
  --performance-capture-config="transaction-kill-threshold-seconds=SECONDS,transaction-kill-type=TRANSACTION_TYPE,transaction-kill-excluded-user-hosts=EXCLUSION_LIST"

更改下列內容：

• TRANSACTION_TYPE：決定要結束的交易類別。請指定下列其中一個值：
  • READ_ONLY_TRANSACTIONS：僅結束唯讀或 SELECT 查詢。 在未指定 transaction-kill-type 的情況下，這是預設值。
  • ALL_TRANSACTIONS：終止超過門檻的任何執行中查詢，包括含有寫入作業的查詢。包括 INSERT、UPDATE、DELETE 和其他 DDL 陳述式。
• EXCLUSION_LIST：要排除的字串清單。您可以透過特定資料庫使用者名稱和主機組合提供項目，例如 user@host，或以 MySQL 樣式使用者帳戶名稱提供項目，預設為 user@%。這份清單支援萬用字元 % 和 _，可用於比對主機部分。

舉例來說，您可能會執行下列指令，設定自動終止「所有」交易 (包括所有讀取和寫入交易)，但排除長時間交易的特定已知使用者。

gcloud sql instances patch example-instance \
--performance-capture-config="transaction-kill-threshold-seconds=600,transaction-kill-type=ALL_TRANSACTIONS,transaction-kill-excluded-user-hosts=report_user@%;backup_user@localhost"

REST v1

使用任何要求資料之前，請先修改下列項目的值：

• SECONDS：系統自動終止長時間執行交易的時限 (以秒為單位)。這個上限值不得小於您為 transactionDurationThreshold 欄位設定的值。
• TRANSACTION_TYPE：決定要結束的交易類別。請使用下列其中一個值：
  • READ_ONLY_TRANSACTIONS：僅終止唯讀或 SELECT 查詢。 在未指定 transactionKillType 的情況下，這是預設值。
  • ALL_TRANSACTIONS：終止超過門檻的任何執行中查詢，包括含有寫入作業的查詢。包括 INSERT、UPDATE、DELETE 和其他 DDL 陳述式。
• EXCLUSION_LIST：要排除的字串清單。您可以透過特定資料庫使用者名稱和主機組合提供項目，例如 user@host，或以 MySQL 樣式的使用者帳戶名稱提供項目，預設為 user@%。這份清單支援萬用字元 % 和 _，可在主機部分進行比對。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "performanceCaptureConfig": {
    "transactionKillThresholdSeconds": SECONDS,
    "transactionKillType": TRANSACTION_TYPE,
    "transactionKillExcludedUserHosts": [ EXCLUSION_LIST
    ]
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2025-11-10T22:19:33.735Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

使用任何要求資料之前，請先修改下列項目的值：

• SECONDS：系統自動終止長時間執行交易的時限 (以秒為單位)。這個上限值不得小於您為 transactionDurationThreshold 欄位設定的值。
• TRANSACTION_TYPE：決定要結束的交易類別。請使用下列其中一個值：
  • READ_ONLY_TRANSACTIONS：僅終止唯讀或 SELECT 查詢。 在未指定 transactionKillType 的情況下，這是預設值。
  • ALL_TRANSACTIONS：終止超過門檻的任何執行中查詢，包括含有寫入作業的查詢。包括 INSERT、UPDATE、DELETE 和其他 DDL 陳述式。
• EXCLUSION_LIST：要排除的字串清單。您可以透過特定資料庫使用者名稱和主機組合提供項目，例如 user@host，或以 MySQL 樣式的使用者帳戶名稱提供項目，預設為 user@%。這份清單支援萬用字元 % 和 _，可在主機部分進行比對。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "performanceCaptureConfig": {
    "transactionKillThresholdSeconds": SECONDS,
    "transactionKillType": TRANSACTION_TYPE,
    "transactionKillExcludedUserHosts": [ EXCLUSION_LIST
    ]
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2025-11-10T22:19:33.735Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

停用效能擷取功能

如要停用成效擷取功能，請按照下列步驟操作。

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 按一下 [編輯]。
4. 在「自訂執行個體」部分，按一下「顯示設定選項」。
5. 展開「查詢洞察」。
6. 在「啟用其他功能」部分，取消勾選「效能擷取」核取方塊。
7. 按一下 [儲存]。

gcloud

gcloud sql instances patch INSTANCE_NAME \
  --performance-capture-config="enabled=false"

將 INSTANCE_NAME 替換為要停用效能擷取的執行個體名稱。

REST v1

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "performanceCaptureConfig": {
     "enabled": false
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "INSERT_TIME",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "performanceCaptureConfig": {
     "enabled": false
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2025-11-10T22:19:33.735Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

後續步驟

• 查看效能擷取記錄
• 監控執行個體