SDK 初期化¶

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

Application 設定¶

.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 をサポートします。同じ設定で少なくとも 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`（有効）

ディスクキャッシュの合計上限は、RUM、Log、Session Replay で共有されます。3 種類のデータは独立したバッチとアップロードカウントを使用しますが、キューエントリやバイト数の上限は個別に設定しません。C# では、Cache.LowWatermarkRatio と 3 つの *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 の両方で、アプリケーションプロセス内にアクティブなクライアントを 1 つだけ作成し、重複した収集を避ける必要があります。

診断¶

.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 初期化¶

Application 設定¶

基本設定¶

ファイルキャッシュとデータ転送¶

ローカル環境デプロイメント（Datakit）¶

設定のライフサイクル¶

診断¶

ランタイム機能¶

関連ドキュメント¶

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

SDK 初期化¶

Application 設定¶

基本設定¶

ファイルキャッシュとデータ転送¶

ローカル環境デプロイメント（Datakit）¶

設定のライフサイクル¶

診断¶

ランタイム機能¶

関連ドキュメント¶

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

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