.NET 用クライアントライブラリを使用したクライアント側のログ記録

[アーティクル]
06/27/2023

.NET 用 Azure Storage クライアントライブラリ (バージョン 2.1 以降) を使用すると、標準の .NET 診断インフラストラクチャを使用して、.NET クライアントアプリケーション内から Azure Storage 要求をログに記録できます。この方法では、クライアントが Azure Storage サービスに送信する要求と、クライアントが受信した応答の詳細を確認できます。

Azure Storage クライアントライブラリを使用すると、ログに記録できるストレージ要求を制御できます。.NET 診断インフラストラクチャでは、ログデータの送信先など、ログデータを完全に制御できます。たとえば、ログデータをファイルまたはアプリケーションに送信して処理することができます。 Azure Storage Analyticsおよびネットワーク監視と組み合わせて、クライアントライブラリログを使用して、アプリケーションが Azure Storage サービスとどのように対話するかを詳しく把握できます。詳細については、「 Azure Storage の監視、診断、トラブルシューティング」を参照してください。

クライアントライブラリのログ記録を有効にする方法

次の例では、ストレージログメッセージを回収し、テキストファイルに保存するために必要な system.diagnostics 構成を示します。構成セクションは、app.config ファイルまたは web.config ファイルに追加できます。

注意

10.0.0 より前のバージョンを使用している場合は、の代わりに Microsoft.Azure.Storage名前を使用しますMicrosoft.WindowsAzure.Storage。

<system.diagnostics>  
     <!--In a dev/test environment you can set autoflush to true in order to autoflush to the log file. -->  
  <trace autoflush="false">  
    <listeners>  
      ...
      <add name="storageListener" />  
    </listeners>  
  </trace>  
  <sources>  
    <source name="Microsoft.Azure.Storage">  
      <listeners>  
        <add name="storageListener"/>  
      </listeners>  
    </source>  
  </sources>  
  <switches>  
    <add name="Microsoft.Azure.Storage" value="Verbose" />  
  </switches>  
  <sharedListeners>  
    <add name="storageListener"  
      type="System.Diagnostics.TextWriterTraceListener"  
      initializeData="C:\logs\WebRole.log"
      traceOutputOptions="DateTime" />  
  </sharedListeners>  
</system.diagnostics>

注意

バージョン 4.6.1 から 4.7.1 (含む) のユーザー.NET Framework、Azure Storage ライブラリの .NET Standard 2.0 成果物を使用するときにログの問題が発生する可能性があります。これは、Visual Studio の NuGet パッケージマネージャーによって自動的に選択される可能性があります。ライブラリは、.NET Framework 4.5.2 成果物としても公開されており、これらの問題は発生しません。詳細については、 .NET Standard バージョンのサポートに関するページを参照してください。

この例では、物理ファイル C:\logs\WebRole.logにログメッセージを書き込むクライアントライブラリを構成します。 EventLogTraceListener などの他のトレースリスナーを使用して Windows イベントログに書き込んだり、EventProviderTraceListener を使用してトレースデータを ETW サブシステムに書き込んだりすることもできます。

重要

ログファイルの完全なフォルダーパスは、ローカルファイルシステムに存在する必要があります。この例では、そのフォルダー内のファイルにログを C:\logs 書き込む前に、まずフォルダーを作成する必要があることを意味します。

さらに、ログエントリをバッファー処理するのではなく、ファイルにすぐに書き込むために autoflush を true に設定できます。この設定は、トレースメッセージの量が少ない開発/テスト環境で役立ちますが、運用環境では autoflush を false に設定することをお勧めします。構成設定を使用して、クライアント内のすべてのストレージ操作に対してクライアントトレースを有効にします (また、すべてのメッセージに対して Verbose などのレベルを指定する場合)。

Id	ログレベル	イベント
0	オフ	ログには何も記録されません。
1	エラー	内部的に処理できない例外がユーザーにスローされた場合は、エラーとしてログに記録されます。
2	警告	例外がキャッチされ、内部的に処理された場合は、警告としてログに記録されます。このログレベルの主なユースケースは再試行シナリオであり、再試行のために例外がユーザーにスローされません。この動作は、404 エラーがサイレント処理される CreateIfNotExists などの操作でも発生する可能性があります。
3	Informational	次の情報がログに記録されます。 •ユーザーがメソッドを呼び出して操作を開始した直後に、URI やクライアント要求 ID などの要求の詳細がログに記録されます。 •送信要求の開始/終了、データの開始/終了のアップロード、応答の開始/終了の受信、データの開始/終了のダウンロードなどの重要なマイルストーンが、タイムスタンプをマークするためにログに記録されます。 •ヘッダーを受信した直後に、要求 ID や HTTP 状態コードなどの応答の詳細がログに記録されます。 •操作が失敗し、ストレージクライアントが再試行を決定した場合、その決定の理由と、次の再試行がいつ行われるかについての情報がログに記録されます。 •ストレージクライアントが保留中の要求を中止することを決定すると、すべてのクライアント側タイムアウトがログに記録されます。
4	"詳細"	次の情報がログに記録されます。 •各要求の文字列から署名へ。 •操作に固有の追加の詳細 (定義および使用する各操作まで)。

既定では、クライアントライブラリは、構成ファイルで指定した詳細レベルですべてのストレージ操作の詳細をログに記録します。また、ログ記録をクライアントアプリケーションの特定の領域に制限して、ログに記録されるデータの量を減らし、必要な情報を見つけるのに役立てることもできます。ログに書き込まれるデータの量を制限するには、クライアントアプリケーションにコードを追加する必要があります。通常、構成ファイルでクライアント側トレースを有効にした後、 OperationContext クラスを使用してコード内でグローバルにオフにします。たとえば、アプリケーションがストレージ操作を実行する前に、Application_Start メソッドの ASP.NET MVC アプリケーションでこれを行うことができます。

protected void Application_Start()  
{  
    ...  
  
    // Disable Default Logging for Windows Azure Storage  
    OperationContext.DefaultLogLevel = LogLevel.Off;  
  
    // Verify that all of the tables, queues, and blob containers used in this application  
    // exist, and create any that don't already exist.  
    CreateTablesQueuesBlobContainers();  
}

その後、ログレベルを定義するカスタム OperationContext オブジェクトを作成することで、関心のある特定の操作のトレースを有効にすることができます。次に、次の例のように、 OperationContext オブジェクトをパラメーターとして、ストレージ操作の呼び出しに使用する Execute メソッドに渡します。

[HttpPost]  
[ValidateAntiForgeryToken]  
public ActionResult Create(Subscriber subscriber)  
{  
    if (ModelState.IsValid)  
    {  
       ...  
        var insertOperation = TableOperation.Insert(subscriber);  
        OperationContext verboseLoggingContext = new OperationContext() { LogLevel = LogLevel.Verbose };  
        mailingListTable.Execute(insertOperation, null, verboseLoggingContext);  
        return RedirectToAction("Index");  
    }  
  
    ...  
    return View(subscriber);  
}

クライアント側のログスキーマとサンプル

次の例は、 c3aa328b を含むクライアント要求 ID を持つ操作について、クライアントライブラリによって生成されたクライアント側ログからの抽出です。クライアント要求 ID は、クライアント側でログに記録されたメッセージをネットワークトレースとストレージログと関連付けできるようにする関連付け識別子です。関連付けの詳細については、「 Azure Storage の監視、診断、トラブルシューティング」を参照してください。この抜粋には、ログファイルで気付く一部の主要情報に関する解説が含まれます (斜体で字下げされます)。

次のログファイルの最初の行を使用してこの機能を説明するために、フィールドは次のとおりです。

ログフィールド	値
ソース	Microsoft.Azure.Storage
Verbosity	Information
詳細度の数	3
クライアント要求 ID	c3aa328b...
[操作テキスト]	場所 Primary、場所モード PrimaryOnly で操作を開始しています。

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
上記のトレースメッセージは、場所モードがプライマリのみに設定されていることを示しています。つまり、失敗した要求はセカンダリの場所に送信されません。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
上記のトレースメッセージは、要求が同期的であることを示しています。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
上記のトレースメッセージは、応答が JSON 形式で返されることを示しています。
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
上記のトレースメッセージには、認証エラーのデバッグに役立つ StringToSign 情報が含まれています。詳細メッセージには、操作の種類や要求パラメーターなど、要求の完全な詳細も含まれます。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
上記のトレースメッセージは、要求が送信され、クライアントが応答を待機していることを示しています。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
上記のトレースメッセージは、応答が受信され、その http 状態コードが示されています。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response headers were processed successfully, proceeding with the rest of the operation.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Processing response body.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Retrieved '8' results with continuation token ''.
上記のトレースメッセージは、8 つの結果が取得され、継続トークンが指定されていないことを示しています。つまり、このクエリの結果はこれ以上ありません。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
上記のトレースメッセージは、操作が正常に完了したことを示しています。

次の 2 つの詳細 (レベル 4) ログエントリは、HEADと DELETE 要求を示し、[操作テキスト] フィールドの詳細情報を示しています。
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = HEAD............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:11 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = DELETE............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:12 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
上記のトレースメッセージは、特定の要求に関連する詳細情報を含む詳細なトレースメッセージ内の OperationText フィールドを示しています。これらの詳細には、HTTP 操作の種類 (HEAD、DELETE、POST など)、クライアント要求 ID、タイムスタンプ、SDK バージョン、追加の操作固有のデータが含まれます。

.NET 用クライアント ライブラリを使用したクライアント側のログ記録

クライアント ライブラリのログ記録を有効にする方法

クライアント側のログ スキーマとサンプル

その他のリソース

.NET 用クライアントライブラリを使用したクライアント側のログ記録

クライアントライブラリのログ記録を有効にする方法

クライアント側のログスキーマとサンプル