콘텐츠로 이동

SDK 초기화

Windows SDK의 C# 및 Native C/C++ 초기화 매개변수는 동일한 데이터 의미 체계를 사용합니다. C#은 GuanceConfig로 클라이언트를 생성하고, Native는 guance_sdk_config_v2로 불투명 Handle을 생성합니다.

애플리케이션 구성

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});
guance_sdk_config_v2 config; // vcpkg 0.1.0-alpha.9부터 지원
guance_sdk_config_v2_init(&config);
config.dataway_url = "https://openway.guance.com";
config.client_token = "<client-token>";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "prod";
config.application_version = "1.0.0";

guance_sdk_handle rum = guance_sdk_init_v2(&config);
if (rum == nullptr) {
    // 초기화에 실패했습니다.
}

Native 구조체는 반드시 먼저 guance_sdk_config_v2_init()를 호출하여 명시적으로 설정되지 않은 필드가 현재 버전의 기본값을 사용하도록 해야 합니다. 기존 guance_sdk_config 및 guance_sdk_init()는 ABI 호환성을 유지하지만, 샘플링 필드는 기존 0.0~1.0 단위를 계속 사용합니다.

기본 구성

의미 .NET / C# Native C/C++ 기본값 필수
공용 DataWay 주소 DatawayUrl dataway_url 없음 조건부 필수
로컬 환경 배포 주소 DatakitUrl datakit_url 없음 조건부 필수
Client Token ClientToken client_token 없음 DataWay 사용 시 필수
RUM 애플리케이션 ID RumAppId rum_app_id 없음 예
서비스 이름 ServiceName service_name df_rum_windows / df_rum_windows_native 예
환경 Env env prod 예
애플리케이션 버전 Version application_version 1.0.0 예
디버그 진단 Debug 빌드에서는 자동 출력(구성 항목 없음) debug — / 0 아니요. SDK 진단을 로컬에서만 출력하며 Logging Intake로는 업로드하지 않습니다.

C#의 Env는 prod, gray, pre, common, local을 지원합니다. 하나의 구성에는 최소한 하나의 업로드 주소를 설정해야 합니다.

파일 캐시 및 데이터 전송

의미 .NET / C# Native C/C++ 기본값
디스크 캐시 총 상한 Cache.MaxDiskBytes max_cache_bytes 128 MiB
캐시 파일 수 상한 Cache.MaxFiles max_cache_files 1024
캐시 배치 최대 보존 기간 Cache.MaxAge max_cache_age_seconds 7일
단일 배치 데이터 수 Cache.MaxBatchItems max_batch_items 50
단일 배치 압축 전 바이트 수 Cache.MaxBatchBytes max_batch_bytes 512 KiB
HTTP 타임아웃 HttpTimeout http_timeout_ms 10초
캐시 위치 CacheDirectory cache_path SDK 기본 디렉터리
프록시 사용자 지정 HttpMessageHandlerFactory proxy_url 없음
주기적 Flush FlushInterval flush_interval_ms .NET 및 Native 모두 기본 15초
Intake 압축 CompressIntakeRequests compress_intake_requests .NET 기본 true, Native 기본 1(켜짐)
회수 목표 워터마크 Cache.LowWatermarkRatio — 0.9
RUM 캐시 소프트 할당량 Cache.RumShare — 0.25
Log 캐시 소프트 할당량 Cache.LogShare — 0.15
Replay 캐시 소프트 할당량 Cache.SessionReplayShare — 0.60
집계 업로드 바이트 속도 Upload.MaxBytesPerSecond max_upload_bytes_per_second 256 KiB/s, 0이면 속도 제한 없음
업로드 버스트 바이트 수 Upload.BurstBytes upload_burst_bytes 2 MiB
집계 업로드 요청 속도 Upload.MaxRequestsPerSecond max_upload_requests_per_second 초당 2회, 0이면 속도 제한 없음
라운드당 업로드 배치 수 Upload.MaxBatchesPerCycle max_upload_batches_per_cycle 4
동시 업로드 요청 수 Upload.MaxConcurrentRequests — 1, 현재 1만 지원
RUM 업로드 가중치 Upload.RumWeight — 4
Log 업로드 가중치 Upload.LogWeight — 2
Replay 업로드 가중치 Upload.SessionReplayWeight — 1

디스크 캐시 총 상한은 RUM, Log, Session Replay가 공유합니다. 세 가지 유형의 데이터는 별도의 배치와 업로드 카운트를 사용하지만, 더 이상 큐 항목 또는 바이트 상한을 각각 구성하지 않습니다. 소프트 할당량은 다른 데이터 유형의 여유 공간을 빌려 쓸 수 있게 하며, 회수 시에는 소프트 할당량을 초과한 데이터를 우선 처리합니다. 업로드 속도 제한은 각 데이터 유형 간에 집계되어 계산됩니다.

Native는 guance_sdk_config_v2_init()를 통해 flush_interval_ms 및 compress_intake_requests의 기본값을 가져와야 합니다. 주기적 Flush는 항목 수 또는 바이트 상한에 도달하지 않은 RUM, Log 배치를 캡슐화하여 업로드를 예약합니다. flush_interval_ms가 0 이하이면 15000밀리초로 폴백됩니다. .NET과 Native는 기본적으로 zlib으로 래핑된 Deflate를 사용하여 RUM 및 Log Intake 요청 본문을 압축하고 Content-Encoding: deflate를 설정합니다. C#에서는 CompressIntakeRequests = false, Native에서는 compress_intake_requests = 0을 설정하여 압축을 끌 수 있습니다. 표의 배치 바이트 상한은 항상 압축 전 크기를 기준으로 계산됩니다.

확장 구성

.NET / C# 매개변수 기본값 설명
HttpMessageHandlerFactory null 사용자 지정 업로드 HTTP 핸들러로, 프록시 설정에 사용할 수 있습니다.
HttpResourceTimingProvider null 실제 네트워크 단계별 소요 시간을 제공합니다. RUM 구성을 참조하세요.
DiagnosticListener null 로컬 진단 이벤트를 수신하며 빌드 구성과 무관합니다.
DataModifier null 개별 필드를 수정합니다. 개인정보 보호 구성을 참조하세요.
LineDataModifier null 데이터 한 건 전체를 수정합니다. 개인정보 보호 구성을 참조하세요.
Trace new TraceConfig() Trace 구성을 참조하세요.
Logging new LogConfig() Log 구성을 참조하세요.
Privacy new RumPrivacyConfig() 개인정보 보호 구성을 참조하세요.
SessionReplay new RumSessionReplayConfig() Session Replay 구성을 참조하세요.
Cache new CacheOptions() 파일 캐시 매개변수. 위 표를 참조하세요.
Upload new UploadOptions() 업로드 스케줄링 매개변수. 위 표를 참조하세요.

로컬 환경 배포(Datakit)

GuanceSdk.Init(new GuanceConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});
guance_sdk_config_v2 config; // vcpkg 0.1.0-alpha.9부터 지원
guance_sdk_config_v2_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "local";
guance_sdk_handle rum = guance_sdk_init_v2(&config);

구성 수명 주기

  • C# GuanceConfig는 GuanceClient 수명 주기 동안 SDK가 보유하므로 GuanceSdk.Init()를 반복 호출하여 구성을 전환하지 마십시오.
  • Native 초기화 중에는 guance_sdk_config_v2 문자열이 복사됩니다. guance_sdk_init_v2() 반환 후 원본 문자열을 해제할 수 있습니다.
  • Native Trace/리소스 필터링 등 콜백 구성은 함수 포인터와 user_data를 유지합니다. 구체적인 수명 주기는 해당 구성 페이지를 기준으로 합니다.
  • C#과 Native 모두 애플리케이션 프로세스에서 활성 클라이언트를 하나만 생성하여 중복 수집을 방지해야 합니다.

진단

C# SDK는 런타임 Debug 스위치를 제공하지 않습니다. 애플리케이션이 Debug 빌드를 사용하거나 디버거가 연결된 경우, SDK는 자체 큐, 전송 및 자동 수집 진단을 현재 프로세스의 Console과 디버그 출력에 출력합니다. 최적화된 Release 실행에서는 자동으로 출력되지 않습니다. 진단 정보는 로컬 문제 해결에만 사용되며 사용자 지정 Log로 기록되거나 업로드되지 않습니다.

초기화 시 진단 리스너를 등록합니다:

DiagnosticListener = item =>
    Console.WriteLine($"{item.Level} {item.Source}: {item.Message}")

DiagnosticListener는 빌드 구성과 독립적입니다. Release 빌드에서도 리스너를 통해 진단 이벤트를 수신하고 애플리케이션의 로그 시스템에 직접 기록할 수 있습니다.

스냅샷 읽기:

var snapshot = GuanceSdk.GetDiagnosticsSnapshot();
Console.WriteLine(
    $"queued={snapshot.RumEventsEnqueued}, " +
    $"uploaded={snapshot.RumUploadSuccessCount}, " +
    $"retries={snapshot.RumUploadRetryCount}");
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));
}

진단 정보에는 Client Token, 인증 헤더 또는 사용자 민감 데이터를 출력해서는 안 됩니다.

런타임 기능

await GuanceSdk.FlushAsync();
await GuanceSdk.ShutdownAsync();
guance_sdk_flush(rum);
guance_sdk_shutdown(rum);
rum = nullptr;

종료 후에는 클라이언트 또는 Native Handle을 계속 사용해서는 안 됩니다. 정상 종료 시 RUM 및 Log 큐가 처리됩니다.

관련 문서

문서 평가

이 페이지가 도움이 되었나요?