Azure Spatial Anchors でのログ記録と診断Logging and diagnostics in Azure Spatial Anchors

Azure Spatial Anchors は、アプリの開発に役立つ標準のログ記録メカニズムを提供します。Azure Spatial Anchors provides a standard logging mechanism that's useful for app development. Spatial Anchors の診断ログ モードは、デバッグに関してより多くの情報が必要な場合に役立ちます。The Spatial Anchors diagnostics logging mode is useful when you need more information for debugging. 診断ログは、環境のイメージを保存します。Diagnostics logging stores images of the environment.

標準的なログ記録Standard logging

Spatial Anchors API では、ログ記録メカニズムをサブスクライブすることで、アプリケーション開発とデバッグに役立つログを取得することができます。In the Spatial Anchors API, you can subscribe to the logging mechanism to get useful logs for application development and debugging. 標準的なログ記録 API では、デバイス ディスク上に環境の画像は保存されません。The standard logging APIs don't store pictures of the environment on the device disk. これらのログは SDK でイベントのコールバックとして提供されます。The SDK provides these logs as event callbacks. これらのログをアプリケーションのログ記録メカニズムに統合するかどうかは、お客様が選ぶことができます。It's up to you to integrate these logs into the application's logging mechanism.

ログ メッセージの構成Configuration of log messages

ユーザーが関心を持つコールバックが 2 つあります。There are two callbacks of interest for the user. 次のサンプルは、セッションの構成方法を示しています。The following sample shows how to configure the session.

    cloudSpatialAnchorSession = new CloudSpatialAnchorSession();
    . . .
    // set up the log level for the runtime session
    cloudSpatialAnchorSession.LogLevel = SessionLogLevel.Information;

    // configure the callback for the debug log
    cloudSpatialAnchorSession.OnLogDebug += CloudSpatialAnchorSession_OnLogDebug;

    // configure the callback for the error log
    cloudSpatialAnchorSession.Error += CloudSpatialAnchorSession_Error;

イベントとプロパティEvents and properties

これらのイベント コールバックは、ログとエラーをセッションから処理するために提供されています。These event callbacks are provided to process logs and errors from the session:

  • LogLevel: ランタイムから受信するイベントの詳細のレベルを指定します。LogLevel: Specifies the level of detail for the events to receive from the runtime.
  • OnLogDebug: 標準的なデバッグ ログ イベントが提供されます。OnLogDebug: Provides standard debug log events.
  • エラー: ランタイムでエラーであると見なされたログ イベントが提供されます。Error: Provides log events that the runtime considers to be errors.

診断ログDiagnostics logging

Spatial Anchors にはログ記録操作の標準モードに加え、診断モードも存在します。In addition to the standard mode of operation for logging, Spatial Anchors also has a diagnostics mode. 診断モードでは、環境のイメージがキャプチャされ、ディスクにログ記録されます。Diagnostics mode captures images of the environment and logs them to the disk. このモードを使用すると、アンカーの予測検索の失敗など、特定の種類の問題をデバッグすることができます。You can use this mode to debug certain kinds of issues, like failure to predictably locate an anchor. 診断ログは、特定の問題を再現するためにのみ、有効にしてください。Enable diagnostics logging only to reproduce a specific issue. 終了後は、無効にします。Then disable it. アプリの通常実行時には、診断を有効にしないでください。Don't enable diagnostics when you're running your apps normally.

Microsoft サポートの利用中に、Microsoft の担当者が詳しい調査のため診断バンドルの提出を依頼することがあります。During a support interaction with Microsoft, a Microsoft representative might ask if you're willing to submit a diagnostics bundle for further investigation. この場合、診断を有効にして問題を再現し、診断バンドルを送信することができます。In this case, you might decide to enable diagnostics and reproduce the issue so you can submit the diagnostic bundle.

Microsoft の担当者が事前に認識していない状態で診断ログを Microsoft に提出しても、返答は得られません。If you submit a diagnostics log to Microsoft without prior acknowledgement from a Microsoft representative, the submission will go unanswered.

以下のセクションでは、診断モードを有効にする方法と、Microsoft に診断ログを送信する方法についても説明します。The following sections show how to enable diagnostics mode and also how to submit diagnostics logs to Microsoft.

診断ログの有効化Enable diagnostics logging

セッションについて診断ログを有効にすると、セッション内のすべての操作に対応する診断ログがローカル ファイル システムに生成されます。When you enable a session for diagnostics logging, all operations in the session have corresponding diagnostics logging in the local file system. ログ記録の間、環境のイメージがディスクに保存されます。During logging, images of the environment are saved to the disk.

private void ConfigureSession()
{
    cloudSpatialAnchorSession = new CloudSpatialAnchorSession();
    . . .

    // set up the log level for the runtime session
    cloudSpatialAnchorSession.LogLevel = SessionLogLevel.Information;

    // configure the callbacks for logging and errors
    cloudSpatialAnchorSession.OnLogDebug += CloudSpatialAnchorSession_OnLogDebug;
    cloudSpatialAnchorSession.Error += CloudSpatialAnchorSession_Error;

    // opt in to diagnostics logging of environment images
    // if this is enabled, the diagnostics bundle includes images of the environment captured by the session
    cloudSpatialAnchorSession.Diagnostics.ImagesEnabled = true;

    // set the level of detail to be collected in the diagnostics log by the session
    cloudSpatialAnchorSession.Diagnostics.LogLevel = SessionLogLevel.All;

    // set the max bundle size to capture the bug information
    cloudSpatialAnchorSession.Diagnostics.MaxDiskSizeInMB = 200;
    . . .
}

診断バンドルの提出Submit the diagnostics bundle

次のコード スニペットは、診断バンドルを Microsoft に提出する方法を示しています。The following code snippet shows how to submit a diagnostics bundle to Microsoft. このバンドルには、診断を有効にした後にセッションでキャプチャされた環境のイメージが含まれます。This bundle will include images of the environment captured by the session after you enable diagnostics.

// method to handle the diagnostics bundle submission
private async Task CreateAndSubmitBundle()
{
    // create the diagnostics bundle manifest to collect the session information
    string path = await cloudSpatialAnchorSession
                              .Diagnostics
                              .CreateManifestAsync("Description of the issue");

    // submit the manifest and data to send feedback to Microsoft
    await cloudSpatialAnchorSession.Diagnostics.SubmitManifestAsync(path);
}

診断バンドルのパーツParts of a diagnostics bundle

診断バンドルには次のような情報が含まれています。The diagnostics bundle might contain the following information:

  • キーフレームのイメージ: 診断が有効な状態のときにセッションでキャプチャされた環境のイメージ。Keyframe images: Images of the environment captured during the session while diagnostics were enabled.
  • ログ:ランタイムによって記録されたログ イベント。Logs: Log events recorded by the runtime.
  • セッションのメタデータ: セッションを識別するメタデータ。Session metadata: Metadata that identifies the session.