Share via


SharePoint Online と連携するカスタム アプリケーションでエラー ログに残すべき必須情報

こんにちは SharePoint サポートの森 健吾 (kenmori) です。

今回の投稿では、SharePoint Online および OneDrive for Business と連携するカスタム アプリケーションで、エラーが発生した際にログに含めるべき情報についてご紹介します。

 

関連付け ID について

SharePoint Online や OneDrive for Business に対して CSOM や REST API を呼び出すアプリケーションにおいては、問題が発生した際のトラブルシューティングのために、エラー発生時の関連付け ID が必要になります。このため、カスタム アプリケーション側でもこの関連付け ID をログに残す必要があります。

ブラウザからアクセスする通常の利用シナリオにおいても、Fiddler や IE 開発者ツールなどで HTTP トレースを採取し、応答ヘッダーから SPRequestGUID 値を確認することがありますが、API を使用した場合においても有効な方法となります。

弊社サポートで調査を行う際には、この関連付け ID から現象発生時のサーバー側のログを確認します。なお、ログの保持期間はとても短いため (通常は約1日程度)、現象発生後なるべくお早めにお問い合わせください。

 

概要

上記ご説明をふまえ、一般的に調査を実施する上で必要な情報は以下になります。
詳細な説明は後記いたします。

1. 現象が発生した日付と時刻
2. エラー メッセージ
3. 呼び出し先 URL
4. HTTP ステータス コード
5. 関連付け ID (Correlation ID)

 

サンプル コード

上記情報を採取するためのサンプル コード (C#) を以下にご紹介します。

下記サンプルの通り、CSOM とREST いずれにおいても、ログ出力に必要な情報は、例外オブジェクトを WebException にキャストし、応答 (Response) 内容を解析して集める方法が効率的です。
なお、ServerException およびその派生クラスの例外オブジェクトをキャッチした場合の処理も追記しております。(2017/11/06)

下記は最小構成のサンプル コードとなりますが、ディスク容量を考慮しない場合は、すべての HTTP 応答ヘッダーを残していただくとさらに有効です。

using を以下のように追加します。

 using System.Net;
using System.Text;

以下は例外情報を解析するメソッド GetExceptionDetail 呼び出し元部分です。 

         private void RunCSOMorREST()
        {
            try
            {
                // CSOM または REST API の呼び出し
            }
            catch (Exception ex)
            {
                string ErrorText = GetExceptionDetail(ex);

            }
        }

以下は、例外オブジェクトからデータを実際に取得するメソッド部分の実装です。

         private string GetExceptionDetail(Exception ex)
        {
            StringBuilder errorText = new StringBuilder();
            // エラー メッセージ
            errorText.Append(ex.Message);
            if (ex is WebException)
            {
                WebException wex = ex as WebException;
                if (wex.Response != null)
                {
                    HttpWebResponse response = (HttpWebResponse)wex.Response;
                    errorText.Append("\t");
                    // 呼び出し先 URL
                    errorText.Append(response.ResponseUri.ToString());
                    errorText.Append("\t");
                    // HTTP ステータス コード
                    errorText.Append(response.StatusCode);
                    errorText.Append("\t");
                    // 関連付け ID (Correlation ID)
                    errorText.Append(response.Headers["SPRequestGuid"]);
                }
            }
            if (ex is ServerException)
            {
                ServerException svex = ex as ServerException;
                if (svex != null)
                {
                    errorText.Append("\t");
                    // 関連付け ID (Correlation ID)
                    errorText.Append(svex.ServerErrorTraceCorrelationId);
                }
            }
            return errorText.ToString();
        }
 

 

詳細説明

上記サンプル コードで取得している情報について詳細を記載いたします。

 

1. 現象が発生した日付と時刻

エラーが発生した日時の情報は、カスタム アプリケーション側でエラーに直面した際の情報と関連付けを行うにあたり非常に重要です。

サンプル コード内では日時データを採取しておりませんが、DateTime.Now.ToString() などで構いませんのでログ取得を実施ください。

なお、SharePoint Online においては、データセンター側のログ保存期間もありますため、現象発生後期間が経過しているかどうかを確認する上で重要となります。

現象発生から 1 日以上経過している場合などにおいてはログ調査できない可能性があります。現象発生時には、なるべく早くご連絡ください。

 

2. エラー メッセージ

エラー メッセージは、エラー発生内容の概要を確認するために重要となります。

エラーの種類 (Exception の型) を問わず取得できるため、必ず取得しておく必要があります。

 

3. 呼び出し先 URL

特にマルチテナントに対してサービスを提供するアプリケーションでは、アプリケーション側で失敗したログが、どのテナントに対する処理であったかを区別する必要があります。

呼び出し先 URL のホスト部分には、ホスト URL が含まれますので調査に有効な情報となります。

 

4. HTTP ステータス コード

上記 2. で取得しているエラーメッセージには同様の情報が含まれる可能性があります。しかし、念のため HTTP ステータス コードはエラーの種類を特定するために有効です。

 

5. 関連付け ID (Correlation ID)

データセンター側のログを確認する上で、最も重要な情報となります。

関連付け ID (Correlation ID) は、すべての HTTP 要求に対して採番される GUID 型の一意なデータであり、HTTP 応答ヘッダーに以下のように記載されます。

 SPRequestGuid: 7e12d79d-60a7-3000-0090-fe30bacd1132

この情報は発生現象のログと照合するために必須の情報となります。

 

参考 : ClientContext.TraceCorrelationId プロパティについて

ClientContext.TraceCorrelationId は関連付け ID を返すプロパティですが、以前本ブログで例外発生時に null が返る旨記載しておりました。最新版の CSOM ライブラリでは本現象は修正されていることを確認しておりますので併せてご検討ください。

タイトル : ClientRuntimeContext.TraceCorrelationId property
アドレス : https://msdn.microsoft.com/en-us/library/office/jj168853.aspx