자바용 Cloud Debugger 설정

개요

이 페이지에서는 Cloud Debugger를 사용하도록 환경과 자바 애플리케이션을 구성하는 방법을 설명합니다. 일부 환경에서는 Cloud Debugger 에이전트가 데이터를 전송할 수 있도록 액세스 범위를 명시적으로 지정해야 합니다. 가능한 최대 액세스 범위를 설정한 다음 ID 및 액세스 관리를 사용해 액세스를 제한하는 방법을 권장합니다. 이 권장사항에 따라 액세스 범위가 cloud-platform 옵션이 있는 모든 Cloud API가 되도록 설정합니다.

언어 버전 및 컴퓨팅 환경

다음 컴퓨팅 환경에서 Cloud Debugger는 자바 버전 7, 8, 9, 11에서 사용할 수 있습니다.

App Engine 표준 환경 App Engine 가변형 환경 Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos on Google Cloud 다른 곳에서 실행 중인 VM 및 컨테이너 Cloud 함수

Cloud Debugger 설정

Cloud Debugger를 설정하려면 다음 작업을 완료해야 합니다.

  1. 프로젝트에 Cloud Debugger API가 사용 설정되어 있는지 확인합니다.

  2. 사용 중인 컴퓨팅 환경에 Debugger를 설치하고 구성합니다.

  3. 소스 코드를 선택합니다.

Cloud Debugger API 사용 설정 확인

Cloud Debugger를 사용하려면 Cloud Debugger API가 사용 설정되었는지 확인합니다. Cloud Debugger는 대부분의 프로젝트에서 기본으로 사용 설정됩니다.
Cloud Debugger API 사용 설정

카나리아 스냅샷 및 로그 지점

자바용 Debugger 에이전트는 스냅샷 또는 로그 지점을 설정할 때마다 카나리아 스냅샷과 로그 지점을 사용할 수 있습니다.

Debugger 에이전트는 스냅샷 또는 로그 지점을 적용할 때 전체 작업을 중단시킬 수 있는 Debugger 에이전트의 잠재적 버그로부터 대규모 작업을 보호하기 위해 스냅샷 및 로그 지점을 카나리아로 저장합니다.

이를 완화하기 위해 Debugger는 설정될 때마다 실행 중인 인스턴스의 하위 집합에서 스냅샷 및 로그 지점을 카나리아로 저장합니다. Debugger가 스냅샷 또는 로그 지점이 실행 중인 인스턴스에 부정적인 영향을 미치지 않는 경우 Debugger는 스냅샷 또는 로그 지점을 모든 인스턴스에 적용합니다.

카나리아 모드에서 Debugger를 사용하는 방법을 알아보려면 디버그 스냅샷디버그 로그 지점 페이지로 이동하세요.

카나리아 스냅샷 및 로그 지점 사용 설정

최신 버전의 Debugger 에이전트를 설치할 때 카나리아를 사용 또는 사용 중지할 수 있습니다. 카나리아는 기본으로 사용 중지됩니다.

카나리아 스냅샷 및 로그 지점을 사용 설정해야하는 경우

배포 및 프로덕션에 중요한 워크로드를 보호하려면 이러한 워크로드를 디버깅할 때 카나리아를 사용 설정하세요.

단일 인스턴스가 있는 경우에도 카나리아가 사용 설정된 상태에서 디버깅할 수 있지만 스냅샷 또는 로그 지점을 카나리아 없이 실행합니다.

카나리아 스냅샷 및 로그 지점을 사용 설정하지 말아야 하는 경우

실행 시간이 40초 미만인 워크로드(예시: Cloud Functions를 사용하는 작업)에서는 카나리아를 사용 설정하지 마세요.

더 빠른 스냅샷 트리거를 원하는 경우 카나리아를 사용 설정하지 마세요.

카나리아 스냅샷과 로그 지점을 제외한 Debugger 에이전트를 구성하려면 사용 중인 Google Cloud Platform의 설치 안내로 이동하세요.

App Engine 표준 환경

디버거는 기본적으로 사용 설정되며 구성할 필요가 없습니다. Cloud Console의 디버그 페이지에서 앱을 빌드하는 데 사용되는 자바 소스 파일이 표시됩니다.

자세한 내용은 소스 코드 자동으로 선택을 참조하세요.

App Engine 가변형 환경

Debugger는 자바 런타임에 기본적으로 사용 설정되며 구성할 필요가 없습니다. Cloud Console의 디버그 페이지에서 앱을 빌드하는 데 사용되는 자바 소스 파일이 표시됩니다.

Debugger는 기본적으로 자바용 Google 제공 기본 이미지를 사용하는 커스텀 런타임에 포함됩니다. 기본 진입점이 사용된 경우 구성할 필요가 없습니다. Cloud Console의 디버그 페이지에서 앱을 빌드하는 데 사용되는 자바 소스 파일이 표시됩니다.

다른 기본 이미지를 사용하여 빌드된 커스텀 런타임으로 Cloud Debugger를 사용하려면 Compute Engine 설정 안내를 따르세요.

자세한 내용은 소스 코드 자동으로 선택을 참조하세요.

Google Kubernetes Engine

GCLOUD

gcloud를 사용하여 Debugger를 사용 설정하려면 다음 단계를 완료하세요.

  1. 다음 액세스 범위 중 하나를 사용하여 클러스터를 만듭니다.

    • https://www.googleapis.com/auth/cloud-platform: 클러스터에 모든 Google Cloud API에 대한 액세스 권한이 부여됩니다.

    • https://www.googleapis.com/auth/cloud_debugger: 클러스터에 Debugger API에 대한 액세스 권한만 부여됩니다. 클러스터의 보안을 강화하려면 이 액세스 범위를 사용하세요.

    gcloud container clusters create example-cluster-name \
           --scopes=https://www.googleapis.com/auth/cloud_debugger
    
  2. Dockerfile에 다음 줄을 추가하여 Debugger 에이전트를 컨테이너식 앱에 추가하고 앱이 배포되면 초기화합니다.

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
    RUN mkdir /opt/cdbg && \
         wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
         tar xvz -C /opt/cdbg
    

    이전 버전의 에이전트를 설치하려면 URL을 다음 값으로 변경합니다.

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    VERSION_NUMBER를 사용할 에이전트 버전으로 바꿉니다(예: https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz). 카나리아는 2.25 이전 버전에서 사용할 수 없습니다. Debugger 에이전트의 버전을 가져오려면 자바 에이전트에 대한 GitHub 페이지로 이동합니다.

  3. Dockerfile에 다음 줄을 추가하여 Debugger 에이전트를 실행합니다.

    카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

    # Start the agent when the app is deployed.
    RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
        -Dcom.google.cdbg.module=MODULE \
        -Dcom.google.cdbg.version=VERSION \
        -Dcom.google.cdbg.breakpoints.enable_canary=true \
        -jar PATH_TO_JAR_FILE
    

    카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

    -Dcom.google.cdbg.breakpoints.enable_canary=false
    

    다음과 같이 명령어의 자리표시자를 교체합니다.

    • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

    • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

    • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

이제 Debugger를 컨테이너식 앱을 배포할 때 사용할 수 있습니다.

Cloud Console의 디버그 페이지에 배포된 앱과 일치하는 소스 코드가 자동으로 표시되도록 하려면 소스 코드 자동으로 선택을 참조하세요.

콘솔

Google Cloud Console을 사용하여 Debugger를 사용 설정하려면 다음 단계를 완료하세요.

  1. 노드 풀 섹션에서 보안을 선택한 다음 각 API에 액세스 설정을 선택합니다.

  2. Debugger를 사용 설정합니다.

    클러스터에 Debugger API가 사용 설정되었습니다.

  3. 선택사항: 모든 Cloud API에 전체 액세스 허용을 선택합니다.

  4. Dockerfile에 다음 줄을 추가하여 Debugger 에이전트를 실행합니다.

    카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

    # Start the agent when the app is deployed.
    RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
        -Dcom.google.cdbg.module=MODULE \
        -Dcom.google.cdbg.version=VERSION \
        -Dcom.google.cdbg.breakpoints.enable_canary=true \
        -jar PATH_TO_JAR_FILE
    

    카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

    -Dcom.google.cdbg.breakpoints.enable_canary=false
    

    다음과 같이 명령어의 자리표시자를 교체합니다.

    • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

    • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

    • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

이제 Debugger를 컨테이너식 앱을 배포할 때 사용할 수 있습니다.

Cloud Console의 디버그 페이지에 배포된 앱과 일치하는 소스 코드가 자동으로 표시되도록 하려면 소스 코드 자동으로 선택을 참조하세요.

Compute Engine

Cloud Debugger는 Google Compute Engine 인스턴스에서 실행되는 모든 자바 앱과 함께 사용할 수 있습니다. 앱에서 실행 중인 모든 인스턴스에 Debugger를 사용 설정하는 것이 좋습니다.

  1. Compute Engine VM 인스턴스가 실행 중인지 확인합니다.

    • 64비트 Debian Linux 이미지
    • 자바 JDK 버전 7, 8, 9
  2. Compute Engine VM 인스턴스가 액세스 범위의 선택사항인 모든 Cloud APIs에 대한 전체 액세스 허용으로 만들어졌거나 다음 액세스 범위 중 하나인지 확인합니다.

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  3. 기본 제공 에이전트 패키지를 다운로드합니다.

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
    sudo mkdir /opt/cdbg
         wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
         tar xvz -C /opt/cdbg
    

    이전 버전의 에이전트를 설치하려면 URL을 다음 값으로 변경합니다.

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    VERSION_NUMBER를 사용할 에이전트 버전으로 바꿉니다(예: https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz). 카나리아는 2.25 이전 버전에서 사용할 수 없습니다. Debugger 에이전트의 버전을 가져오려면 자바 에이전트에 대한 GitHub 페이지로 이동합니다.

  4. 자바 호출에 에이전트를 추가합니다.
    (Tomcat 또는 Jetty를 사용하는 경우 웹 서버 섹션을 참조하세요.)

    카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

    # Start the agent when the app is deployed.
    java -agentpath:/opt/cdbg/cdbg_java_agent.so \
        -Dcom.google.cdbg.module=MODULE \
        -Dcom.google.cdbg.version=VERSION \
        -Dcom.google.cdbg.breakpoints.enable_canary=true \
        -jar PATH_TO_JAR_FILE
    

    카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

    -Dcom.google.cdbg.breakpoints.enable_canary=false
    

    다음과 같이 명령어의 자리표시자를 교체합니다.

    • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

    • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

    • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

이제 디버거를 앱에서 사용할 수 있습니다.

Cloud Console의 디버그 페이지에 배포된 앱과 일치하는 소스 코드가 자동으로 표시되도록 하려면 소스 코드 자동으로 선택을 참조하세요.

웹 서버

자바 웹 서버는 일반적으로 부트스트랩 프로세스를 통해 시작되며 각 웹 서버에는 자바 옵션을 맞춤설정하는 고유한 방법이 있습니다.

Tomcat

/etc/default/tomcat7 또는 /etc/default/tomcat8에 다음 줄을 추가합니다.

카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

# Start the agent when the app is deployed.
JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true"

카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

-Dcom.google.cdbg.breakpoints.enable_canary=false

다음과 같이 명령어의 자리표시자를 교체합니다.

  • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

  • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

  • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

Docker 컨테이너에서 Tomcat을 실행하는 경우 다음 줄을 대신 DockerfileDockerfile에 추가합니다.

카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

# Start the agent when the app is deployed.
ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true

카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

-Dcom.google.cdbg.breakpoints.enable_canary=false

다음과 같이 명령어의 자리표시자를 교체합니다.

  • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

  • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

  • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

Jetty

/var/lib/jetty/start.d에 다음 줄을 추가합니다.

카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so \
-Dcom.google.cdbg.module=MODULE \
-Dcom.google.cdbg.version=VERSION \
-Dcom.google.cdbg.breakpoints.enable_canary=true

카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

-Dcom.google.cdbg.breakpoints.enable_canary=false

다음과 같이 명령어의 자리표시자를 교체합니다.

  • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

  • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

  • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

Google Cloud에서 Cloud Run 및 Cloud Run for Anthos 실행

  1. Debugger 에이전트를 설치할 디렉터리를 생성하려면 Dockerfile에 다음 명령어를 추가하고 Debugger 에이전트 보관 파일을 다운로드하고 설치 디렉터리에 압축을 풉니다.

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
    RUN mkdir /opt/cdbg && \
         wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
         tar xvz -C /opt/cdbg
    

    이전 버전의 에이전트를 설치하려면 URL을 다음 값으로 변경합니다.

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    VERSION_NUMBER를 사용할 에이전트 버전으로 바꿉니다(예: https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz). 카나리아는 2.25 이전 버전에서 사용할 수 없습니다. Debugger 에이전트의 버전을 가져오려면 자바 에이전트에 대한 GitHub 페이지로 이동합니다.

    자바 호출을 찾아 다음 플래그를 추가하여 Debugger 에이전트를 초기화합니다.

    카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

    # Start the agent when the app is deployed.
    RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
        -Dcom.google.cdbg.breakpoints.enable_canary=true \
        -jar PATH_TO_JAR_FILE
    

    카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

    -Dcom.google.cdbg.breakpoints.enable_canary=false
    

    다음과 같이 명령어의 자리표시자를 교체합니다.

    • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

디버그 페이지에서 소스 코드의 위치를 선택합니다. Cloud Console의 디버그 페이지에 배포된 앱과 일치하는 소스 코드가 자동으로 표시되도록 하려면 소스 코드 자동으로 선택을 참조하세요.

이제 Debugger를 사용할 수 있습니다.

로컬 및 기타 위치

  1. Debugger 기본 제공 에이전트 패키지를 다운로드합니다.

    mkdir /opt/cdbg
    wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_service_account.tar.gz | \
        tar xvz -C /opt/cdbg
    
  2. 서비스 계정 사용자 인증 정보를 다운로드합니다.
    Google Cloud에서 호스팅하지 않는 머신에서 자바용 Cloud Debugger 에이전트를 사용하려면 에이전트가 Google Cloud 서비스 계정 사용자 인증 정보를 사용하여 Cloud Debugger 서비스로 인증해야 합니다.

    Cloud Console 서비스 계정 페이지에서 기존 또는 새 서비스 계정의 사용자 인증 정보 파일을 만듭니다. 서비스 계정에는 Cloud Debugger Agent 이상의 역할이 있어야 합니다.

    자바용 Cloud Debugger 에이전트와 함께 서비스 계정 JSON 파일을 배치합니다.

  3. 에이전트를 자바 호출에 추가합니다.

    카나리아를 사용 설정한 상태에서 디버그하려면 다음 단계를 따르세요.

    java -agentpath:/opt/cdbg/cdbg_java_agent.so \
      -Dcom.google.cdbg.module=MODULE \
      -Dcom.google.cdbg.version=VERSION \
      -Dcom.google.cdbg.breakpoints.enable_canary=true \
      -Dcom.google.cdbg.auth.serviceaccount.enable=true \
      -Dcom.google.cdbg.auth.serviceaccount.jsonfile=/opt/cdbg/gcp-svc.json \
      -jar PATH_TO_JAR_FILE
    

    카나리아를 사용 설정하지 않은 상태에서 디버깅하려면 enable_canary 플래그를 false로 설정합니다.

    -Dcom.google.cdbg.breakpoints.enable_canary=false
    

    다음과 같이 명령어의 자리표시자를 교체합니다.

    • PATH_TO_JAR_FILE은 앱의 JAR 파일에 대한 상대 경로입니다. 예를 들면 ~/myapp.jar입니다.

    • MODULE은 앱의 이름입니다. 이 이름을 버전과 함께 사용하여 Cloud Console에서 앱을 식별합니다. 예를 들면 MyApp, Backend 또는 Frontend입니다.

    • VERSION은 앱 버전입니다(예: 빌드 ID). Cloud Console에는 실행 중인 앱이 MODULE - VERSION으로 표시됩니다. 예를 들면 v1.0, build_147 또는 v20160520입니다.

    • auth.serviceaccount.jsonfile 시스템 속성을 추가하는 대신 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용할 수 있습니다.

이제 디버거를 앱에서 사용할 수 있습니다.

Cloud Console의 디버그 페이지에는 로컬 소스 파일을 업로드하는 대신 로컬 개발용으로 표시할 수 있습니다. 소스 코드 수동으로 선택을 참조하세요.