문제 해결¶
SDK 초기화 예외 검증¶
.NET / C# 설정 검증¶
GuanceSdk.Init()는 핵심 설정을 즉시 검증합니다.
| 예외 정보 | 처리 방법 |
|---|---|
RumAppId is required. |
콘솔에서 생성한 애플리케이션 ID를 설정합니다. |
ServiceName is required. |
빈 값이 아닌 ServiceName을 설정합니다. |
Version is required. |
애플리케이션 버전을 설정합니다. |
Env must be one of... |
prod, gray, pre, common 또는 local을 사용합니다. |
Either DatawayUrl or DatakitUrl is required. |
전송 주소를 하나 이상 설정합니다. |
ClientToken is required when DatawayUrl is configured. |
공용 DataWay 모드에서 Client Token을 추가로 설정합니다. |
SampleRate must be between 0 and 1. |
샘플링 비율을 0.0~1.0으로 조정합니다. |
Native C/C++ 초기화 또는 로드 실패¶
- 애플리케이션, 임포트 라이브러리,
guance_windows_native.dll이 동일한 아키텍처를 사용하는지 확인합니다. 현재 vcpkg 포트는 동적x64-windows만 제공하며, 다른 아키텍처는 일치하는 아키텍처의 소스 빌드 산출물을 사용해야 합니다. - DLL이 애플리케이션 디렉터리 또는 Windows DLL 검색 경로에 있는지 확인합니다. NuGet 패키지의 x86, x64, ARM64 Native 런타임 에셋은 .NET 래퍼 계층에서 사용하며 C/C++ 헤더 파일 및 임포트 라이브러리와 동일하지 않습니다.
- 먼저
guance_sdk_config_init()를 호출한 후 주소, Token, 애플리케이션 ID, 서비스 이름, 버전, 환경을 입력합니다. - 공용 DataWay에는 주소와 Client Token이 필요하며, 로컬 환경 배포(Datakit)에는 접근 가능한 Datakit 주소를 입력해야 합니다.
guance_sdk_init()가 빈 Handle을 반환하면 필수 입력 항목, 캐시 디렉터리 권한, 프로세스 아키텍처를 확인합니다.
SDK가 정상 실행되는데 데이터가 없는 경우¶
콘솔에 RUM 데이터가 없는 경우¶
다음 항목을 순서대로 확인합니다.
- App ID가 현재 워크스페이스의 "사용자 지정" 애플리케이션과 일치하는지 확인합니다.
- 공용 DataWay에 올바른 기본 주소와 Client Token이 모두 설정되어 있는지 확인합니다.
- 로컬 환경 배포(Datakit)를 애플리케이션 프로세스에서 접근할 수 있고 RUM 수집기가 활성화되었는지 확인합니다.
- RUM
SampleRate또는sample_rate가0보다 큰지 확인합니다. - View가 시작되었거나 해당 자동 수집이 활성화되었는지 확인합니다.
- 애플리케이션이 종료되기 전에 대기하거나 종료(shutdown) API를 호출했는지 확인합니다.
var snapshot = GuanceSdk.GetDiagnosticsSnapshot();
Console.WriteLine(
$"sampled={snapshot.SessionSampled}, " +
$"enqueued={snapshot.RumEventsEnqueued}, " +
$"uploaded={snapshot.RumUploadSuccessCount}, " +
$"retry={snapshot.RumUploadRetryCount}, " +
$"terminal={snapshot.RumUploadTerminalFailureCount}, " +
$"lastStatus={snapshot.LastRumUploadStatusCode}, " +
$"lastError={snapshot.LastRumUploadError}");
guance_sdk_diagnostics diagnostics{};
if (guance_sdk_get_diagnostics(rum, &diagnostics)) {
printf("queued=%lld uploaded=%lld retries=%lld status=%lld error=%lld\n",
static_cast<long long>(diagnostics.rum_events_enqueued),
static_cast<long long>(diagnostics.rum_upload_success_count),
static_cast<long long>(diagnostics.rum_upload_retry_count),
static_cast<long long>(diagnostics.last_rum_upload_status_code),
static_cast<long long>(diagnostics.last_rum_upload_error_code));
}
큐에 추가된 개수가 0이면 샘플링, View, 수집 스위치를 먼저 확인합니다. 재시도가 계속 증가하면 네트워크, 프록시, DNS, 전송 주소를 확인합니다. 최종 실패가 증가하면 Token, 권한, 서버 상태 코드를 확인합니다.
데스크톱 UI에 View 또는 Action이 없는 경우¶
WPF 및 WinForms¶
- 첫 번째 창을 만들기 전에
EnableAutomaticInstrumentation()을 호출합니다. EnableWpf또는EnableWinForms가 꺼져 있지 않은지 확인합니다.- 주요 컨트롤에 안정적인
Name, 제목 또는 접근성 이름을 설정합니다. - 동적 WinForms 컨트롤은 Application Idle에서 스캔됩니다. 메시지 루프가 오랫동안 유휴 상태가 아니면 발견이 지연될 수 있습니다.
WinUI 3¶
WinUI 3 창은 Activate() 전에 명시적으로 연결해야 하며, 다중 창 애플리케이션은 창마다 개별적으로 연결해야 합니다.
window = new MainWindow().UseGuanceRum("MainWindow");
// 또는 GuanceSdk.AttachWinUIWindow(window, "MainWindow");
window.Activate();
Native C/C++¶
- 창 생성 후
guance_rum_start_view()를 호출하고, 창이 닫히기 전에guance_rum_stop_view()를 호출합니다. - Action은 명령, 메뉴 또는 입력 메시지 처리 경계에서 명시적으로 시작하고 종료해야 합니다.
- UI Watchdog에는 현재 프로세스가 소유한 유효한 최상위
HWND가 필요합니다. - Native SDK는 범용 창 또는 컨트롤 훅을 설치하지 않으므로 모든 MFC 또는 사용자 지정 프레임워크 이벤트를 자동으로 감지하지 않습니다.
Log 데이터가 없는 경우¶
GuanceConfig.Logging이 설정되어 있고EnableCustomLog = true인지 확인합니다.SampleRate,LevelFilters및 메시지가 30 KiB UTF-8 상한을 초과하는지 확인합니다.System.Diagnostics.Trace출력은 SDK가 자동으로 전달하지 않습니다. 애플리케이션의 기존 로그 출력 지점에서AddLog()또는AddLogs()를 명시적으로 호출하세요.GetLogDiagnosticsSnapshot()을 읽어 설정, 샘플링, 레벨, 용량 초과 폐기 횟수를 각각 확인합니다.
- 먼저
guance_log_config_init()를 호출한 다음guance_log_configure()를 호출합니다. enable_custom_log가1인지 확인하고sample_rate와level_filter_mask를 확인합니다.- Native SDK는 Console, ETW 또는 타사 로그 라이브러리를 자동으로 가로채지 않으므로 기존 로그 출력 지점에서
guance_log_add()또는guance_log_add_batch()를 호출해야 합니다. guance_log_get_diagnostics()를 사용하여 큐 추가, 폐기, 재시도, 마지막 상태 코드를 확인합니다.
Log와 RUM은 별도의 큐를 사용합니다. RUM이 정상이어도 Log가 활성화된 것은 아니며, 그 반대의 경우도 마찬가지입니다.
요청에 Trace Header가 없는 경우¶
EnableAutoTrace또는enable_auto_trace가 활성화되었는지 확인합니다.- 샘플링 비율이
0이 아닌지 확인하고 대상 URL이ShouldTrace또는should_trace를 통과하는지 확인합니다. - 서버가 요구하는 전파 형식이
TraceType또는trace_type과 일치하는지 확인합니다. - Trace Header는 선택한 형식에 따라 결정되므로
trace_id라는 이름의 HTTP Header만 찾지 마세요. - 신뢰할 수 없는 대상에 Trace Header를 전달하지 마세요.
자동 진단 구독에는 AutomaticInstrumentationOptions.EnableHttpClient = true가 필요합니다. 사용자 지정 HttpClient 파이프라인에서는 GuanceSdk.CreateHttpMessageHandler()를 명시적으로 사용할 수 있습니다.
WinHTTP 요청에는 guance_rum_winhttp.hpp 어댑터를 사용해야 합니다. 다른 HTTP 라이브러리는 guance_trace_create_context()를 호출하고 반환된 Header를 요청에 작성해야 합니다.
요청에 이미 동일한 이름의 Trace Header가 있으면 HTTP 라이브러리 또는 비즈니스 코드가 SDK 주입 후 해당 Header를 덮어썼는지 확인합니다.
Trace 또는 Log가 RUM과 연결되지 않는 경우¶
- Trace/Log 설정의
EnableLinkRumData또는enable_link_rum_data를 각각 활성화합니다. - 활성 View 또는 Action이 존재하는 동안 요청을 보내거나 Log를 기록합니다. SDK는 이미 종료된 컨텍스트를 소급하여 수정하지 않습니다.
- Trace 연관 정보는 일치하는 RUM Resource에 기록됩니다. Windows SDK는 APM Span을 별도로 업로드하지 않으므로 Trace 콘솔에 Span이 없다고 해서 Header 주입이 실패한 것은 아닙니다.
WebView2에 페이지 데이터가 없는 경우¶
- WebView2 Runtime이 설치되어 있고 컨트롤이
EnsureCoreWebView2Async()를 완료할 수 있는지 확인합니다. EnableWebView = true인지 확인하거나AttachWebView()를 명시적으로 호출합니다.- 동적 컨트롤은 초기화 완료 후 명시적으로 연결하는 것이 좋습니다.
- 컨트롤이
Unloaded또는Disposed된 후에는 새 인스턴스에서 다시 연결해야 합니다. - 진단 리스너를 등록하여
WebView2 initialization failed또는did not succeed를 확인합니다.
동일한 컨트롤에서 AttachWebView()를 반복 호출해도 주입이 중복되지 않습니다. 페이지 자체에서 Browser RUM을 초기화한 경우 동일한 페이지 이벤트를 수동으로 중복 보고하지 마세요.
Electron에 데이터가 없는 경우¶
먼저 애플리케이션이 어떤 Electron 통합 방식을 사용하는지 확인합니다. 두 방식은 Session과 업로드 소유자가 다르므로 설정을 혼용할 수 없습니다.
- 전체(Full) 모드에서는 npm으로 다운로드한 런타임 또는 CLI가 지정한
native.directory를 확인합니다. 혼합(Mixed) 모드에서는 C++ 호스트가 SDK를 초기화하고native.pipeName과 일치하는 Bridge Server를 시작했는지 확인합니다. 두 모드의 설치 단계는 Electron 모니터링을 참조하세요. - 전체 모드의 패키징 디렉터리는 ASAR 외부의
resources/native/이며, 동일한 버전과 아키텍처의 Bridge EXE, 기본 DLL, 매니페스트가 포함되어야 합니다. Replay를 사용할 때는 추가 DLL과replay-manifest.json도 필요합니다. 혼합 모드는 호스트가 기본 및 선택 DLL을 배포합니다. - 전체 모드는
native.settings를 통해 완전한 Native 설정을 제공하며 시작 및 구성 요소 로드 진단을 확인합니다. 종료 코드2는 전송 주소 또는 RUM Application ID가 없음을 의미하고, 종료 코드3은 Native Core 초기화 또는 Log 설정 실패를 의미합니다. - Browser RUM/Logs는 모니터링 대상 Renderer에서만 초기화됩니다. 각 창에는 Preload를 설치하고 신뢰할 수 있는
webContents를 등록한 후 최소 초기화를 한 번 실행해야 합니다. Renderer에는 Bridge 모드에 필요한 자리 표시자 파라미터만 입력하며 실제 Token, 애플리케이션 ID 또는 전송 주소는 입력하지 않습니다. - Renderer DevTools Network에는 RUM, Log 또는 Replay 직접 전송 요청이 표시되지 않아야 합니다. 고정 IPC Channel이 메시지를 수신하는지, Main Process가 신뢰할 수 있는 Renderer를 수락하는지 확인합니다. 전체 모드에서는 Bridge EXE의 stdin/stdout 전송을, 혼합 모드에서는 named-pipe 연결을 확인합니다.
- Native Host의 RUM, Log, Replay 큐 추가 횟수, 업로드 상태 코드, 재시도, 최종 실패 횟수를 확인합니다. 애플리케이션 종료 시 Adapter의
stop()이 완료될 때까지 기다립니다. 혼합 모드는 호스트가 자체 SDK Handle을 닫아 큐 데이터가 유실되지 않도록 해야 합니다.
Bridge는 Electron Main Process Crash를 자동으로 캡처할 수 없습니다. Renderer의 unresponsive와 render-process-gone은 Main Process가 수신하여 신뢰할 수 있는 Bridge 명령으로 변환해야 합니다. 전체 통합 방법은 Electron 모니터링을 참조하세요.
- Browser RUM은 Renderer에서만 초기화되며, 각 독립 Renderer 페이지마다 초기화해야 합니다.
file://페이지에서는sessionPersistence: "local-storage"를 설정합니다.- Main Process는 RUM 인스턴스를 원격 페이지에 자동으로 전달하지 않습니다.
- Browser RUM의
applicationId,site/datakitOrigin, Token 및 샘플링 비율을 확인합니다. - 이 모드는 Windows Native Bridge를 시작하지 않습니다. 전체 문제 해결 방법은 Web RUM Electron 앱 통합을 참조하세요.
데이터 중복¶
- 애플리케이션 시작 과정에서 해당 SDK Handle을 한 번만 초기화합니다.
.NET에서GuanceSdk.Init()을 반복 호출하면 이전 클라이언트가 비동기적으로 해제되며, 초기화 경계가 겹치면 중복 수집이 발생할 수 있습니다.- 자동 수집이 이미 다루는 컨트롤 상호 작용,
HttpClient또는 WinHTTP 요청을 수동으로 다시 보고하지 마세요. - WinUI 3에서는 동일한 창에 대해 한 가지 연결 방식만 사용합니다.
- Electron renderer는 초기화 진입점이 한 번만 실행되도록 해야 합니다.
Replay가 활성화되었지만 데이터가 없는 경우¶
.NET을 NuGet0.1.0-alpha.9로 업그레이드한 후 동일한 버전의Guance.Windows.SessionReplay가 설치되었는지 확인합니다. 초기화 시 설정한DiagnosticListener를 통해session_replay_component를 확인하여 패키지 누락, 버전 불일치, 로드 실패를 구분합니다.- Native를 vcpkg
0.1.0-alpha.10으로 업그레이드한 후replayFeature가 활성화되고 Replay DLL이 기본 DLL과 인접하며 버전과 아키텍처가 일치하는지 확인합니다. 표준 오류 출력의 Replay 구성 요소 진단을 확인하고session_replay_enabled만 확인하지 마세요. - 클라이언트의
IsSessionReplayAvailable또는guance_rum_is_session_replay_available()을 사용하여 구성 요소를 사용할 수 있는지 확인한 다음, 샘플링 비율, 활성 View, 녹화 시작/중지 상태를 확인합니다. 구성 요소를 사용할 수 있다고 해서 현재 Session이 샘플링된 것은 아닙니다. - Electron Full Mode에서는
--with-replay또는--replay-archive로 추가 구성 요소가 설치되고 패키징되었는지 확인합니다. Mixed Mode에서는 호스트 Native와 Bridge Server 모두 Replay가 활성화되었는지 확인합니다. WebView2/Electron의getCapabilities()에records가 포함되지 않으면 페이지에서 녹화를 강제로 시작해서는 안 됩니다.
기본 패키지만 설치한 경우에도 일반 RUM, Log, Trace는 정상 작동합니다. 자세한 설치 방법은 선택 구성 요소 설치를 참조하세요.
종료 시 큐에 데이터가 남는 경우¶
비동기 종료를 트리거한 후 곧바로 프로세스를 종료하지 마세요. Native 충돌 Error는 다음 시작 시 복원되어 큐에 추가되며, 충돌한 프로세스에서는 네트워크 업로드가 실행되지 않습니다.
Debug 디버깅 활성화¶
Native는 테스트 환경에서 debug = 1로 설정합니다. C#에는 런타임 Debug 설정 필드가 없으므로 초기화 시 설정한 DiagnosticListener 또는 GuanceSdk.AddDiagnosticListener()를 통해 SDK 레벨, 출처, 메시지를 기록합니다. 문제를 제출할 때 다음을 제공하세요.
- SDK 버전, 런타임 또는 컴파일러 버전, Windows 버전
- UI 프레임워크, 프로세스 아키텍처, 통합 언어
- 마스킹된 설정
- RUM 및 Log 진단 횟수, 상태 코드
- 재현 가능한 최소 단계
Client Token, 인증 Header, Cookie, 사용자 민감 정보 또는 로컬 절대 경로는 제출하지 마세요.