SDK 초기화¶

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

애플리케이션 구성¶

.NET / C#Native C/C++

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 config;
guance_sdk_config_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.version = "1.0.0";

guance_sdk_handle rum = guance_sdk_init(&config);
if (rum == nullptr) {
    // 초기화 실패.
}

Native 구조체는 먼저 guance_sdk_config_init()을 호출해야 하며, 명시적으로 설정하지 않은 필드는 현재 버전의 기본값을 사용합니다.

기본 구성¶

의미	.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`	`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`(켜짐)

디스크 캐시 총 상한은 RUM, Log, Session Replay가 함께 사용합니다. 세 유형의 데이터는 독립적인 배치와 업로드 횟수를 사용하지만, 큐 항목 또는 바이트 상한을 각각 구성하지는 않습니다. C#에서는 Cache.LowWatermarkRatio와 세 개의 *Share 매개변수로 재확보 수위와 소프트 할당량을 제어하고, Upload로 집계 업로드 속도를 구성할 수 있습니다. Native는 해당 max_upload_* 필드를 사용합니다. HttpResourceTimingProvider는 실제 네트워크 단계 소요 시간을 제공하는 데 사용할 수 있습니다.

Native는 guance_sdk_config_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로 설정하여 압축을 끌 수 있습니다. 표의 배치 바이트 상한은 항상 압축 전 크기를 기준으로 계산됩니다.

로컬 환경 배포(Datakit)¶

.NET / C#Native C/C++

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 config;
guance_sdk_config_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(&config);

설정 수명 주기¶

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

진단¶

.NET / C#Native C/C++

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, 인증 Header 또는 사용자 민감 데이터가 출력되지 않아야 합니다.

런타임 기능¶

.NET / C#Native C/C++

await GuanceSdk.FlushAsync();
await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);
rum = nullptr;

종료 후에는 클라이언트 또는 Native Handle을 계속 사용할 수 없습니다. 정상 종료 시 RUM과 Log 큐가 처리됩니다.

SDK 초기화¶

애플리케이션 구성¶

기본 구성¶

파일 캐시 및 데이터 전송¶

로컬 환경 배포(Datakit)¶

설정 수명 주기¶

진단¶

런타임 기능¶

관련 문서¶

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

SDK 초기화¶

애플리케이션 구성¶

기본 구성¶

파일 캐시 및 데이터 전송¶

로컬 환경 배포(Datakit)¶

설정 수명 주기¶

진단¶

런타임 기능¶

관련 문서¶

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

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