본문 바로가기
WIKI 기술 지식 베이스

라이브 디버거 (Live Debugger)

원문 보기 위키 갱신

⚠️ app.ddog-gov.com, us2.ddog-gov.com Datadog 사이트 사용자분들께 중요한 안내예요.

이 제품은 선택하신 Datadog 사이트({% placeholder "user-datadog-site-name" /%})에서 지원되지 않아요.

출처: 문서

본문

개요 (Overview)

Live Debugger를 사용하면 코드를 재배포하거나 실행을 중단하지 않고 실행 중인 서비스에서 애플리케이션 동작을 실시간으로 검사할 수 있어요.

임시 디버그 로그를 추가하거나 문제를 로컬에서 재현하는 대신, 코드의 특정 지점에서 애플리케이션 상태를 동적으로 캡처할 수 있어요. 여기에는 변수 값, 메서드 파라미터, 실행 컨텍스트가 포함돼요. Live Debugger는 프로덕션 또는 기타 장기 실행 환경에서 문제를 진단하는 데 아주 적합해요.

Live Debugger는 로그포인트(auto-expiring, non-breaking breakpoint)를 사용해 애플리케이션을 중단하지 않고 진단 데이터를 수집해요. 실행이 정상적으로 계속되므로 Live Debugger는 프로덕션 시스템에서 문제가 발생하는 즉시 조사하는 데 안전하게 사용할 수 있어요.

주요 기능 (Key capabilities)

Live Debugger는 다음을 제공해요:

  • 실행 중인 코드의 변수 값, 메서드 인자, 실행 컨텍스트에 대한 실시간 검사
  • 애플리케이션을 중단하거나 재배포를 요구하지 않고 디버깅 정보를 수집하는 안전하고 비침습적인 데이터 캡처
  • 코드베이스 어디에서나(서드파티 라이브러리 포함) 동적 로그포인트 배치
  • 구성 가능한 기간 후 자동으로 비활성화되는 자동 만료 로그포인트
  • 사용자 정의 표현식에 기반한 조건부 데이터 캡처 — 특정 조건이 충족될 때만 정보가 수집돼요
  • 개인 데이터, 비밀, 자격 증명 노출 방지를 돕는 내장 민감 데이터 스크러빙

요구 사항 (Requirements)

Java (Language is Java)

  • Datadog Java SDK, 버전 1.64.0 이상 강력 권장(JDK 8 이상); 1.64.0 미만 버전은 예기치 않은 오류와 성능 저하가 발생할 수 있어요
    • in-app 활성화 최소: 1.48.0
    • 수동 활성화 최소: 1.42.0
  • Datadog Agent, 버전 7.49.0 이상

Python (Language is Python)

  • Datadog Python SDK (ddtrace), 버전 4.11.0 이상 강력 권장; 4.11.0 미만 버전은 예기치 않은 오류와 성능 저하가 발생할 수 있어요
    • in-app 활성화 최소: 3.10.0
    • 수동 활성화 최소: 2.9.0
  • Datadog Agent, 버전 7.49.0 이상

.NET (Language is .NET)

  • Datadog .NET SDK, 버전 3.46.0 이상 강력 권장; 3.46.0 미만 버전은 예기치 않은 오류와 성능 저하가 발생할 수 있어요
    • in-app 활성화 최소: 3.29.0
    • 수동 활성화 최소: 3.9.0
  • Datadog Agent, 버전 7.49.0 이상

Node.js (Language is Node.js)

  • Datadog Node.js SDK (dd-trace-js), 버전 5.109.0 이상 강력 권장; 5.109.0 미만 버전은 예기치 않은 오류와 성능 저하가 발생할 수 있어요
    • in-app 활성화 최소: 5.84.0
    • 수동 활성화 최소: 5.39.0
    • 소스 코드가 트랜스파일되거나 번들된 경우(예: TypeScript, Babel, Webpack) 배포된 애플리케이션과 함께 게시된 소스 맵
  • Datadog Agent, 버전 7.49.0 이상

Ruby (Language is Ruby)

  • Datadog Ruby SDK (ddtrace), 최소 버전 2.37.0; 2.38.0 이상 강력 권장; 2.38.0 미만 버전은 예기치 않은 오류와 성능 저하가 발생할 수 있어요
  • Ruby 2.6 이상(MRI/CRuby만; JRuby는 지원되지 않아요)
  • Rack 기반 프레임워크(Rails, Sinatra 또는 기타 Rack 호환 프레임워크); 백그라운드 워커(예: Sidekiq, Resque)는 지원되지 않아요
  • RAILS_ENV 또는 RACK_ENV가 production으로 설정돼야 해요
  • Datadog Agent, 버전 7.49.0 이상

PHP (Language is PHP)

Go (Language is Go)

  • Datadog Go SDK, 버전 2.9.0 이상 강력 권장(v1 라인에서는 1.74.6 이상); 2.9.0 미만 버전은 예기치 않은 오류와 성능 저하가 발생할 수 있어요
    • in-app 활성화 최소: 2.6.0
  • Datadog Agent, 버전 7.73.0 이상, 애플리케이션과 같은 호스트에서 실행
  • Linux 커널 5.17 이상

Datadog 구성 (Datadog configuration)

  • 배포에 service, env, version 태그가 있는 Unified Service Tagging 구성
  • Agent에서 Remote Configuration 활성화
  • logs_enabled: true로 Agent 로그 수집 활성화
    • 로그 수집이 비활성화된 경우 apm_config.debugger_logs_enabled_override: true(DD_APM_DEBUGGER_LOGS_ENABLED_OVERRIDE=true)를 설정해 Live Debugger 로그를 전달해요.
  • (권장) Source Code Integration

권한 (Permissions)

Live Debugger를 사용하려면 다음 권한이 필요해요:

  • Live Debugger Read (live_debugger_read): Live Debugger 페이지에 접근하는 데 필요해요.
  • Live Debugger Write (live_debugger_write): Debug Session과 로그포인트를 만들거나 수정하는 데 필요해요.
  • Live Debugger Redaction Write (live_debugger_redaction_write): 캡처한 데이터의 리덱션 모드를 변경하는 데 필요해요.

역할과 사용자에게 역할을 할당하는 방법에 대한 자세한 내용은 Role Based Access Control을 참고해요.

설정 (Setup)

Go: Live Debugger를 사용하려면 Datadog Agent를 구성한 다음 애플리케이션에서 Live Debugger를 활성화해요.

Agent 구성하기 — 다음 방법 중 하나로 Live Debugger용 Agent를 구성해요:

YAML: system-probe.yaml(datadog.yaml 옆에 위치)을 다음과 같이 업데이트해요:

dynamic_instrumentation:
  enabled: true

자세한 내용은 Agent configuration files을 참고해요.

환경 변수: Datadog Agent 매니페스트에 다음을 추가해요:

DD_DYNAMIC_INSTRUMENTATION_ENABLED=true

Helm: Helm 차트에 다음을 추가해요:

datadog:
  dynamicInstrumentationGo:
    enabled: true

Live Debugger 활성화 (Enable Live Debugger)

Java, Python, .NET, Node.js, Go: Live Debugger를 in-app으로 또는 환경 변수로 활성화할 수 있어요.

In-app 활성화 (권장) — 다음 두 가지 방법 중 하나로 in-app에서 Live Debugger를 활성화해요:

  • Live Debugger Settings 페이지에서 서비스와 환경을 활성화해요.
  • Debug Session을 시작해요. Live Debugger가 선택한 서비스와 환경에서 자동으로 활성화돼요.

환경 변수로 활성화 — SDK가 in-app 최소 버전보다 낮거나 Datadog UI 외부에서 활성화를 관리하려면 다음 환경 변수를 설정해요.

Java: DD_DYNAMIC_INSTRUMENTATION_ENABLED=true와 함께 DD_SERVICE, DD_ENV, DD_VERSION을 설정해 서비스를 시작해요. -javaagent 인자는 -jar보다 먼저 와야 해요:

export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_DYNAMIC_INSTRUMENTATION_ENABLED=true
java \
    -javaagent:dd-java-agent.jar \
    -jar <YOUR_SERVICE>.jar

참고: JDK 18 이하에서는 -parameters 플래그(Spring 6+, Spring Boot 3+, Scala의 기본)로 컴파일된 클래스가 Method Parameters detected 오류와 함께 계측에 실패할 수 있어요.

Python: ddtrace를 설치한 다음 DD_DYNAMIC_INSTRUMENTATION_ENABLED=true와 ddtrace-run으로 서비스를 시작해요:

pip install ddtrace
export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_DYNAMIC_INSTRUMENTATION_ENABLED=true
ddtrace-run python -m myapp.py

.NET, Node.js, Go: 다음 환경 변수를 설정해 서비스를 시작해요:

DD_SERVICE=<YOUR_SERVICE>
DD_ENV=<YOUR_ENV>
DD_VERSION=<YOUR_VERSION>
DD_DYNAMIC_INSTRUMENTATION_ENABLED=true

Ruby: 다음 환경 변수를 설정해 서비스를 시작해요:

export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_DYNAMIC_INSTRUMENTATION_ENABLED=true

참고: Live Debugger는 첫 번째 HTTP 요청에서 초기화돼요. 로그포인트를 만들기 전에 서비스가 최소 하나의 요청을 받아야 해요.

PHP: 다음 환경 변수를 설정해 서비스를 시작해요:

DD_SERVICE=<YOUR_SERVICE>
DD_ENV=<YOUR_ENV>
DD_VERSION=<YOUR_VERSION>
DD_DYNAMIC_INSTRUMENTATION_ENABLED=true

활성화 모드 (Enablement modes)

Live Debugger를 활성화한 후 Live Debugger Settings 페이지에서 각 서비스와 환경의 활성화 상태를 확인하고 업데이트할 수 있어요. 각 서비스와 환경은 세 가지 모드 중 하나일 수 있어요:

  • Automatic: 이 서비스와 환경에서 Live Debugger가 아직 Enabled 또는 Disabled로 설정되지 않았어요. 첫 번째 Debug Session이 시작될 때 이 설정은 자동으로 Enabled로 변경돼요. 더 빠른 첫 디버깅 경험을 위해 미리 설정을 Enabled로 바꿔두세요.
  • Enabled: 디버그 심볼 업로드와 새 로그포인트의 빠른 전달을 포함해 선택한 서비스와 환경에서 Live Debugger가 활성화돼요.
  • Disabled: 해당 서비스와 환경에서 로그포인트를 만들거나 재활성화할 수 없어요.

로그 인덱스 만들기 (Create a logs index)

Live Debugger는 Datadog로 보내져 애플리케이션 로그 옆에 표시되는 로그를 생성해요. 특히 Exclusion filters를 사용하는 경우 전용 로그 인덱스가 이 로그가 의도치 않게 필터링되지 않도록 하는 데 도움이 돼요.

인덱스를 만들려면:

  1. 로그 인덱스를 만들고 샘플링 없이 원하는 보존 기간으로 구성해요.
  2. source:dd_debugger 태그와 일치하도록 필터를 설정해요. 모든 Live Debugger 로그에는 이 소스가 있어요.
  3. 첫 번째 일치가 우선하므로 새 인덱스가 해당 태그와 일치하는 필터가 있는 다른 인덱스보다 우선하도록 해요.

Source Code Integration을 설정해 Live Debugger에서 소스 코드 파일을 직접 볼 수 있어요. 서비스와 환경을 해당 리포지토리 및 Git 커밋 SHA에 연결한 후 IDE의 브레이크포인트처럼 소스 코드에서 로그포인트를 추가하고 기존 것을 볼 수 있어요. 이렇게 하면 로그포인트가 정확히 배치되었는지 확인하고 의도하지 않은 데이터를 캡처하거나 잘못된 결과를 생성하는 것을 피할 수 있어요.

참고: Source Code Integration은 Debug Session을 수동으로 시작할 때는 선택 사항이지만 Bits Live Debugger를 사용할 때는 필수예요.

Live Debugger 사용하기 (Using Live Debugger)

Debug Session 만들고 사용하기 (Creating and using a Debug Session)

Debug Session을 사용하면 자동 만료 로그포인트로 실행 중인 코드를 검사할 수 있어요. Debug Session을 만들고 사용하려면:

  1. 다음 위치 중 하나에서 Debug Session을 시작해요:
  2. 코드 위치를 선택해 첫 번째 로그포인트를 추가하고 로그 이벤트 캡처를 시작해요.
  3. 세션 동안 필요에 따라 로그포인트를 추가, 제거, 수정해요.
  4. 로그포인트로 캡처된 로그 이벤트는 수집·인덱싱되면서 Debug Session 보기에 나타나요. Logs Explorer와 로그 데이터를 참조하는 기타 Datadog 도구에서도 이 로그를 보고, 쿼리하고, 분석할 수 있어요.
  5. 조직의 사용자가 만든 활성·비활성 Debug Session을 Live Debugger Sessions 목록에서 확인해요. Debug Session의 로그 이벤트는 로그 인덱스에 정의된 보존 기간 동안에만 표시돼요.

Debug Session은 자동으로 만료돼요. 세션이나 개별 로그포인트를 언제든 수동으로 비활성화하거나 재활성화할 수도 있어요.

로그포인트 만들기 (Creating logpoints)

로그포인트는 코드에서 정보를 캡처할 위치, 포함할 데이터, 어떤 조건에서 캡처할지 지정하는 "non-breaking breakpoints"예요. 디버깅용 로그포인트를 추가하려면:

  1. Live Debugger 페이지로 이동해요.
  2. Create Debug Session을 클릭해요.
  3. 서비스와 환경을 선택하고 코드에서 첫 번째 로그포인트를 배치할 위치를 선택해요.
  4. expression language를 사용해 로그포인트 메시지 템플릿을 정의해요.
  5. (선택) Capture Variables 옵션을 사용해 모든 실행 컨텍스트 또는 특정 변수를 로그 이벤트 메타데이터의 일부로 수집해요(이 기능은 초당 1회 실행으로 제한돼요). 로그 메시지 문자열만 캡처하려면 로그포인트 정의에서 capture variables 옵션을 제거해요.
  6. (선택) 로그를 내보낼 조건을 정의해요.
  7. 기존 로그포인트 정의에 대한 변경 사항을 저장하려면 Apply changes를 클릭해요.

대부분의 로그포인트 설정은 생성 후 수정할 수 있어요(로그포인트가 이미 로그 이벤트 캡처를 시작했더라도). 다만 로그포인트가 처음 선택한 서비스, 환경, 코드 위치는 수정할 수 없어요(이 경우 새 로그포인트나 Debug Session을 만들어야 해요).

로그포인트를 만들거나 수정하거나 재활성화한 후 코드를 계측하고 로그 이벤트 캡처를 시작하는 데 몇 분이 걸릴 수 있어요. 참고: 선택한 코드가 실행되지 않거나 로그포인트 조건이 충족되지 않으면 로그 이벤트가 생성되지 않아요.

민감 데이터 보호하기 (Protecting sensitive data)

Live Debugger 데이터는 특히 Capture Variables 옵션을 사용할 때 민감한 정보를 포함할 수 있어요. Live Debugger는 이 데이터를 보호하기 위해 모드 기반 및 식별자 기반 리덱션을 자동으로 적용해요.

모드 기반 리덱션 — Live Debugger에는 두 가지 리덱션 모드가 있어요:

  • Strict Mode: 숫자와 부울을 제외한 모든 값을 리덱션해요. Bits Live Debugger는 Strict Mode로 설정된 서비스·환경 조합에서는 사용할 수 없어요.
  • Targeted Mode: 신용카드 번호, API 키, IP 및 기타 PII 같은 알려진 민감 패턴을 리덱션해요. 또한 캡처된 데이터에 [REDACTED:HIGH_ENTROPY]로 표시되는 가능성이 높은 비밀을 자동으로 리덱션하는 고엔트로피 비밀 스캐너도 실행해요.

이 리덱션 모드는 비활성화할 수 없고 전환만 가능해요. Targeted Mode는 staging이나 preprod 같은 일반적인 사전 프로덕션 환경에서 자동으로 적용돼요. 리덱션 모드를 변경하려면 Live Debugger Redaction Write 권한이 필요해요.

식별자 기반 리덱션 — 흔한 민감 식별자(예: password, accessToken 및 유사 용어)와 연관된 변수 값은 캡처된 데이터가 호스트를 떠나기 전에 스크러빙돼요. 언어별 추가 리덱션 규칙이 각 SDK에 내장돼 있어요.

다음을 통해 리덱션 동작을 확장할 수 있어요:

  • 커스텀 식별자 기반 리덱션
  • 클래스/타입 기반 리덱션 규칙
  • Sensitive Data Scanner 규칙

구성 세부 사항은 sensitive data scrubbing 지침과 Sensitive Data Scanner 문서를 참고해요.

Bits Live Debugger 사용하기 (Using Bits Live Debugger)

💡 Bits Live Debugger는 Preview 단계예요. Bits Live Debugger에 대해 알아보고 액세스를 요청하세요.

Bits Live Debugger를 사용하면 문제를 평문으로 설명해 실행 중인 서비스를 조사할 수 있어요. Bits Code가 로그포인트 배치를 처리하고, 변수 스냅샷을 캡처하며, 결과 해석을 도와줘요.

참고: Bits Live Debugger는 서비스와 환경이 Targeted Mode일 것을 요구해요. 자세한 내용은 Mode-based redaction을 참고해요.

제한 사항 (Limitations)

Live Debugger 사용 및 구성에는 다음 제약이 적용돼요:

  • 구성 범위: Live Debugger와 Dynamic Instrumentation은 동일한 서비스와 환경에 대해 함께 활성화되거나 비활성화돼요.
  • 속도 제한:
    • 변수 캡처가 있는 로그포인트: 초당 1회 실행으로 제한돼요.
    • 변수 캡처가 없는 로그포인트: 서비스 인스턴스당 초당 5000회 실행으로 제한돼요.

더 알아보기 (Learn more)