Configurare l'acquisizione delle prestazioni

Acquisizione delle prestazioni ti consente di diagnosticare problemi temporanei del database acquisendo metriche dettagliate per la tua istanza quando le prestazioni sono ridotte. Per utilizzare l'acquisizione delle prestazioni, attivala per la tua istanza e configura le soglie che attivano gli snapshot dettagliati basati sulle metriche della tua istanza Cloud SQL.

Prima di iniziare

Per utilizzare l'acquisizione delle prestazioni, devi abilitare Query Insights per la tua istanza.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un'istanza e attivare l'acquisizione delle prestazioni, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Attivare e configurare l'acquisizione del rendimento

Puoi abilitare l'acquisizione delle prestazioni quando crei o aggiorni l'istanza Cloud SQL.

gcloud

Crea e configura un'istanza

Per abilitare l'acquisizione delle prestazioni quando crei l'istanza Cloud SQL, esegui questo comando:

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"

Sostituisci quanto segue:

  • INSTANCE_NAME: il nome dell'istanza
  • DATABASE_VERSION: la versione del database. Ad esempio: MYSQL_8_4 o MYSQL_8_0_37. Se non specifichi una versione del database, la versione predefinita è MYSQL_8_0.
  • REGION: la regione
  • TIER: il tipo di macchina
  • EDITION_TYPE: la tua versione di Cloud SQL

Per il flag performance-capture-config, includi enabled=true. Nella stessa definizione del flag, puoi specificare configurazioni facoltative per PROBE_CONFIGURATION e per PERFORMANCE_CAPTURE_THRESHOLDS oppure puoi specificarle in un secondo momento aggiornando l'istanza.

Ad esempio:

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"

Aggiornare un'istanza esistente

Per abilitare l'acquisizione delle prestazioni per un'istanza Cloud SQL esistente, esegui questo comando:

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

Per il flag performance-capture-config, includi enabled=true. Per lo stesso flag, puoi specificare configurazioni facoltative per PROBE_CONFIGURATION e per PERFORMANCE_CAPTURE_THRESHOLDS.

Puoi anche utilizzare il comando gcloud beta sql instances patch per aggiornare i valori di configurazione della soglia per l'acquisizione delle prestazioni su un'istanza esistente.

Configurare l'intervallo di probing e i probe consecutivi delle metriche di rendimento

Puoi sostituire PROBE_CONFIGURATION con una o entrambe le seguenti impostazioni dei flag. Se non imposti i flag, l'agente di monitoraggio utilizza il valore predefinito.

  • probing-interval-seconds=SECONDS: un numero intero compreso tra 20 e 86400. L'intervallo di tempo, in secondi, tra i probe delle metriche. Ad esempio, 30, 60, 100. Il valore predefinito è 30.
  • probe-threshold=PROBES: il numero di volte consecutive in cui una soglia deve essere superata per attivare l'acquisizione del rendimento. L'intervallo valido è compreso tra 1 e 20. Il valore predefinito è 3.

Configurare le soglie di acquisizione delle prestazioni

Puoi sostituire PERFORMANCE_CAPTURE_THRESHOLDS con una o più delle seguenti impostazioni dei flag. Se non imposti i valori per i flag, l'agente di monitoraggio utilizza i valori predefiniti per le soglie.

  • running-threads-threshold=THREADS: per le istanze principali, il numero minimo di thread attivi considerati al di sopra della soglia. Ad esempio, 10. Deve essere maggiore o uguale a 10. Se non viene impostato, il valore predefinito si basa sulle dimensioni dell'istanza. Il valore predefinito è MIN(600, cpuCount * 20).
  • seconds-behind-source-threshold=SECONDS : per le repliche di lettura, il ritardo di replica minimo, in secondi, considerato superiore alla soglia. Deve essere maggiore di 0. Il valore predefinito è 900.
  • transaction-duration-threshold=SECONDS: la durata, in secondi, di una transazione non eseguita prima che venga monitorata e inclusa in un log di acquisizione delle prestazioni. Ad esempio, 300, 600. Il valore minimo è 60. Il valore predefinito è 3600.

REST v1

Crea e configura un'istanza

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • INSTANCE_ID: l'ID istanza
  • DATABASE_VERSION: la versione del database. Ad esempio: MYSQL_8_4 o MYSQL_8_0_37. Se non specifichi una versione del database, la versione predefinita è MYSQL_8_0.
  • REGION: la regione
  • MACHINE_TYPE: il tipo di macchina
  • EDITION_TYPE: la tua versione di Cloud SQL
  • PROBING_INTERVAL_SECONDS: un numero intero compreso tra 20 e 86400. L'intervallo di tempo, in secondi, tra i probe delle metriche. Il valore predefinito è 30.
  • PROBE_THRESHOLD: il numero di volte consecutive in cui una soglia deve essere superata per attivare un'acquisizione del rendimento. L'intervallo valido è compreso tra 1 e 20. Il valore predefinito è 3.
  • RUNNING_THREADS_THRESHOLD: per le istanze principali, il numero minimo di thread attivi considerati al di sopra della soglia. Ad esempio, 10. Deve essere maggiore o uguale a 10. Se non viene impostato, il valore predefinito si basa sulle dimensioni dell'istanza. Il valore predefinito è MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: per le repliche di lettura, il ritardo di replica minimo, in secondi, considerato superiore alla soglia. Deve essere maggiore di 0. Il valore predefinito è 900.
  • TRANSACTION_DURATION_THRESHOLD: la durata, in secondi, di una transazione non eseguita prima che venga monitorata e inclusa in un log di acquisizione del rendimento. Ad esempio, 300, 600. Il valore minimo è 60. Il valore predefinito è 3600.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Aggiornare un'istanza esistente

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PERFORMANCE_CAPTURE_ENABLE: impostato su true per abilitare l'acquisizione delle prestazioni per l'istanza.
  • PROBING_INTERVAL_SECONDS: un numero intero compreso tra 20 e 86400. L'intervallo di tempo, in secondi, tra i probe delle metriche. Il valore predefinito è 30.
  • PROBE_THRESHOLD: il numero di volte consecutive in cui una soglia deve essere superata per attivare un'acquisizione del rendimento. L'intervallo valido è compreso tra 1 e 20. Il valore predefinito è 3.
  • RUNNING_THREADS_THRESHOLD: per le istanze principali, il numero minimo di thread attivi considerati al di sopra della soglia. Ad esempio, 10. Deve essere maggiore o uguale a 10. Se non viene impostato, il valore predefinito si basa sulle dimensioni dell'istanza. Il valore predefinito è MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: per le repliche di lettura, il ritardo di replica minimo, in secondi, considerato superiore alla soglia. Deve essere maggiore di 0. Il valore predefinito è 900.
  • TRANSACTION_DURATION_THRESHOLD: la durata, in secondi, di una transazione non eseguita prima che venga monitorata e inclusa in un log di acquisizione del rendimento. Ad esempio, 300, 600. Il valore minimo è 60. Il valore predefinito è 3600.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Crea e configura un'istanza

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • INSTANCE_ID: l'ID istanza
  • DATABASE_VERSION: la versione del database. Ad esempio: MYSQL_8_4 o MYSQL_8_0_37. Se non specifichi una versione del database, la versione predefinita è MYSQL_8_0.
  • REGION: la regione
  • MACHINE_TYPE: il tipo di macchina
  • EDITION_TYPE: la tua versione di Cloud SQL
  • PROBING_INTERVAL_SECONDS: un numero intero compreso tra 20 e 86400. L'intervallo di tempo, in secondi, tra i probe delle metriche. Il valore predefinito è 30.
  • PROBE_THRESHOLD: il numero di volte consecutive in cui una soglia deve essere superata per attivare un'acquisizione del rendimento. L'intervallo valido è compreso tra 1 e 20. Il valore predefinito è 3.
  • RUNNING_THREADS_THRESHOLD: per le istanze principali, il numero minimo di thread attivi considerati al di sopra della soglia. Ad esempio, 10. Deve essere maggiore o uguale a 10. Se non viene impostato, il valore predefinito si basa sulle dimensioni dell'istanza. Il valore predefinito è MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: per le repliche di lettura, il ritardo di replica minimo, in secondi, considerato superiore alla soglia. Deve essere maggiore di 0. Il valore predefinito è 900.
  • TRANSACTION_DURATION_THRESHOLD: la durata, in secondi, di una transazione non eseguita prima che venga monitorata e inclusa in un log di acquisizione del rendimento. Ad esempio, 300, 600. Il valore minimo è 60. Il valore predefinito è 3600.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Aggiornare un'istanza esistente

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PERFORMANCE_CAPTURE_ENABLE: impostato su true per abilitare l'acquisizione delle prestazioni per l'istanza.
  • PROBING_INTERVAL_SECONDS: un numero intero compreso tra 20 e 86400. L'intervallo di tempo, in secondi, tra i probe delle metriche. Il valore predefinito è 30.
  • PROBE_THRESHOLD: il numero di volte consecutive in cui una soglia deve essere superata per attivare un'acquisizione del rendimento. L'intervallo valido è compreso tra 1 e 20. Il valore predefinito è 3.
  • RUNNING_THREADS_THRESHOLD: per le istanze principali, il numero minimo di thread attivi considerati al di sopra della soglia. Ad esempio, 10. Deve essere maggiore o uguale a 10. Se non viene impostato, il valore predefinito si basa sulle dimensioni dell'istanza. Il valore predefinito è MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: per le repliche di lettura, il ritardo di replica minimo, in secondi, considerato superiore alla soglia. Deve essere maggiore di 0. Il valore predefinito è 900.
  • TRANSACTION_DURATION_THRESHOLD: la durata, in secondi, di una transazione non eseguita prima che venga monitorata e inclusa in un log di acquisizione del rendimento. Ad esempio, 300, 600. Il valore minimo è 60. Il valore predefinito è 3600.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Disattivare l'acquisizione delle prestazioni

Per disattivare l'acquisizione delle prestazioni, utilizza il seguente comando.

gcloud

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

Sostituisci INSTANCE_NAME con il nome dell'istanza in cui vuoi disattivare l'acquisizione delle prestazioni.

REST v1

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Passaggi successivi