パフォーマンス キャプチャを構成する

パフォーマンス キャプチャ を使用すると、パフォーマンスが低下したときにインスタンスの詳細な 指標をキャプチャして、データベースの一時的な問題を診断できます。 パフォーマンス キャプチャを使用するには、インスタンスのパフォーマンス キャプチャを有効にして、Cloud SQL インスタンスの詳細な指標ベースのスナップショットをトリガーするしきい値を構成します。

始める前に

パフォーマンス キャプチャを使用するには、 インスタンスの Query Insights を有効にする必要があります。

必要なロール

インスタンスを作成してパフォーマンス キャプチャを有効にするために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタム ロールや他の事前定義 ロールから取得することもできます。

パフォーマンス キャプチャを有効にして構成する

パフォーマンス キャプチャは、Cloud SQL インスタンスの作成時または更新時に有効にできます。

gcloud

インスタンスを作成して構成する

Cloud SQL インスタンスの作成時にパフォーマンス キャプチャを有効にするには、 次のコマンドを実行します。

gcloud beta sql instances create INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --region=REGION \
  --tier=TIER \
  --edition=EDITION_TYPE \
  --performance-capture-config="enabled=true,PROBE_CONFIGURATION,PERFORMANCE_CAPTURE_THRESHOLDS"

次のように置き換えます。

  • INSTANCE_NAME: インスタンス名
  • DATABASE_VERSION: データベースのバージョン。 たとえば、MYSQL_8_4 や MYSQL_8_0_37 です。データベース バージョンを指定しない場合、デフォルトのデータベース バージョンは MYSQL_8_0 です。
  • REGION: リージョン
  • TIER: マシンタイプ
  • EDITION_TYPE: Cloud SQL エディション

performance-capture-config フラグに enabled=true を含めます。同じフラグ定義で、 PROBE_CONFIGURATION と PERFORMANCE_CAPTURE_THRESHOLDS のオプション構成を指定できます。また、インスタンスを更新して後で指定することもできます。

次に例を示します。

gcloud beta sql instances create my-instance \
  --database-version=MYSQL_8_0 \
  --edition=ENTERPRISE_PLUS \
  --tier=db-perf-optimized-N-4 \
  --region=us-west1 \
  --performance-capture-config="enabled=true,probing-interval-seconds=30,probe-threshold=5,running-threads-threshold=10,transaction-duration-threshold=300"

既存のインスタンスを更新する

既存の Cloud SQL インスタンスでパフォーマンス キャプチャを有効にするには、次のコマンドを実行します。

gcloud beta 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 beta sql instances patch コマンドを使用して、既存のインスタンスのパフォーマンス キャプチャのしきい値構成値を更新することもできます。

パフォーマンス指標のプローブ間隔と連続プローブを構成する

PROBE_CONFIGURATION は、次のフラグ設定のいずれかまたは両方に置き換えることができます。フラグを設定しない場合、モニタリング エージェントはデフォルト値を使用します。

  • probing-interval-seconds=SECONDS: ～86400 の整数。20指標プローブ間の時間間隔（秒単位）。 例: 30、60、100。 デフォルトは 30 です。
  • probe-threshold=PROBES: パフォーマンス キャプチャをトリガーするためにしきい値を超える必要がある連続回数。有効な範囲は 1～20 です。 デフォルトは 3 です。

パフォーマンス キャプチャのしきい値を構成する

PERFORMANCE_CAPTURE_THRESHOLDS は、 次のフラグ設定の 1 つ以上に置き換えることができます。フラグの値を設定しない場合、モニタリング エージェントはしきい値のデフォルト値を使用します。

  • running-threads-threshold=THREADS：プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 10。 10 以上の値を指定する必要があります。 設定しない場合、デフォルトはインスタンスのサイズに基づきます。 デフォルトは MIN(600, cpuCount * 20) です。
  • seconds-behind-source-threshold=SECONDS : 読み取りレプリカの場合、しきい値を超えていると見なされる最小レプリケーション ラグ（秒単位）。0 より大きい値を入力してください。 デフォルトは 900 です。
  • transaction-duration-threshold=SECONDS：トランザクションが追跡され、パフォーマンス キャプチャ ログに含まれるまでの、コミットされていないトランザクションの期間（秒単位）。例: 300、600。最小値は 60 です。 デフォルトは 3600 です。

REST v1

インスタンスを作成して構成する

リクエストのデータを使用する前に、 次のように置き換えます。

  • PROJECT_ID: プロジェクト ID
  • INSTANCE_ID: インスタンス ID
  • DATABASE_VERSION: データベースのバージョン。たとえば、MYSQL_8_4 や MYSQL_8_0_37 です。データベース バージョンを指定しない場合、デフォルトのデータベース バージョンは MYSQL_8_4 です。
  • REGION: リージョン
  • MACHINE_TYPE: マシンタイプ
  • EDITION_TYPE: Cloud SQL エディション
  • PROBING_INTERVAL_SECONDS：20～86400 の整数。 指標プローブ間の時間間隔（秒単位）。デフォルトは 30 です。
  • PROBE_THRESHOLD：パフォーマンス キャプチャをトリガーするためにしきい値を超える必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3 です。
  • RUNNING_THREADS_THRESHOLD：プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 10。 10 以上の値を指定する必要があります。 設定しない場合、デフォルトはインスタンスのサイズに基づきます。 デフォルトは MIN(600, cpuCount * 20) です。
  • SECONDS_BEHIND_SOURCE_THRESHOLD：読み取りレプリカの場合、しきい値を超えていると見なされる最小レプリケーション ラグ（秒単位）。0 より大きい値を入力してください。デフォルトは 900 です。
  • TRANSACTION_DURATION_THRESHOLD：トランザクションが追跡され、パフォーマンス キャプチャ ログに含まれるまでの、コミットされていない トランザクションの期間（秒単位）。 例: 300、600。最小値は 60 です。デフォルトは 3600 です。

HTTP メソッドと URL: 

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

リクエストの本文（JSON）: 

{
  "name": "INSTANCE_ID",
  "region": "REGION",
  "databaseVersion": "DATABASE_VERSION",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE"
  },
  "performanceCaptureConfig": {
     "enabled": true,
     "probingIntervalSeconds": PROBING_INTERVAL_SECONDS,
     "probeThreshold": PROBE_THRESHOLD,
     "runningThreadsThreshold": RUNNING_THREADS_THRESHOLD,
     "secondsBehindSourceThreshold": SECONDS_BEHIND_SOURCE_THRESHOLD,
     "transactionDurationThreshold": TRANSACTION_DURATION_THRESHOLD
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような 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": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

既存のインスタンスを更新する

リクエストのデータを使用する前に、 次のように置き換えます。

  • PERFORMANCE_CAPTURE_ENABLE: インスタンスのパフォーマンス キャプチャを有効にするには、true に設定します。
  • PROBING_INTERVAL_SECONDS：20～86400 の整数。 指標プローブ間の時間間隔（秒単位）。デフォルトは 30 です。
  • PROBE_THRESHOLD：パフォーマンス キャプチャをトリガーするためにしきい値を超える必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3 です。
  • RUNNING_THREADS_THRESHOLD：プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 10。 10 以上の値を指定する必要があります。 設定しない場合、デフォルトはインスタンスのサイズに基づきます。 デフォルトは MIN(600, cpuCount * 20) です。
  • SECONDS_BEHIND_SOURCE_THRESHOLD：読み取りレプリカの場合、しきい値を超えていると見なされる最小レプリケーション ラグ（秒単位）。0 より大きい値を入力してください。デフォルトは 900 です。
  • TRANSACTION_DURATION_THRESHOLD：トランザクションが追跡され、パフォーマンス キャプチャ ログに含まれるまでの、コミットされていない トランザクションの期間（秒単位）。 例: 300、600。最小値は 60 です。デフォルトは 3600 です。

HTTP メソッドと URL: 

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

リクエストの本文（JSON）: 

{
  "performanceCaptureConfig": {
     "enabled": PERFORMANCE_CAPTURE_ENABLE,
     "probingIntervalSeconds": PROBING_INTERVAL_SECONDS,
     "probeThreshold": PROBE_THRESHOLD,
     "runningThreadsThreshold": RUNNING_THREADS_THRESHOLD,
     "secondsBehindSourceThreshold": SECONDS_BEHIND_SOURCE_THRESHOLD,
     "transactionDurationThreshold": TRANSACTION_DURATION_THRESHOLD
  },
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような 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

インスタンスを作成して構成する

リクエストのデータを使用する前に、 次のように置き換えます。

  • PROJECT_ID: プロジェクト ID
  • INSTANCE_ID: インスタンス ID
  • DATABASE_VERSION: データベースのバージョン。たとえば、MYSQL_8_4 や MYSQL_8_0_37 です。データベース バージョンを指定しない場合、デフォルトのデータベース バージョンは MYSQL_8_4 です。
  • REGION: リージョン
  • MACHINE_TYPE: マシンタイプ
  • EDITION_TYPE: Cloud SQL エディション
  • PROBING_INTERVAL_SECONDS：20～86400 の整数。 指標プローブ間の時間間隔（秒単位）。デフォルトは 30 です。
  • PROBE_THRESHOLD：パフォーマンス キャプチャをトリガーするためにしきい値を超える必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3です。
  • RUNNING_THREADS_THRESHOLD：プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 10。 10 以上の値を指定する必要があります。 設定しない場合、デフォルトはインスタンスのサイズに基づきます。 デフォルトは MIN(600, cpuCount * 20) です。
  • SECONDS_BEHIND_SOURCE_THRESHOLD：読み取りレプリカの場合、しきい値を超えていると見なされる最小レプリケーション ラグ（秒単位）。0 より大きい値を入力してください。デフォルトは 900です。
  • TRANSACTION_DURATION_THRESHOLD：トランザクションが追跡され、パフォーマンス キャプチャ ログに含まれるまでの、コミットされていない トランザクションの期間（秒単位）。 例: 300、600。最小値は 60 です。デフォルトは 3600です。

HTTP メソッドと URL: 

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

リクエストの本文（JSON）: 

{
  "name": "INSTANCE_ID",
  "region": "REGION",
  "databaseVersion": "DATABASE_VERSION",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
  },
  "performanceCaptureConfig": {
     "enabled": true,
     "probingIntervalSeconds": PROBING_INTERVAL_SECONDS,
     "probeThreshold": PROBE_THRESHOLD,
     "runningThreadsThreshold": RUNNING_THREADS_THRESHOLD,
     "secondsBehindSourceThreshold": SECONDS_BEHIND_SOURCE_THRESHOLD,
     "transactionDurationThreshold": TRANSACTION_DURATION_THRESHOLD
  },
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような 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": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

既存のインスタンスを更新する

リクエストのデータを使用する前に、 次のように置き換えます。

  • PERFORMANCE_CAPTURE_ENABLE: インスタンスのパフォーマンス キャプチャを有効にするには、true に設定します。
  • PROBING_INTERVAL_SECONDS：20～86400 の整数。 指標プローブ間の時間間隔（秒単位）。デフォルトは 30 です。
  • PROBE_THRESHOLD：パフォーマンス キャプチャをトリガーするためにしきい値を超える必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3 です。
  • RUNNING_THREADS_THRESHOLD：プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 10。10 以上の値を指定する必要があります。 設定しない場合、デフォルトはインスタンスのサイズに基づきます。 デフォルトは MIN(600, cpuCount * 20) です。
  • SECONDS_BEHIND_SOURCE_THRESHOLD：読み取りレプリカの場合、しきい値を超えていると見なされる最小レプリケーション ラグ（秒単位）。0 より大きい値を入力してください。デフォルトは 900 です。
  • TRANSACTION_DURATION_THRESHOLD：トランザクションが追跡され、パフォーマンス キャプチャ ログに含まれるまでの、コミットされていない トランザクションの期間（秒単位）。 例: 300、600。最小値は 60 です。デフォルトは 3600 です。

HTTP メソッドと URL: 

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

リクエストの本文（JSON）: 

{
  "performanceCaptureConfig": {
     "enabled": PERFORMANCE_CAPTURE_ENABLE,
     "probingIntervalSeconds": PROBING_INTERVAL_SECONDS,
     "probeThreshold": PROBE_THRESHOLD,
     "runningThreadsThreshold": RUNNING_THREADS_THRESHOLD,
     "secondsBehindSourceThreshold": SECONDS_BEHIND_SOURCE_THRESHOLD,
     "transactionDurationThreshold": TRANSACTION_DURATION_THRESHOLD
  },
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような 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"
}

パフォーマンス キャプチャを無効にする

パフォーマンス キャプチャを無効にするには、次のコマンドを使用します。

gcloud

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

INSTANCE_NAME は、パフォーマンス キャプチャを無効にするインスタンスの 名前に置き換えます。

REST v1

HTTP メソッドと URL: 

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 メソッドと URL: 

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"
}

次のステップ