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

パフォーマンス キャプチャを使用すると、パフォーマンスが低下したときにインスタンスの詳細な指標をキャプチャして、データベースの一時的な問題を診断できます。パフォーマンス キャプチャを使用するには、インスタンスのパフォーマンス キャプチャを有効にして、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: 20～86400 の整数。指標プローブ間の時間間隔（秒単位）。例: 30、60、100。デフォルトは 30 です。
  • probe-threshold=PROBES: パフォーマンス キャプチャをトリガーするためにしきい値を超過する必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3 です。

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

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

  • running-threads-threshold=THREADS: プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 1010 以上の値を指定する必要があります。設定しない場合、デフォルトはインスタンスのサイズに基づきます。デフォルトは 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_0 です。
  • REGION: リージョン
  • MACHINE_TYPE: マシンタイプ
  • EDITION_TYPE: Cloud SQL エディション
  • PROBING_INTERVAL_SECONDS: 20～86400 の整数。指標プローブ間の時間間隔（秒単位）。デフォルトは 30 です。
  • PROBE_THRESHOLD: パフォーマンス キャプチャをトリガーするためにしきい値を超過する必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3 です。
  • RUNNING_THREADS_THRESHOLD: プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 1010 以上の値を指定する必要があります。設定しない場合、デフォルトはインスタンスのサイズに基づきます。デフォルトは 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: プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 1010 以上の値を指定する必要があります。設定しない場合、デフォルトはインスタンスのサイズに基づきます。デフォルトは 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_0 です。
  • REGION: リージョン
  • MACHINE_TYPE: マシンタイプ
  • EDITION_TYPE: Cloud SQL エディション
  • PROBING_INTERVAL_SECONDS: 20～86400 の整数。指標プローブ間の時間間隔（秒単位）。デフォルトは 30 です。
  • PROBE_THRESHOLD: パフォーマンス キャプチャをトリガーするためにしきい値を超過する必要がある連続回数。有効な範囲は 1～20 です。デフォルトは 3 です。
  • RUNNING_THREADS_THRESHOLD: プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 1010 以上の値を指定する必要があります。設定しない場合、デフォルトはインスタンスのサイズに基づきます。デフォルトは 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: プライマリ インスタンスの場合、しきい値を超えていると見なされるアクティブ スレッドの最小数。例: 1010 以上の値を指定する必要があります。設定しない場合、デフォルトはインスタンスのサイズに基づきます。デフォルトは 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"
}

次のステップ