문제 해결¶

SDK 초기화 예외 검증¶

.NET / C# 구성 검증¶

GuanceSdk.Init()은 주요 구성을 즉시 검증합니다.

Native C/C++ 초기화 또는 로드 실패¶

1. 애플리케이션, 임포트 라이브러리, guance_windows_native.dll이 동일한 아키텍처를 사용하는지 확인합니다. 현재 vcpkg 포트는 동적 x64-windows만 제공합니다. 다른 아키텍처에서는 일치하는 아키텍처의 소스 빌드 산출물을 사용해야 합니다.
2. DLL이 애플리케이션 디렉터리 또는 Windows DLL 검색 경로에 있는지 확인합니다. NuGet 패키지의 x86, x64, ARM64 Native 런타임 에셋은 .NET 래퍼 레이어용이며 C/C++ 헤더 파일 및 임포트 라이브러리와 동일하지 않습니다.
3. 먼저 guance_sdk_config_init()을 호출한 다음 주소, Token, 애플리케이션 ID, 서비스 이름, 버전, 환경을 입력합니다.
4. 공용 DataWay에는 주소와 Client Token이 필요하며, 로컬 환경 배포(Datakit)에서는 접근 가능한 Datakit 주소를 입력해야 합니다.
5. guance_sdk_init()이 빈 Handle을 반환하면 필수 항목, 캐시 디렉터리 권한, 프로세스 아키텍처를 확인합니다.

SDK가 정상 실행되지만 데이터가 없음¶

콘솔에 RUM 데이터가 없음¶

다음 순서로 확인합니다.

1. App ID가 현재 워크스페이스의 "사용자 지정" 애플리케이션과 일치하는지 확인합니다.
2. 공용 DataWay에 올바른 기본 주소와 Client Token이 모두 설정되어 있는지 확인합니다.
3. 로컬 환경 배포(Datakit)에 애플리케이션 프로세스에서 접근할 수 있고 RUM 수집기가 활성화되어 있는지 확인합니다.
4. RUM SampleRate 또는 sample_rate가 0보다 큰지 확인합니다.
5. View가 시작되었거나 해당 자동 수집이 활성화되어 있는지 확인합니다.
6. 애플리케이션 종료 전에 종료 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는 일반 창 또는 컨트롤 Hook을 설치하지 않으므로 모든 MFC 또는 사용자 지정 프레임워크 이벤트를 자동으로 발견하지 않습니다.

Log 데이터가 없음¶

Log와 RUM은 별도의 큐를 사용합니다. RUM이 정상이어도 Log가 활성화된 것은 아니며, 그 반대도 마찬가지입니다.

요청에 Trace Header가 없음¶

1. EnableAutoTrace 또는 enable_auto_trace가 활성화되어 있는지 확인합니다.
2. 샘플링 비율이 0이 아닌지 확인하고 대상 URL이 ShouldTrace 또는 should_trace를 통과하는지 확인합니다.
3. 서버가 요구하는 전파 형식이 TraceType 또는 trace_type과 일치하는지 확인합니다.
4. Trace Header는 선택한 형식에 따라 결정되므로 trace_id라는 이름의 HTTP Header만 검색하지 마세요.
5. 신뢰할 수 없는 대상에 Trace 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에 페이지 데이터가 없음¶

1. WebView2 Runtime이 설치되어 있고 컨트롤이 EnsureCoreWebView2Async()를 완료할 수 있는지 확인합니다.
2. EnableWebView = true인지 확인하거나 AttachWebView()를 명시적으로 호출합니다.
3. 동적 컨트롤은 초기화 완료 후 명시적으로 연결하는 것이 좋습니다.
4. 컨트롤이 Unloaded 또는 Disposed된 후에는 새 인스턴스에 다시 연결해야 합니다.
5. 진단 리스너를 등록하고 WebView2 initialization failed 또는 did not succeed 메시지를 확인합니다.

동일한 컨트롤에서 AttachWebView()를 반복 호출해도 중복 주입되지 않습니다. 페이지 자체에서도 Browser RUM을 초기화했다면 동일한 페이지 이벤트를 수동으로 중복 전송하지 마세요.

Electron에 데이터가 없음¶

먼저 애플리케이션이 어떤 Electron 연동 방식을 사용하는지 확인합니다. 두 방식은 Session과 업로드 소유자가 다르므로 구성을 혼용할 수 없습니다.

데이터 중복¶

• 애플리케이션 시작 과정에서 해당 SDK Handle을 한 번만 초기화합니다.
• .NET에서 GuanceSdk.Init()을 반복 호출하면 이전 클라이언트가 비동기적으로 해제되므로 초기화 경계가 겹치면 중복 수집이 발생할 수 있습니다.
• 자동 수집이 이미 적용된 컨트롤 상호 작용, HttpClient 또는 WinHTTP 요청을 다시 수동으로 전송하지 마세요.
• WinUI 3에서 동일한 창에는 한 가지 연결 방식만 사용합니다.
• Electron renderer는 초기화 진입점이 한 번만 실행되도록 해야 합니다.

종료 시 큐 데이터가 남아 있음¶

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

비동기 종료를 트리거한 직후 프로세스를 종료하지 마세요. Native 크래시 Error는 다음 시작 시 복구되어 인큐되며, 크래시 프로세스에서는 네트워크 업로드가 실행되지 않습니다.

Debug 모드 활성화¶

테스트 환경에서 Debug = true 또는 debug = 1을 활성화합니다. C#에서는 GuanceSdk.AddDiagnosticListener()를 통해 SDK 수준, 출처, 메시지를 기록할 수 있습니다. 문제를 제출할 때 다음 항목을 제공하세요.

• SDK 버전, 런타임 또는 컴파일러 버전, Windows 버전.
• UI 프레임워크, 프로세스 아키텍처, 연동 언어.
• 비식별화된 구성.
• RUM 및 Log 진단 카운트, 상태 코드.
• 재현 가능한 최소 단계.

Client Token, 인증 Header, Cookie, 사용자 민감 정보 또는 로컬 절대 경로를 제출하지 마세요.