디버그 스냅샷

앱을 배포하거나 시작한 후 Google Cloud Console에서 Cloud Debugger를 열 수 있습니다. Debugger를 사용하면 앱을 중지하거나 속도를 저하시키지 않고도 앱의 호출 스택 및 로컬 변수를 캡처하고 검사할 수 있습니다.

Debugger를 사용하려면 Cloud Console의 디버그 페이지로 이동하세요.

시작하기 전에

Debugger는 앱 소스 코드의 액세스 권한에 관계없이 사용할 수 있습니다. 소스 코드를 사용할 수 없는 경우 파일 이름과 줄 번호를 수동으로 입력하는 방법은 아래의 디버그 스냅샷 만들기를 참조하세요.

로컬 또는 Git 저장소에 저장된 소스 코드에 액세스하려면 소스 코드 위치를 선택해야 할 수 있습니다.

스냅샷

스냅샷은 앱의 소스 코드에서 특정 줄 위치에 있는 로컬 변수 및 호출 스택을 캡처합니다. 특정 조건 및 위치를 지정하여 앱 데이터의 스냅샷을 반환하고 자세히 확인하여 앱을 디버그할 수 있습니다.

카나리아가 포함된 Debugger 에이전트

스냅샷을 설정하면 Debugger 에이전트가 인스턴스 하위 집합에서 스냅샷을 테스트합니다. Debugger 에이전트가 스냅샷이 성공적으로 실행될 수 있는지 확인하면 스냅샷이 모든 인스턴스에 적용됩니다. 이 과정은 약 40초 정도 걸립니다.

이 프로세스 이후 스냅샷이 트리거되면 변수호출 스택 창에 결과가 표시됩니다. 스냅샷이 설정된 후 40초 이내에 트리거되면 카나리아 스냅샷이 적용된 인스턴스의 결과가 표시됩니다.

Debugger 에이전트는 데이터를 캡처할 때 발생하는 지연 시간을 최소화하기 위한 몇 가지 전략을 구현합니다.

Debugger 에이전트가 카나리아를 실행하는 동안 다음이 표시됩니다.

Debugger 에이전트가 인스턴스 카나리아

카나리아 모드에서 Debugger 에이전트가 실패하는 경우 수행할 작업을 알아 보려면 디버그 스냅샷 페이지의 문제 해결 섹션으로 이동하세요.

어떤 Debugger 에이전트 버전에 카나리아 기능이 있는지 알아보려면 언어별 페이지를 참조하세요.

카나리아가 없는 Debugger 에이전트

카나리아 없이 Debugger 에이전트를 사용하고 스냅샷을 설정하면 실행 중인 모든 앱 인스턴스에 적용됩니다. 인스턴스가 스냅샷 위치에서 처음으로 코드를 실행하면 Debugger 에이전트가 스냅샷을 만들어 볼 수 있게 제공합니다. Debugger 에이전트는 데이터를 캡처할 때 발생하는 지연 시간을 최소화하기 위한 몇 가지 전략을 구현합니다.

디버그 스냅샷 만들기

Console

소스 코드 줄 번호를 클릭하여 해당 위치에서 스냅샷을 만듭니다.

  1. 스냅샷 패널이 오른쪽 패널에서 선택되어 있는지 확인합니다.
  2. 왼쪽 패널에서 확인할 소스 코드가 포함된 파일을 선택합니다. 선택한 파일의 콘텐츠가 가운데 패널에 표시됩니다.
  3. 소스 코드 위치의 줄 번호를 클릭합니다.

스냅샷 위치 찾아보기

여러 줄을 클릭하면 한 파일에 둘 이상의 스냅샷 위치를 설정할 수 있습니다.

Debugger에서 소스 코드를 로드하는 다른 방법은 소스 코드 옵션 섹션을 참조하세요.

사용할 수 있는 소스 코드가 없는 경우 스냅샷 패널에 스냅샷을 만들 파일 이름:줄을 수동으로 입력할 수 있습니다.

스냅샷 위치 수동으로 설정

gcloud

명령줄에서 스냅샷 위치를 설정하려면 다음 명령어를 입력합니다.

gcloud debug snapshots create LOCATION

각 항목의 의미는 다음과 같습니다.

  • LOCATION은 스냅샷을 설정할 파일 이름과 줄입니다. 형식은 FILE:LINE입니다. 여기서 FILE은 파일 이름 또는 이름이 같은 다른 파일이 있을 경우, 구분하기 위한 경로 구성요소가 앞에 있는 파일 이름입니다. 디버그 대상에 고유하지 않은 파일 이름이 지정되면 오류가 발생합니다.

스냅샷 조건(선택사항)

스냅샷 조건은 앱 언어(자바, Python, Go가 지원됨)로 작성된 간단한 표현식이며 스냅샷을 만들려면 이 조건이 true로 평가되어야 합니다. 스냅샷 조건은 true로 평가될 때까지 또는 스냅샷 제한 시간이 만료될 때까지 모든 인스턴스에서 줄이 실행될 때마다 평가됩니다.

스냅샷 조건 사용은 선택사항입니다.

조건은 논리 연산자를 포함할 수 있는 완전한 부울 표현식입니다.

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

Console

조건을 지정하려면 스냅샷 패널의 조건 필드에 조건을 입력합니다.

스냅샷 조건 설정

gcloud

snapshots create--condition 플래그를 사용하여 조건을 다음과 같이 지정합니다.

gcloud debug snapshots create LOCATION --condition="ultimateAnswer <= 42 && foo==bar"

다음 언어 기능을 사용하여 조건을 표현할 수 있습니다.

자바

다음을 포함한 대부분의 자바 표현식이 지원됩니다.
  • 로컬 변수: a == 8
  • 숫자 및 부울 연산: x + y < 20
  • 인스턴스 및 정적 필드: this.counter == 20, this.myObj.isShutdown, myStatic 또는 com.mycompany.MyClass.staticMember
  • 등호 연산자가 포함된 문자열 비교: myString == "abc"
  • 함수 호출. 읽기 전용 함수만 사용할 수 있습니다. 예를 들어 StringBuilder.indexOf()는 지원되지만 StringBuilder.append()는 지원되지 않습니다.
  • 정규화된 유형으로 유형 변환: ((com.myprod.ClassImpl) myInterface).internalField

다음 언어 기능은 지원되지 않습니다.

  • Integer와 같은 unboxing 숫자 유형. 대신 myInteger.value를 사용하세요.

Python

다음을 포함한 대부분의 Python 표현식이 지원됩니다.
  • 로컬 및 전역 변수 읽기
  • 배열, 목록, 슬라이스, 사전, 객체에서 읽기
  • 단순 메소드 호출

다음 언어 기능은 지원되지 않습니다.

  • 새 객체를 할당하거나 복잡한 구조를 사용하는 함수 호출
  • 표현식 내부에 새 객체 만들기

Go

다음을 포함한 대부분의 Go 표현식 구문이 지원됩니다.
  • 로컬 및 전역 변수 읽기
  • 배열, 슬라이스, 맵, 구조체에서 읽기

다음 언어 기능은 지원되지 않습니다.

  • 인터페이스 값에서 읽기
  • 유형 변환 및 복합 리터럴
  • len 이외의 함수 호출

표현식(선택사항)

Debugger의 표현식 기능을 사용하면 스냅샷을 만들 때 복잡한 표현식을 평가하거나 객체 계층 구조를 순회할 수 있습니다. 표현식은 위에서 설명한 스냅샷 조건과 동일한 언어 기능을 지원합니다.

표현식 사용은 선택사항입니다.

표현식의 일반적인 용도는 다음과 같습니다.

  • 로컬 변수 집합에 포함되지 않은 정적 또는 전역 변수 보기
  • 매번 Debugger 패널에서 로컬 변수를 펼치지 않고 여러 겹으로 중첩된 구성원 변수를 쉽게 보기
  • 반복적인 수학 계산 방지. 예를 들어 (endTimeMillis - startTimeMillis) / 1000.0을 사용하여 기간을 초 단위로 계산합니다.

표현식을 추가하는 방법은 다음과 같습니다.

Console

  1. 표현식 필드에서 표현식을 입력합니다. 표현식을 더 추가하려면 Tab 키를 누르세요.
  2. Enter 키 또는 스냅샷 버튼 스냅샷 버튼을 누릅니다.

스냅샷이 만들어질 때 표현식 결과가 표시됩니다.

표현식 설정

gcloud

snapshots create--expression 플래그를 사용하여 표현식을 다음과 같이 정의합니다.

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

스냅샷 보기

Console

앱이 지정된 위치에서 소스 코드를 실행하면 스냅샷 데이터가 Debugger에 나타납니다. 인스턴스 변수 및 로컬 변수는 패널의 변수 섹션에 나타납니다. 스택 추적은 패널의 호출 스택 섹션에 나타납니다.

스냅샷 보기

스냅샷이 만들어진 시점의 로컬 변수 값을 확인하고 세부 데이터 구조를 자세히 살펴볼 수 있습니다. 또한 호출 스택 프레임을 클릭하면 스택의 해당 수준에서 로컬 변수를 확인할 수 있습니다.

파일에서 여러 스냅샷 위치를 설정했거나 이미 만든 스냅샷을 보려면 스냅샷 기록 패널을 펼칩니다.

gcloud

명령줄에서 스냅샷의 Cloud Console URL을 검색하려면 다음 명령어를 입력합니다.

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE  HighScoreService.java:105                             53bd97d4-b6c6-74fc  https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

Cloud Console에서 스냅샷을 보려면 VIEW 열의 값을 복사하여 브라우저에 붙여넣습니다.

명령줄에서 자세한 스냅샷 데이터를 보려면 다음 명령어를 입력합니다.

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

describe 명령어는 스택 추적 및 로컬 변수 값을 반환하며 주로 사람이 아닌 머신이 읽을 수 있는 형식으로 반환합니다.

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

스냅샷 다시 만들기

스냅샷은 한 번만 만들어집니다. 같은 위치에 앱 데이터의 스냅샷을 하나 더 캡처하려면 수동으로 다시 만들면 됩니다.

Console

스냅샷을 다시 만들려면 스냅샷 패널의 오른쪽 상단에 있는 카메라 아이콘을 클릭합니다.

스냅샷 버튼

그러면 새 스냅샷이 스냅샷 기록 패널에 추가됩니다. 해당 줄의 이전 스냅샷은 스냅샷 기록 또는 해당 줄 번호의 마커에서 액세스할 수 있습니다.

줄 마커에 표시된 이전 스냅샷

gcloud

명령줄에서 스냅샷을 다시 만들려면 원래 사용한 create 명령어를 반복합니다.

gcloud debug snapshots create LOCATION

스냅샷 위치 삭제

Console

스냅샷 마커에서 X를 클릭하여 스냅샷 위치를 삭제합니다.

스냅샷 아이콘

gcloud

명령줄에서 스냅샷을 삭제하려면 다음 명령어를 입력합니다.

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

각 항목의 의미는 다음과 같습니다.

  • IDgcloud debug snapshots list에서 반환된 값입니다.

  • LOCATION-REGEXP는 스냅샷의 코드 위치를 정의하는 정규 표현식입니다.

스냅샷 공유

브라우저 또는 gcloud debug snapshots list 명령어의 출력에서 스냅샷 URL을 복사하고 프로젝트에 액세스 권한이 있는 다른 사용자에게 제공하여 다른 프로젝트 구성원과 스냅샷을 공유할 수 있습니다. 나중에 참조할 수 있도록 이 URL을 저장하고 다시 돌아와 결과를 볼 수도 있습니다. Debugger는 만들어지는 스냅샷마다 새 URL을 사용합니다. 즉, 코드의 같은 위치에서 캡처되었어도 별개의 조합으로 공유할 수 있습니다. 공유는 스냅샷을 만든 후 30일이 지나면 만료됩니다.

문제 해결

Debugger 에이전트가 인스턴스를 비정상 종료했나요?

Debugger 에이전트에 결함이 있는 경우 다음 오류가 표시될 수 있습니다.

변수 창에 오류 메시지가 표시됨

다음과 같은 이유로 Debugger 에이전트가 보호 장치를 트리거한 것처럼 표시되도록 거짓양성을 얻을 수 있습니다.

  • Debugger 에이전트가 카나리아를 수행하는 동안 인스턴스가 종료되었습니다.

    카나리아 스냅샷이 적용된 인스턴스가 종료되면 Debugger 에이전트가 인스턴스를 종료한 것처럼 보입니다. 스냅샷이 설정된 후 40초 이내에 종료된 인스턴스가 없는지 확인합니다. 예를 들어 Cloud Run 및 App Engine의 자동 확장이나 새 코드 배포로 인해 인스턴스가 종료될 수 있습니다.

인스턴스에서 Debugger 에이전트를 삭제하고 이전 버전을 다시 설치해야 합니다. 이전 버전을 다시 설치하려면 Debugger 에이전트의 이전 버전 설치 설정 안내를 따르세요.

이전 버전의 에이전트에서 문제가 지속되면 거짓양성이 아닌지 확인한 다음 Debugger 에이전트를 사용 중지하고 의견을 보냅니다.