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`	비어 있음
주기적 플러시	`FlushInterval`	`flush_interval_ms`	.NET 및 Native 모두 기본값 `15`초
Intake 압축	`CompressIntakeRequests`	`compress_intake_requests`	.NET 기본값 `true`, Native 기본값 `1`(켜짐)

디스크 캐시 총 상한은 RUM, Log 및 세션 리플레이 간에 공유됩니다. 세 가지 데이터 유형은 독립적인 배치 및 업로드 카운트를 사용하지만, 더 이상 개별적으로 큐 항목 또는 바이트 상한을 구성하지 않습니다. C#은 또한 Cache.LowWatermarkRatio 및 세 개의 *Share 매개변수를 통해 재생 수위와 소프트 할당량을 제어할 수 있으며, Upload 구성을 통해 집계 업로드 속도를 제어합니다. Native는 해당 max_upload_* 필드를 사용합니다. HttpResourceTimingProvider는 실제 네트워크 단계 지연 시간을 제공하는 데 사용할 수 있습니다.

Native는 guance_sdk_config_init()을 통해 flush_interval_ms 및 compress_intake_requests의 기본값을 가져와야 합니다. 주기적 플러시는 항목 수 또는 바이트 상한에 도달하지 않은 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로 기록되거나 Guance에 보고되지 않습니다.

초기화 시 진단 리스너 등록:

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)¶

구성 수명 주기¶

진단¶

런타임 기능¶

관련 문서¶

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

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