Clientseitige Protokollierung mit der Clientbibliothek für .NET

Artikel
08/05/2023

Mit der Azure Storage-Clientbibliothek für .NET (Version 2.1 und höher) können Sie Azure Storage-Anforderungen in Ihrer .NET-Clientanwendung mithilfe der standardmäßigen .NET-Diagnose-Infrastruktur protokollieren. Auf diese Weise können Sie Details der Anforderungen anzeigen, die Ihr Client an Azure Storage-Dienste sendet, und die Antworten, die er empfängt.

Die Azure Storage-Clientbibliothek gibt Ihnen die Kontrolle darüber, welche Speicheranforderungen Sie protokollieren können, und die .NET-Diagnose-Infrastruktur gibt Ihnen die vollständige Kontrolle über die Protokolldaten, z. B. wohin sie gesendet werden sollen. Beispielsweise können Sie die Protokolldaten zur Verarbeitung an eine Datei oder an eine Anwendung senden. In Kombination mit Azure Storage Analytics und Netzwerküberwachung können Sie die Clientbibliotheksprotokollierung verwenden, um ein detailliertes Bild der Interaktion Ihrer Anwendung mit Azure Storage-Diensten zu erstellen. Weitere Informationen finden Sie unter Überwachen, Diagnostizieren und Problembehandlung für Azure Storage.

Aktivieren der Clientbibliotheksprotokollierung

Das folgende Beispiel zeigt die system.diagnostics-Konfiguration, die erforderlich ist, um Meldungen des Speicherprotokolls zu erfassen und persistent in einer Textdatei zu speichern. Der Konfigurationsabschnitt kann entweder app.config- oder web.config-Dateien hinzugefügt werden.

Hinweis

Wenn Sie eine ältere Version als 10.0.0 verwenden, verwenden Sie den Namen Microsoft.WindowsAzure.Storage anstelle von 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>

Hinweis

.NET Framework Benutzern in den Versionen 4.6.1-4.7.1 (einschließlich) können Protokollierungsprobleme auftreten, wenn die .NET Standard 2.0-Artefakte der Azure Storage-Bibliotheken verwendet werden, die möglicherweise automatisch vom NuGet-Paket-Manager von Visual Studio ausgewählt werden. Die Bibliotheken werden auch als .NET Framework 4.5.2-Artefakte veröffentlicht, bei denen diese Probleme nicht auftreten. Weitere Informationen finden Sie unter Unterstützung der .NET Standard-Version.

In diesem Beispiel wird die Clientbibliothek so konfiguriert, dass Protokollnachrichten in die physische Datei C:\logs\WebRole.loggeschrieben werden. Sie können auch andere Ablaufverfolgungslistener wie den EventLogTraceListener verwenden, um in das Windows-Ereignisprotokoll zu schreiben, oder den EventProviderTraceListener , um Ablaufverfolgungsdaten in das ETW-Subsystem zu schreiben.

Wichtig

Der vollständige Ordnerpfad für die Protokolldatei muss im lokalen Dateisystem vorhanden sein. In diesem Beispiel bedeutet dies, dass Sie zuerst den C:\logs Ordner erstellen müssen, bevor Sie Protokolle in eine Datei in diesem Ordner schreiben.

Darüber hinaus können Sie autoflush auf true festlegen, um die Protokolleinträge sofort in die Datei zu schreiben, anstatt sie zu puffern. Diese Einstellung kann in einer Entwicklungs-/Testumgebung mit geringen Mengen an Ablaufverfolgungsmeldungen nützlich sein, aber in einer Produktionsumgebung sollten Sie autoflush auf false festlegen. Sie verwenden die Konfigurationseinstellungen, um die Clientablaufverfolgung für alle Speichervorgänge im Client zu aktivieren (und die Ebene , z. B . Ausführlich, für alle Nachrichten anzugeben).

Id	Protokollebene	Ereignisse
0	Aus	Es wird nichts protokolliert.
1	Fehler	Wenn eine Ausnahme nicht intern behandelt werden kann und für den Benutzer ausgelöst wird, wird sie als Fehler protokolliert.
2	Warnung	Wenn eine Ausnahme intern abgefangen und behandelt wird, wird sie als Warnung protokolliert. Der primäre Anwendungsfall für diese Protokollebene ist das Wiederholungsszenario, bei dem keine Ausnahme an den Benutzer zurückgegeben wird, um es erneut zu versuchen. Dieses Verhalten kann auch in Vorgängen wie CreateIfNotExists auftreten, bei denen der Fehler 404 unbeaufsichtigt behandelt wird.
3	Informational	Die folgenden Informationen werden protokolliert: •Direkt nachdem der Benutzer eine Methode zum Starten eines Vorgangs aufgerufen hat, werden Anforderungsdetails wie URI und Clientanforderungs-ID protokolliert. •Wichtige Meilensteine wie Senden der Anforderung Start/End, Upload Data Start/End, Empfang der Antwort start/end, Download Data Start/End werden protokolliert, um die Zeitstempel zu markieren. •Direkt nach dem Empfang der Header werden Antwortdetails wie Anforderungs-ID und HTTP-status Code protokolliert. •Wenn ein Vorgang fehlschlägt und der Speicherclient beschließt, es erneut zu versuchen, wird der Grund für diese Entscheidung zusammen mit Informationen darüber protokolliert, wann die nächste Wiederholung durchgeführt wird. •Alle clientseitigen Timeouts werden protokolliert, wenn ein Speicherclient entscheidet, eine ausstehende Anforderung abzubrechen.
4	Ausführlich	Die folgenden Informationen werden protokolliert: •Zeichenfolgen-zu-Sign für jede Anforderung. •Alle zusätzlichen Details, die für Vorgänge spezifisch sind (bis zu jedem Vorgang, der definiert und verwendet werden soll).

Standardmäßig protokolliert die Clientbibliothek Details aller Speichervorgänge auf der Ausführlichkeitsebene, die Sie in der Konfigurationsdatei angeben. Sie können die Protokollierung auch auf bestimmte Bereiche Ihrer Clientanwendung beschränken, um die Menge der protokollierten Daten zu reduzieren und die benötigten Informationen zu finden. Um die Menge der in die Protokolle geschriebenen Daten zu begrenzen, müssen Sie Ihrer Clientanwendung Code hinzufügen. Nach dem Aktivieren der clientseitigen Ablaufverfolgung in der Konfigurationsdatei schalten Sie diese in der Regel global im Code aus, indem Sie die OperationContext-Klasse verwenden. Sie können dies beispielsweise in einer ASP.NET MVC-Anwendung in der Application_Start-Methode tun, bevor Ihre Anwendung Speichervorgänge ausführt:

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();  
}

Anschließend können Sie die Ablaufverfolgung für die spezifischen Vorgänge aktivieren, die Sie interessieren, indem Sie ein benutzerdefiniertes OperationContext-Objekt erstellen, das die Protokollierungsebene definiert. Übergeben Sie dann das OperationContext-Objekt als Parameter an die Execute-Methode , die Sie zum Aufrufen eines Speichervorgangs verwenden, wie im folgenden Beispiel gezeigt:

[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);  
}

Clientseitiges Protokollschema und Beispiel

Das folgende Beispiel ist ein Extrakt aus dem clientseitigen Protokoll, das von der Clientbibliothek für einen Vorgang mit einer Clientanforderungs-ID generiert wird, die c3aa328b enthält. Die Clientanforderungs-ID ist ein Korrelationsbezeichner, mit dem clientseitig protokollierte Nachrichten mit Netzwerkablaufverfolgungen und Speicherprotokollen korreliert werden können. Weitere Informationen zur Korrelation finden Sie unter Überwachen, Diagnostizieren und Problembehandlung für Azure Storage. Der Protokollauszug enthält Kommentare (eingezogen und kursiv) zu einigen Schlüsselinformationen, die in den Protokolldateien enthalten sind.

Um diese Funktionalität mithilfe der ersten Zeile der folgenden Protokolldatei zu veranschaulichen, sind die Felder:

Protokollfeld	Wert
Quelle	Microsoft.Azure.Storage
Verbosity	Information
Ausführlichkeit nein	3
Clientanforderungs-ID	c3aa328b...
Vorgang Text	Vorgang mit Primärspeicherort pro Speicherortmodus PrimaryOnly starten.

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
Die vorherige Ablaufverfolgungsmeldung zeigt, dass der Standortmodus nur auf primär festgelegt ist, was bedeutet, dass eine fehlerhafte Anforderung nicht an einen sekundären Speicherort gesendet wird.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
Die vorherige Ablaufverfolgungsmeldung zeigt, dass die Anforderung synchron ist.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
Die vorherige Ablaufverfolgungsmeldung zeigt, dass die Antwort als JSON formatiert zurückgegeben werden soll.
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
Die vorherige Ablaufverfolgungsmeldung enthält die StringToSign-Informationen, die zum Debuggen von Authentifizierungsfehlern nützlich sind. Ausführliche Nachrichten enthalten auch vollständige Anforderungsdetails, einschließlich Vorgangstyp und Anforderungsparametern.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
Die vorherige Ablaufverfolgungsmeldung zeigt, dass die Anforderung gesendet wurde und der Client auf eine Antwort wartet.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
Die vorherige Ablaufverfolgungsmeldung zeigt, dass die Antwort empfangen wurde und ihr HTTP-status Code.
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 ''.
Die vorherige Ablaufverfolgungsmeldung zeigt, dass 8 Ergebnisse abgerufen und kein Fortsetzungstoken bereitgestellt wurde, was bedeutet, dass es keine weiteren Ergebnisse für diese Abfrage gibt.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
Die vorherige Ablaufverfolgungsmeldung zeigt, dass der Vorgang erfolgreich abgeschlossen wurde.

Die folgenden beiden ausführlichen Protokolleinträge (Ebene 4) zeigen eine HEAD- und eine DELETE-Anforderung an und veranschaulichen die detaillierten Informationen im Feld Vorgangstext:
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.
Die vorherige Ablaufverfolgungsmeldung zeigt das Feld OperationText in ausführlichen Ablaufverfolgungsmeldungen, einschließlich detaillierter Informationen zu einer bestimmten Anforderung. Zu diesen Details gehören der HTTP-Vorgangstyp (z. B. HEAD, DELETE, POST), die Clientanforderungs-ID, der Zeitstempel, die SDK-Version und zusätzliche vorgangsspezifische Daten.

Freigeben über

Clientseitige Protokollierung mit der Clientbibliothek für .NET

Aktivieren der Clientbibliotheksprotokollierung

Clientseitiges Protokollschema und Beispiel

Zusätzliche Ressourcen