コンテンツにスキップ

SDK 初期化

Windows SDK の C# と Native C/C++ の初期化パラメータは、同じデータセマンティクスを使用します。C# は GuanceConfig を使用してクライアントを作成し、Native は guance_sdk_config_v2 を使用して不透明ハンドルを作成します。

Application 設定

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 をサポートします。同じ設定で少なくとも 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)

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 のどちらも、アプリケーションプロセス内に作成するアクティブなクライアントは 1 つだけにし、重複収集を避けてください。

診断

C# SDK は実行時の Debug スイッチを提供しません。アプリが Debug ビルドを使用しているか、デバッガーがアタッチされている場合、SDK は自身のキュー、転送、自動収集の診断を現在のプロセスのコンソールとデバッグ出力に出力します。最適化された 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、またはユーザーの機密データを出力しないでください。

ランタイム機能

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

終了後は、クライアントまたは Native Handle を引き続き使用しないでください。正常終了すると、RUM と Log のキューが処理されます。

関連ドキュメント

フィードバック

このページは役に立ちましたか?