성능 캡처 구성

성능 캡처를 사용하면 성능이 저하될 때 인스턴스의 세부 측정항목을 캡처하여 데이터베이스의 일시적인 문제를 진단할 수 있습니다. 성능 캡처를 사용하려면 인스턴스에 성능 캡처를 사용 설정하고 Cloud SQL 인스턴스의 세부 측정항목 기반 스냅샷을 트리거하는 기준점을 구성합니다.

시작하기 전에

성능 캡처를 사용하려면 인스턴스에 쿼리 통계를 사용 설정해야 합니다.

필요한 역할

인스턴스를 만들고 성능 캡처를 사용 설정하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 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를 다음 플래그 설정 중 하나 이상으로 바꿀 수 있습니다. 플래그 값을 설정하지 않으면 모니터링 에이전트에서 기준점의 기본값을 사용합니다.

  • 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_0입니다.
  • 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_0입니다.
  • 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"
}

다음 단계