Configurar a captura de performance

Com a captura de desempenho, é possível diagnosticar problemas temporários no banco de dados capturando métricas detalhadas da instância quando o desempenho está degradado. Para usar a captura de performance, ative-a na sua instância e configure os limites que acionam os snapshots detalhados baseados em métricas da instância do Cloud SQL.

Antes de começar

Para usar a captura de desempenho, ative os insights de consulta na sua instância.

Funções exigidas

Para receber as permissões necessárias para criar uma instância e ativar a captura de desempenho, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar e configurar a captura de performance

É possível ativar a captura de desempenho ao criar ou atualizar sua instância do Cloud SQL.

gcloud

Criar e configurar uma instância

Para ativar a captura de desempenho ao criar a instância do Cloud SQL, execute o seguinte 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"

Substitua:

  • INSTANCE_NAME: o nome da instância
  • DATABASE_VERSION: a versão do banco de dados. Por exemplo, MYSQL_8_4 ou MYSQL_8_0_37. Se você não especificar uma versão do banco de dados, a versão padrão será MYSQL_8_0.
  • REGION: a região
  • TIER: o tipo de máquina
  • EDITION_TYPE: sua edição do Cloud SQL

Para a sinalização performance-capture-config, inclua enabled=true. Na mesma definição de flag, é possível especificar configurações opcionais para PROBE_CONFIGURATION e PERFORMANCE_CAPTURE_THRESHOLDS ou atualizar a instância mais tarde.

Exemplo:

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"

Atualizar uma instância

Para ativar a captura de desempenho em uma instância do Cloud SQL, execute o seguinte comando:

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

Para a sinalização performance-capture-config, inclua enabled=true. Para a mesma flag, é possível especificar configurações opcionais para PROBE_CONFIGURATION e para PERFORMANCE_CAPTURE_THRESHOLDS.

Também é possível usar o comando gcloud beta sql instances patch para atualizar os valores de configuração de limite para captura de desempenho em uma instância atual.

Configurar o intervalo de sondagem e as sondagens consecutivas de métricas de desempenho

Você pode substituir PROBE_CONFIGURATION por uma ou ambas as configurações de flag a seguir. Se você não definir as flags, o agente de monitoramento usará o valor padrão.

  • probing-interval-seconds=SECONDS: um número inteiro entre 20 e 86400. O intervalo de tempo, em segundos, entre as sondagens de métricas. Por exemplo, 30, 60, 100. O padrão é 30.
  • probe-threshold=PROBES: o número de vezes consecutivas que um limite precisa ser excedido para acionar uma captura de desempenho. O intervalo válido é de 1 a 20. O padrão é 3.

Configurar limites de captura de performance

Substitua PERFORMANCE_CAPTURE_THRESHOLDS por uma ou mais das seguintes configurações de flag. Se você não definir valores para as flags, o agente de monitoramento vai usar os valores padrão para os limites.

  • running-threads-threshold=THREADS: para instâncias principais, o número mínimo de threads ativas consideradas acima do limite. Por exemplo, 10. Precisa ser maior ou igual a 10. Se não for definido, o padrão será baseado no tamanho da instância. O padrão é MIN(600, cpuCount * 20).
  • seconds-behind-source-threshold=SECONDS : para réplicas de leitura, o atraso mínimo de replicação, em segundos, considerado acima do limite. Precisa ser maior que 0. O padrão é 900.
  • transaction-duration-threshold=SECONDS: a duração, em segundos, de uma transação não confirmada antes de ser rastreada e incluída em um registro de captura de desempenho. Por exemplo: 300 e 600. O valor mínimo é 60 O padrão é 3600.

REST v1

Criar e configurar uma instância

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: ID do projeto;
  • INSTANCE_ID: o ID da sua instância
  • DATABASE_VERSION: a versão do banco de dados. Por exemplo, MYSQL_8_4 ou MYSQL_8_0_37. Se você não especificar uma versão do banco de dados, a versão padrão será MYSQL_8_0.
  • REGION: a região
  • MACHINE_TYPE: o tipo de máquina
  • EDITION_TYPE: sua edição do Cloud SQL
  • PROBING_INTERVAL_SECONDS: um número inteiro entre 20 e 86400. O intervalo de tempo, em segundos, entre as sondagens de métricas. O padrão é 30.
  • PROBE_THRESHOLD: o número de vezes consecutivas que um limite precisa ser excedido para acionar uma captura de desempenho. O intervalo válido é de 1 a 20. O padrão é 3.
  • RUNNING_THREADS_THRESHOLD: para instâncias principais, o número mínimo de threads ativas consideradas acima do limite. Por exemplo, 10. Precisa ser maior ou igual a 10. Se não for definido, o padrão será baseado no tamanho da instância. O padrão é MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: para réplicas de leitura, o atraso mínimo de replicação, em segundos, considerado acima do limite. Precisa ser maior que 0. O padrão é 900.
  • TRANSACTION_DURATION_THRESHOLD: a duração, em segundos, de uma transação não confirmada antes de ser rastreada e incluída em um registro de captura de desempenho. Por exemplo: 300 e 600. O valor mínimo é 60 O padrão é 3600.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Atualizar uma instância

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PERFORMANCE_CAPTURE_ENABLE: defina como true para ativar a captura de desempenho na instância.
  • PROBING_INTERVAL_SECONDS: um número inteiro entre 20 e 86400. O intervalo de tempo, em segundos, entre as sondagens de métricas. O padrão é 30.
  • PROBE_THRESHOLD: o número de vezes consecutivas que um limite precisa ser excedido para acionar uma captura de desempenho. O intervalo válido é de 1 a 20. O padrão é 3.
  • RUNNING_THREADS_THRESHOLD: para instâncias principais, o número mínimo de threads ativas consideradas acima do limite. Por exemplo, 10. Precisa ser maior ou igual a 10. Se não for definido, o padrão será baseado no tamanho da instância. O padrão é MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: para réplicas de leitura, o atraso mínimo de replicação, em segundos, considerado acima do limite. Precisa ser maior que 0. O padrão é 900.
  • TRANSACTION_DURATION_THRESHOLD: a duração, em segundos, de uma transação não confirmada antes de ser rastreada e incluída em um registro de captura de desempenho. Por exemplo: 300 e 600. O valor mínimo é 60 O padrão é 3600.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Criar e configurar uma instância

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: ID do projeto;
  • INSTANCE_ID: o ID da sua instância
  • DATABASE_VERSION: a versão do banco de dados. Por exemplo, MYSQL_8_4 ou MYSQL_8_0_37. Se você não especificar uma versão do banco de dados, a versão padrão será MYSQL_8_0.
  • REGION: a região
  • MACHINE_TYPE: o tipo de máquina
  • EDITION_TYPE: sua edição do Cloud SQL
  • PROBING_INTERVAL_SECONDS: um número inteiro entre 20 e 86400. O intervalo de tempo, em segundos, entre as sondagens de métricas. O padrão é 30.
  • PROBE_THRESHOLD: o número de vezes consecutivas que um limite precisa ser excedido para acionar uma captura de desempenho. O intervalo válido é de 1 a 20. O padrão é 3.
  • RUNNING_THREADS_THRESHOLD: para instâncias principais, o número mínimo de threads ativas consideradas acima do limite. Por exemplo, 10. Precisa ser maior ou igual a 10. Se não for definido, o padrão será baseado no tamanho da instância. O padrão é MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: para réplicas de leitura, o atraso mínimo de replicação, em segundos, considerado acima do limite. Precisa ser maior que 0. O padrão é 900.
  • TRANSACTION_DURATION_THRESHOLD: a duração, em segundos, de uma transação não confirmada antes de ser rastreada e incluída em um registro de captura de desempenho. Por exemplo: 300 e 600. O valor mínimo é 60 O padrão é 3600.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Atualizar uma instância

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PERFORMANCE_CAPTURE_ENABLE: defina como true para ativar a captura de desempenho na instância.
  • PROBING_INTERVAL_SECONDS: um número inteiro entre 20 e 86400. O intervalo de tempo, em segundos, entre as sondagens de métricas. O padrão é 30.
  • PROBE_THRESHOLD: o número de vezes consecutivas que um limite precisa ser excedido para acionar uma captura de desempenho. O intervalo válido é de 1 a 20. O padrão é 3.
  • RUNNING_THREADS_THRESHOLD: para instâncias principais, o número mínimo de threads ativas consideradas acima do limite. Por exemplo, 10. Precisa ser maior ou igual a 10. Se não for definido, o padrão será baseado no tamanho da instância. O padrão é MIN(600, cpuCount * 20).
  • SECONDS_BEHIND_SOURCE_THRESHOLD: para réplicas de leitura, o atraso mínimo de replicação, em segundos, considerado acima do limite. Precisa ser maior que 0. O padrão é 900.
  • TRANSACTION_DURATION_THRESHOLD: a duração, em segundos, de uma transação não confirmada antes de ser rastreada e incluída em um registro de captura de desempenho. Por exemplo: 300 e 600. O valor mínimo é 60 O padrão é 3600.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Desativar a captura de performance

Para desativar a captura de performance, use o seguinte comando:

gcloud

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

Substitua INSTANCE_NAME pelo nome da instância em que você quer desativar a captura de desempenho.

REST v1

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

A seguir