SDK 初期化¶
Windows SDK の C# と Native C/C++ の初期化パラメータは、同じデータセマンティクスを使用します。C# は GuanceConfig を使用してクライアントを作成し、Native は guance_sdk_config_v2 を使用して不透明ハンドルを作成します。
Application 設定¶
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 をサポートします。同じ設定で少なくとも 1 つの送信先アドレスを設定してください。
ファイルキャッシュとデータ転送¶
| 意味 | .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 日 |
| 1 バッチあたりのデータ件数 | Cache.MaxBatchItems |
max_batch_items |
50 |
| 1 バッチあたりの未圧縮バイト数 | 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 で共有されます。3 種類のデータはそれぞれ独立したバッチとアップロードカウントを使用しますが、キューエントリやバイト上限は個別に設定されません。ソフトクォータでは、他のデータタイプの空き容量を借用できます。回収時には、ソフトクォータを超えたデータが優先的に処理されます。アップロードのレート制限は、各データタイプを集約して計算されます。
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 Handler です。プロキシの設定に使用できます。 |
HttpResourceTimingProvider |
null |
実際のネットワークフェーズの所要時間を提供します。RUM 設定 を参照してください。 |
DiagnosticListener |
null |
ローカルの診断イベントを受信します。ビルド設定とは関係ありません。 |
DataModifier |
null |
単一フィールドを変更します。プライバシー設定 を参照してください。 |
LineDataModifier |
null |
データ 1 件全体を変更します。プライバシー設定 を参照してください。 |
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 のどちらも、アプリケーションプロセス内に作成するアクティブなクライアントは 1 つだけにし、重複収集を避けてください。
診断¶
C# SDK は実行時の Debug スイッチを提供しません。アプリが Debug ビルドを使用しているか、デバッガーがアタッチされている場合、SDK は自身のキュー、転送、自動収集の診断を現在のプロセスのコンソールとデバッグ出力に出力します。最適化された 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、認証 Header、またはユーザーの機密データを出力しないでください。
ランタイム機能¶
終了後は、クライアントまたは Native Handle を引き続き使用しないでください。正常終了すると、RUM と Log のキューが処理されます。