문제 해결¶

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 주입 후 이를 덮어썼는지 확인하세요.

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 충돌 오류는 다음 시작 시 복구되어 큐에 추가되며, 충돌 프로세스에서 네트워크 업로드가 실행되지 않습니다.

Debug 디버그 활성화¶

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

• SDK 버전, 런타임 또는 컴파일러 버전 및 Windows 버전
• UI 프레임워크, 프로세스 아키텍처 및 연동 언어
• 민감한 정보가 제거된 설정
• RUM 및 Log 진단 횟수, 상태 코드
• 재현 가능한 최소 단계

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