Journalisation côté client avec la bibliothèque cliente pour .NET

Avec la bibliothèque cliente de stockage Azure pour .NET (version 2,1 et versions ultérieures), vous pouvez consigner les demandes de stockage Azure à partir de votre application cliente .NET à l’aide de l’infrastructure de Diagnostics .NET standard. De cette façon, vous pouvez afficher les détails des demandes envoyées par votre client aux services de stockage Azure et les réponses qu’il reçoit.

La bibliothèque cliente de stockage Azure vous permet de contrôler les demandes de stockage que vous pouvez journaliser, et l’infrastructure de Diagnostics .NET vous donne un contrôle total sur les données du journal, telles que l’emplacement où l’envoyer. Par exemple, vous pouvez choisir d’envoyer les données du journal à un fichier ou à une application en vue de leur traitement. En association avec la Azure Storage Analytics et la surveillance réseau, vous pouvez utiliser la journalisation de la bibliothèque cliente pour créer une image détaillée de la façon dont votre application interagit avec les services de stockage Azure. Pour plus d’informations, consultez surveiller, diagnostiquer et résoudre les problèmes liés à Azure Storage.

Comment activer la journalisation de la bibliothèque cliente

L'exemple suivant montre la configuration system.diagnostics nécessaire pour collecter et conserver les messages du journal de stockage dans un fichier texte. La section de configuration peut être ajoutée à des fichiers app.config ou web.config.

Notes

Si vous utilisez une version antérieure à la version 10.0.0, utilisez le nom Microsoft.WindowsAzure.Storage au lieu de 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>  
  

Notes

.NET Framework les utilisateurs des versions 4.6.1-4.7.1 (inclusivement) peuvent rencontrer des problèmes de journalisation lors de l’utilisation des artefacts .NET Standard 2,0 des bibliothèques de stockage Azure, qui peuvent être automatiquement sélectionnés par le gestionnaire de package NuGet de Visual Studio. Les bibliothèques sont également publiées en tant qu’artefacts .NET Framework 4.5.2, qui ne rencontrent pas ces problèmes. Pour plus d’informations, consultez à propos de la prise en charge des versions .NET standard.

Cet exemple configure la bibliothèque cliente pour écrire des messages de journal dans le fichier physique C:\logs\WebRole.log . Vous pouvez également utiliser d’autres écouteurs de suivi tels que EventLogTraceListener pour écrire dans le journal des événements Windows, ou EventProviderTraceListener pour écrire des données de trace dans le sous-système ETW.

Important

Le chemin d’accès complet du dossier pour le fichier journal doit exister sur le système de fichiers local. Dans cet exemple, cela signifie que vous devez d’abord créer le C:\logs dossier avant d’écrire des journaux dans un fichier dans ce dossier.

En outre, vous pouvez affecter à AutoFlush la valeur true pour écrire immédiatement les entrées de journal dans le fichier au lieu de les mettre en mémoire tampon. Ce paramètre peut être utile dans un environnement de développement/test avec un faible volume de messages de trace, mais dans un environnement de production, vous pouvez affecter à AutoFlush la valeur false. Vous utilisez les paramètres de configuration pour activer le traçage client (et pour spécifier le niveau, tel que Verbose, pour tous les messages) pour toutes les opérations de stockage dans le client.

Id Niveau du journal Événements
0 Off Rien n'est journalisé.
1 Error Si une exception ne peut pas être gérée en interne et est levée pour l’utilisateur, elle est consignée comme une erreur.
2 Avertissement Si une exception est interceptée et gérée en interne, elle est enregistrée en tant qu’avertissement. Le cas d’usage principal pour ce niveau de journal est le scénario de nouvelle tentative, où une exception n’est pas renvoyée à l’utilisateur pour réessayer. Ce comportement peut également se produire dans des opérations telles que CreateIfNotExists, où l’erreur 404 est gérée en mode silencieux.
3 Informationnel Les informations suivantes sont enregistrées :

• Juste après que l’utilisateur a appelé une méthode pour démarrer une opération, les détails de la demande, tels que l’URI et l’ID de demande client, sont journalisés.

• Les étapes majeures importantes, telles que l’envoi de début/fin de demande, le chargement des données par le début/la fin, la réception de la réponse en début/fin, le téléchargement des données en début/fin sont journalisées pour marquer les horodateurs.

• Juste après la réception des en-têtes, les détails de la réponse, tels que l’ID de la demande et le code d’état HTTP, sont journalisés.

• Si une opération échoue et que le client de stockage décide de réessayer, la raison de cette décision est enregistrée avec les informations relatives au moment où la prochaine tentative aura lieu.

• Tous les délais d’expiration côté client sont consignés lorsqu’un client de stockage décide d’abandonner une demande en attente.
4 Commentaires Les informations suivantes sont enregistrées :

• Chaîne de signature pour chaque demande.

• Détails supplémentaires spécifiques aux opérations (jusqu’à chaque opération à définir et utiliser).

Par défaut, la bibliothèque cliente enregistre dans le journal les détails de toutes les opérations de stockage au niveau de détail que vous spécifiez dans le fichier de configuration. Vous pouvez également limiter la journalisation à des zones spécifiques de votre application cliente pour réduire la quantité de données journalisées et vous aider à trouver les informations dont vous avez besoin. Pour limiter la quantité de données écrites dans les journaux, vous devez ajouter du code à votre application cliente. En général, après avoir activé le suivi côté client dans le fichier de configuration, vous pouvez le désactiver globalement dans le code à l’aide de la classe OperationContext . Par exemple, vous pouvez le faire dans une application ASP.NET MVC dans la méthode Application_Start avant que votre application effectue des opérations de stockage :

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

Vous pouvez ensuite activer le suivi pour les opérations spécifiques qui vous intéressent en créant un objet OperationContext personnalisé qui définit le niveau de journalisation. Ensuite, transmettez l’objet OperationContext en tant que paramètre à la méthode Execute que vous utilisez pour appeler une opération de stockage, comme dans l’exemple suivant :

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

Schéma de journal côté client et exemple

L’exemple suivant est un extrait du journal côté client généré par la bibliothèque cliente pour une opération avec un ID de demande client qui comprend c3aa328b. L’ID de demande client est un identificateur de corrélation qui permet aux messages enregistrés côté client d’être corrélés avec les suivis réseau et les journaux de stockage. Pour plus d’informations sur la corrélation, consultez surveiller, diagnostiquer et résoudre les problèmes liés à Azure Storage. L'extrait comprend des commentaires (en retrait et en italique) sur certaines informations clés qui peuvent être observées dans les fichiers journaux.

Pour illustrer cette fonctionnalité à l’aide de la première ligne du fichier journal suivant, les champs sont les suivants :

Source Microsoft.Azure.Storage
Commentaires Information
Verbosity No 3
ID de la demande client c3aa328b...
Operation Text Démarrage de l'opération avec l'emplacement Primary par mode d'emplacement PrimaryOnly.

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
Le message de suivi précédent indique que le mode d’emplacement est défini sur principal uniquement, ce qui signifie qu’une demande ayant échoué n’est pas envoyée à un emplacement secondaire.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
Le message de trace précédent indique que la demande est synchrone.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
Le message de trace précédent indique que la réponse doit être retournée au format JSON.
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
Le message de suivi précédent comprend les informations de StringToSign, qui sont utiles pour le débogage des échecs d’authentification. Les messages détaillés contiennent également des détails complets sur les demandes, y compris le type d’opération et les paramètres de demande.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
Le message de suivi précédent indique que la demande a été envoyée et que le client attend une réponse.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
Le message de suivi précédent indique que la réponse a été reçue et son code d’État 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 ''.
Le message de suivi précédent indique que 8 résultats ont été récupérés et qu’aucun jeton de continuation n’a été fourni, ce qui signifie qu’il n’y a plus de résultats pour cette requête.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
Le message de trace précédent indique que l’opération s’est terminée avec succès.

Les deux entrées de journal détaillées (niveau 4) suivantes affichent une demande HEAD et DELETE et illustrent les informations détaillées dans le champ texte de l' opération :
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.
Le message de suivi précédent montre le champ OperationText dans les messages de suivi détaillé, y compris les informations détaillées relatives à une demande spécifique. Ces détails incluent le type d’opération HTTP (par exemple, HEAD, DELETE, POST), l’ID de demande client, l’horodatage, la version du kit de développement logiciel (SDK) et des données supplémentaires spécifiques à l’opération.