使用適用于 .NET 的用戶端程式庫進行用戶端記錄

發行項
06/27/2023

使用適用于 .NET 的 Azure 儲存體用戶端程式庫 (2.1 版和更新版本) ，您可以使用標準 .NET 診斷基礎結構，從 .NET 用戶端應用程式內記錄 Azure 儲存體要求。如此一來，您可以看到用戶端傳送至 Azure 儲存體服務的要求詳細資料，以及其收到的回應。

Azure 儲存體用戶端程式庫可讓您控制您可以記錄的儲存體要求，而 .NET 診斷基礎結構可讓您完全控制記錄資料，例如傳送位置。例如，您可以選擇將記錄資料傳送至檔案或應用程式進行處理。結合 Azure 儲存體分析和網路監視，您可以使用用戶端程式庫記錄來建置應用程式如何與 Azure 儲存體服務互動的詳細圖片。如需詳細資訊，請參閱監視、診斷和疑難排解 Azure 儲存體。

如何啟用用戶端程式庫記錄

以下範例顯示要收集並將儲存體記錄訊息保存到文字檔所需的 system.diagnostics 設定。組態區段可以新增至 app.config 或 web.config 檔案。

注意

如果您使用 10.0.0 之前的版本，請使用名稱 Microsoft.WindowsAzure.Storage ，而不是 Microsoft.Azure.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>

注意

.NET Framework 4.6.1-4.7.1 版的使用者 (內含) 在使用 Azure 儲存體程式庫的 .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。您可以使用組態設定來啟用用戶端追蹤 (，並針對用戶端中的所有儲存體作業指定層級，例如 詳細資訊) 。

識別碼	記錄層級	事件
0	關閉	不記錄任何訊息。
1	錯誤	如果無法在內部處理例外狀況，而且擲回給使用者，則會將其記錄為錯誤。
2	警告	如果在內部攔截並處理例外狀況，則會將其記錄為警告。此記錄層級的主要使用案例是重試案例，其中例外狀況不會擲回給使用者重試。此行為也可以在 CreateIfNotExists 之類的作業中發生，其中 404 錯誤會以無訊息方式處理。
3	資訊	系統會記錄下列資訊： •在使用者呼叫方法來啟動作業之後，系統會記錄要求詳細資料，例如 URI 和用戶端要求識別碼。 •傳送要求開始/結束、上傳資料開始/結束、接收回應開始/結束、下載資料開始/結束等重要里程碑會記錄為時間戳記。 •在收到標頭之後，系統會記錄要求識別碼和 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之用戶端要求識別碼的作業所產生的用戶端記錄檔擷取。用戶端要求識別碼是相互關聯識別碼，可讓記錄在用戶端的訊息與網路追蹤和儲存體記錄相互關聯。如需相互關聯的詳細資訊，請參閱監視、診斷和疑難排解 Azure 儲存體。擷取內容包含可在記錄檔中觀察到的某些重要資訊的評論 (內縮並斜體)。

若要使用下列記錄檔的第一個資料列來說明這項功能，欄位如下：

記錄欄位	值
來源	Microsoft Azure 儲存體
詳細程度	資訊
詳細資訊號碼	3
用戶端要求識別碼	c3aa328b...
作業內容	從主要位置開始作業 (依據位置模式 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.
上述追蹤訊息顯示作業已順利完成。

下列兩個詳細資訊 (層級 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) 、用戶端要求識別碼、時間戳記、SDK 版本和其他作業特定資料。

共用方式為

使用適用于 .NET 的用戶端程式庫進行用戶端記錄

如何啟用用戶端程式庫記錄

用戶端記錄結構描述和範例

其他資源