配置性能捕获

借助性能捕获功能，您可以在性能下降时捕获实例的详细指标，从而诊断数据库的暂时性问题。 如需使用性能捕获功能，请为实例启用性能捕获功能，并配置触发 Cloud SQL 实例的详细基于指标的快照的阈值。

配置性能捕获触发器的指南

为性能捕获配置触发器时，请谨记以下准则。

  • 以下性能捕获触发器默认处于停用状态：

    • 高 CPU 利用率
    • 内存用量较高
    • 事务锁等待
    • 信号量等待
    • 历史记录列表长度

    如果您为其中一个触发器配置了阈值，但之后想要停用该触发器，请将阈值设置为 0。

  • 为帮助防止过度捕获，请根据历史效果数据配置触发阈值。

    我们建议您将阈值设置为历史范围的较高值（例如，高于正常每日峰值工作负载）。

    如果阈值设置得过低或过接近典型工作负载，代理可能会反复触发捕获。这可能会导致：

    • 费用和日志记录开销较高：不必要的日志可能会迅速增加 Cloud Logging 费用。
    • 延长冷却时间睡眠模式：如果实例反复违反同一阈值，系统会触发自适应冷却时间退避机制。这会将性能捕获置于 24 小时睡眠模式，该模式会暂停所有触发检查和诊断。如果在此休眠模式期间发生实际的严重事件，您可能会丢失关键的诊断数据。

准备工作

在配置性能捕获之前，请完成以下任务。

所需的角色

如需获得修改实例和启用性能捕获所需的权限，请让管理员向您授予项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用性能捕获

您可以在创建 Cloud SQL 实例或更新现有实例时启用性能捕获功能。

如需启用性能捕获，请为实例启用 Query Insights。启用查询洞见后，实例会使用性能捕获的基本配置以及任何基于阈值的触发器的默认值。对于基于阈值的可选触发器，触发器处于停用状态。

如需在现有实例上启用查询数据分析和性能捕获功能，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 如需打开实例的概览页面，请点击实例名称。
  3. 在自定义实例部分中，点击显示配置选项。
  4. 展开 Query Insights。
  5. 选中启用查询数据分析复选框。
  6. 在启用其他功能部分中，确保已选中性能捕获复选框。
  7. 点击保存。

配置性能捕获

您可以使用 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：允许处于“锁定等待”状态的交易的阈值。 例如 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
  },
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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
  },
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

自动结束长时间运行的事务

您可以使用性能捕获功能来结束任何超出预定义时长的事务，这有助于防止失控查询导致实例不稳定。

如需将 Cloud SQL for MySQL 数据库配置为自动结束长时间运行的事务，请使用 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
    ]
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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
    ]
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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 实例页面。

    转到“Cloud SQL 实例”

  2. 如需打开实例的概览页面，请点击实例名称。
  3. 点击修改。
  4. 在自定义实例部分中，点击显示配置选项。
  5. 展开 Query Insights。
  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
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

后续步骤