SDK 初期化¶

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

アプリケーション設定¶

.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 つの構成には、少なくとも 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 として書き込まれたり送信されたりすることはありません。

初期化時に診断リスナーを登録：

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、認証ヘッダー、ユーザーの機密データを出力しないでください。

ランタイム機能¶

.NET / C#Native C/C++

await GuanceSdk.FlushAsync();
await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);
rum = nullptr;

シャットダウン後は、クライアントまたは Native ハンドルを引き続き使用しないでください。正常なシャットダウンにより、RUM と Log のキューが処理されます。

SDK 初期化¶

アプリケーション設定¶

基本設定¶

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

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

設定のライフサイクル¶

診断¶

ランタイム機能¶

関連ドキュメント¶

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

SDK 初期化¶

アプリケーション設定¶

基本設定¶

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

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

設定のライフサイクル¶

診断¶

ランタイム機能¶

関連ドキュメント¶

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

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