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

Article
02/21/2017

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

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

概要

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

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

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

関連付け ID について

概要

サンプルコード

詳細説明

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

Additional resources

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

関連付け ID について

概要

サンプル コード

詳細説明

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

Additional resources

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

サンプルコード