Error Tracking의 예외 재생 (Exception Replay in Error Tracking)
Error Tracking에서 예외가 발생할 때 실행 컨텍스트와 로컬 변수 값을 캡처해 문제를 더 빠르게 진단·재현·해결하도록 도와주는 APM Error Tracking의 Exception Replay 기능을 알아봐요.
출처: 문서
본문
{% callout %}
다음 Datadog 사이트 사용자에게 중요한 안내: app.ddog-gov.com, us2.ddog-gov.com
{% alert level="danger" %} 이 제품은 사용자가 선택한 Datadog 사이트에서는 지원되지 않아요. ({% placeholder "user-datadog-site-name" /%}). {% /alert %}
{% /callout %}
{% alert level="info" %} Exception Replay는 Python, Java, .NET, PHP에서 일반 공급(GA)되며, 지원되는 경우 기본적으로 활성화돼요. {% /alert %}
개요 (Overview)
Exception Replay는 예외가 발생할 때 실행 컨텍스트와 로컬 변수 값을 캡처해 문제를 더 빠르게 진단·재현·해결하도록 도와줘요. 스택 트레이스와 변수 스냅샷을 포함한 주변 상태를 기록한 다음, 이 데이터를 다른 이슈 세부 정보와 함께 Error Tracking에 직접 표시해요.
{% image source="https://docs.dd-static.net/images/tracing/error_tracking/error_tracking_executional_context-3.d6c8b6d269fe29196ad7854101a73e67.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/error_tracking/error_tracking_executional_context-3.d6c8b6d269fe29196ad7854101a73e67.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Error Tracking Explorer Exception Replay" /%}
Exception Replay는 운영(production) 사용을 위해 설계됐어요. 스냅샷은 속도가 제한되고 민감 데이터는 자동으로 삭제(redact)돼요. 활성화되면 애플리케이션의 예외를 기다렸다가 스택 트레이스와 로컬 변수의 스냅샷을 캡처한 뒤 Datadog으로 전달해요.
{% alert level="info" %} 어떤 제품이 지원되나요? Exception Replay는 APM 기반 예외에서만 사용할 수 있으며 Logs나 RUM의 오류는 지원하지 않아요. {% /alert %}
요구 사항 및 설정 (Requirements & Setup)
Exception Replay는 Python, Java, .NET, PHP를 지원하며 APM 기반 예외만 캡처해요. Datadog 에이전트와 APM 계측 애플리케이션이 필요해요. 환경 전체, 앱 내 개별 서비스, 또는 환경 변수를 사용해 특정 서비스에서 활성화할 수 있어요.
활성화 방법은 트레이서 버전과 원격 구성 (Remote Configuration) 사용 가능 여부에 따라 달라져요. 자세한 내용은 아래 표를 참고하세요.
| 환경별 (By Environment/Bulk) | 서비스별 (By Service/In-App) | 서비스별 (By Service/Env Var) |
|---|---|---|
| 활성화 방법 (How to Enable) | 기본 활성화됨 | Settings 페이지 |
| 에이전트 버전 (Agent Version) | v7.49.0+ | v7.49.0+ |
| 최소 트레이서 버전 (Minimum Tracer Versions) | Python ≥ 3.15.0Java ≥ 1.54.0.NET ≥ 3.29.0PHP ≥ 1.19.0 | Python ≥ 3.10.0Java ≥ 1.48.0.NET ≥ 3.29.0PHP ≥ 1.14.0 |
| 원격 구성 필요? (Remote Configuration Required?) | 예 | 예 |
앱 내에서 Exception Replay를 활성화하려면 Error Tracking의 Exception Replay Settings 페이지로 이동해 원하는 환경 또는 서비스를 선택하고 Enabled로 전환해요.
{% video url="https://docs.dd-static.net/images/tracing/error_tracking/error_tracking_exception_replay_enablement.mp4" /%}
앱 내 활성화를 사용할 수 없다면 환경 변수를 설정해요:
DD_EXCEPTION_REPLAY_ENABLED=true
이 값은 앱 내 구성을 재정의하는 데도 사용할 수 있으며, 둘 다 설정된 경우 우선해요.
Exception Replay 스냅샷용 로그 인덱스 만들기 (Create a logs index for Exception Replay snapshots)
Exception Replay 스냅샷 전용 로그 인덱스를 만들고 원하는 보존 기간과 샘플링 없음으로 구성해요.
source:dd_debugger와 일치하도록 필터를 설정해요.- 인덱스가 이 태그와 일치하는 다른 인덱스보다 우선하도록 해요(첫 번째 일치가 우선).
{% alert level="info" %} 왜 로그 인덱스를 만드나요? Exception Replay 스냅샷은 원래 APM 스팬에 연결되는 링크가 포함된 로그로 전송돼요. {% /alert %}
소스 코드 연결하기 (Link your source code)
Datadog 소스 코드 통합을 활성화하면 Error Tracking 스택 트레이스 내에서 직접 코드 미리 보기를 볼 수 있어요. Exception Replay 스냅샷이 캡처되면 코드 미리 보기에서 변수 이름 위에 마우스를 올려 캡처된 값을 볼 수 있어요.
{% video url="https://docs.dd-static.net/images/tracing/error_tracking/error_tracking_exception_replay_sci.mp4" /%}
민감 데이터 삭제 (Sensitive data redaction)
Exception Replay는 스냅샷을 사용할 수 있게 되기 전에 민감 데이터를 보호하기 위해 자동 모드 기반 및 식별자 기반 삭제를 적용해요.
모드 기반 삭제 (Mode-based redaction)
Exception Replay에는 두 가지 삭제 모드가 있어요:
- Strict Mode: 숫자와 불리언을 제외한 모든 값을 삭제해요.
- Targeted Mode: 신용카드 번호, API 키, IP, 기타 PII 같은 알려진 민감 패턴을 삭제해요. 또한 높은 엔트로피 비밀 스캐너를 실행해 가능성이 높은 비밀을 자동으로 삭제하며, 이 값은 스냅샷에서
[REDACTED:HIGH_ENTROPY]로 표시돼요.
이러한 삭제 모드는 비활성화할 수 없고 전환만 가능하며, Targeted Mode는 staging이나 preprod 같은 일반적인 사전 운영 환경에서 자동으로 적용돼요.
식별자 기반 삭제 (Identifier-based redaction)
일반적인 민감 식별자(예: password, accessToken 및 유사한 용어)와 연결된 변수 값은 스냅샷이 호스트를 떠나기 전에 삭제돼요. 각 트레이서에는 추가 언어별 삭제 규칙이 내장되어 있어요(예: Python 트레이서는 기본 민감 식별자 목록을 유지해요).
삭제 동작은 다음을 통해 확장할 수 있어요:
- 커스텀 식별자 기반 삭제
- 클래스/유형 기반 삭제 규칙
- Sensitive Data Scanner 규칙
구성 세부 사항은 Dynamic Instrumentation 민감 데이터 스크러빙 지침과 Sensitive Data Scanner 문서를 참고하세요.
{% alert level="info" %} 왜 DI 지침인가요? Exception Replay는 Dynamic Instrumentation (DI) 위에 구축되어 있어, 민감 데이터 스크러빙 구성 옵션도 여기에 적용돼요. {% /alert %}
문제 해결 (Troubleshooting)
누락된 변수 값 (Missing variable values)
Exception Replay 스냅샷은 인스턴스당 예외 유형당 시간당 스냅샷 1개로 속도가 제한돼요. 일부 런타임에서는 주어진 예외에 대해 두 번째 발생 후에만 스냅샷이 캡처돼요.
스냅샷이 나타나지 않을 수 있는 추가 이유 (Additional reasons a snapshot may not appear)
- Exception Replay가 활성화되지 않음
- 스냅샷이 선택한 시간 창 밖에서 발생
- 타사 패키지 제외(
DD_THIRD_PARTY_DETECTION_EXCLUDES로 포함 가능) - 로그 인덱스 보존 설정이나 앞선 인덱스의 제외 필터 (Exclusion Filters)로 인해
source:dd_debugger로그가 누락됨 - Exception Replay가 FedRAMP 지역에서 사용 불가
- Java: JDK 18 이하에서
-parameters플래그로 컴파일된 클래스는 지원되지 않을 수 있어요. Spring 6+, Spring Boot 3+, Scala는 기본적으로 이 플래그를 사용해요. - .NET: FIPS 활성화 호스트에서 트레이서 버전 3.55.0 이전은 Exception Replay를 지원하지 않아요. Linux에서 애플리케이션이 크래시할 수 있어요. Exception Replay를 사용하려면 트레이서 3.55.0 이상으로 업그레이드하세요. 이전 버전에서는 크래시를 피하려면
DD_EXCEPTION_REPLAY_ENABLED=false로 설정하세요.
Error Tracking Explorer에서 @error.debug_info_captured:true 쿼리를 사용해 Exception Replay 스냅샷이 있는 오류를 찾아보세요.
GovCloud의 BatchUploader WARN 메시지 (BatchUploader WARN messages on GovCloud/Java)
GovCloud 사이트(app.ddog-gov.com)에서 Java 트레이서는 com.datadog.debugger.uploader.BatchUploader에서 HTTP 403과 함께 This traffic is not permitted on your account와 유사한 주기적 WARN 메시지를 기록할 수 있어요. 이는 Exception Replay, Dynamic Instrumentation, Code Origin for Spans가 지원되지 않는 사이트에서 디버거 관련 업로드를 시도할 때 예상되는 동작이에요. 핵심 APM 기능(트레이스, 메트릭, 프로파일링, 로그 주입)은 영향을 받지 않아요.
이 로그 메시지를 중지하려면 Java 애플리케이션 파드에 다음 환경 변수를 설정하고 워크로드를 재시작하세요:
DD_EXCEPTION_REPLAY_ENABLED=false
DD_DYNAMIC_INSTRUMENTATION_ENABLED=false
DD_CODE_ORIGIN_FOR_SPANS_ENABLED=false
또는 JVM 시스템 속성을 사용해요:
-Ddd.exception.replay.enabled=false
-Ddd.dynamic.instrumentation.enabled=false
-Ddd.code.origin.for.spans.enabled=false
수정을 확인하려면 트레이서 시작 JSON(DATADOG TRACER CONFIGURATION)을 확인해 debugger_exception_enabled, debugger_enabled, debugger_span_origin_enabled가 모두 false인지 확인하세요. WARN 메시지는 약 5분에 한 번꼴로 속도가 제한되므로, 재시작 후 메시지가 중지되었는지 확인하려면 최소 그 시간만큼 기다려야 해요.
더 알아보기 (Learn more)
도움이 되는 추가 문서, 링크, 아티클이에요: