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

Avec la bibliothèque cliente Stockage Azure pour .NET (version 2.1 et ultérieures), vous pouvez enregistrer les demandes de stockage Azure à partir de votre application cliente .NET à l’aide de l’infrastructure .NET diagnostics standard. De cette façon, vous pouvez voir les détails des demandes que votre client envoie aux services de stockage Azure et les réponses qu’il reçoit.

La bibliothèque cliente stockage Azure vous permet de contrôler les demandes de stockage que vous pouvez enregistrer, et l’infrastructure .NET diagnostics vous donne un contrôle total sur les données de journal, par exemple où les envoyer. Par exemple, vous pouvez choisir d’envoyer les données de journal à un fichier ou à une application à des fins de traitement. En combinaison avec azure Storage Analytics et la surveillance réseau, vous pouvez utiliser la journalisation de bibliothèque de client 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 de Stockage Azure.

Comment activer la journalisation des bibliothèques clientes

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 aux fichiers app.config ou web.config.

<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>  
  

Cet exemple configure la bibliothèque cliente pour écrire des messages de journal dans le fichier C:\logs\WebRole.logphysique . Vous pouvez également utiliser d’autres écouteurs de trace, 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.

En outre, vous pouvez définir autoflush sur true afin d’é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 de faibles volumes de messages de trace, mais dans un environnement de production, vous pouvez définir autoflush sur false. Vous utilisez les paramètres de configuration pour activer le suivi du client (et pour spécifier le niveau, par exemple, détaillé, pour tous les messages) pour toutes les opérations de stockage dans le client.

Par défaut, la bibliothèque cliente consigne 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 règle générale, après avoir activé le suivi côté client dans le fichier de configuration, vous le désactivez 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 inclut 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 traces réseau et les journaux de stockage. Pour plus d’informations sur la corrélation, consultez Surveiller, diagnostiquer et dépanner stockage Azure. 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 :

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
Le message de trace précédent indique que le mode d’emplacement est défini uniquement sur principal, ce qui signifie qu’une demande ayant échoué ne sera 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 requête 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 trace précédent inclut les informations StringToSign, qui sont utiles pour le débogage des échecs d’authentification. Les messages détaillés contiennent également des détails complets sur la demande, notamment le type d’opération et les paramètres de demande.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
Le message de trace 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 trace précédent indique que la réponse a été reçue et son code http status.
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 trace 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 un HEAD et une demande 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 trace précédent affiche le champ OperationText dans les messages de trace détaillés, y compris des 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 SDK et des données supplémentaires spécifiques à l’opération.