SDK 초기화¶
Windows SDK의 C# 및 Native C/C++ 초기화 매개변수는 동일한 데이터 의미 체계를 사용합니다. C#은 GuanceConfig로 클라이언트를 생성하고, Native는 guance_sdk_config_v2로 불투명 Handle을 생성합니다.
애플리케이션 구성¶
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)¶
구성 수명 주기¶
- 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는 빌드 구성과 독립적입니다. Release 빌드에서도 리스너를 통해 진단 이벤트를 수신하고 애플리케이션의 로그 시스템에 직접 기록할 수 있습니다.
스냅샷 읽기:
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, 인증 헤더 또는 사용자 민감 데이터를 출력해서는 안 됩니다.
런타임 기능¶
종료 후에는 클라이언트 또는 Native Handle을 계속 사용해서는 안 됩니다. 정상 종료 시 RUM 및 Log 큐가 처리됩니다.