Partager via

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

  • Article

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.

Notes

Si vous utilisez une version antérieure à 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

Les utilisateurs de .NET Framework sur les versions 4.6.1-4.7.1 (inclusives) 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 prise en charge des versions de .NET Standard.

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.

Important

Le chemin d’accès complet du 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 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.

Id Niveau du journal Événements
0 Désactivé 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 enregistrée en tant qu’erreur.
2 Avertissement Si une exception est interceptée et gérée en interne, elle est journalisée en tant qu’avertissement. Le principal cas d’usage de ce niveau de journalisation est le scénario de nouvelle tentative, où une exception n’est pas renvoyée à l’utilisateur pour effectuer une nouvelle tentative. 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 consigné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 consignés.

•Les jalons importants tels que l’envoi de la demande début/fin, le début/la fin du chargement des données, le début/la fin de la réponse de réception, le début/la fin du téléchargement des données sont consignés pour marquer les horodatages.

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

•Si une opération échoue et que le client de stockage décide de réessayer, la raison de cette décision est journalisée, ainsi que des informations sur le moment où la prochaine nouvelle tentative se produira.

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

•Chaîne à signer pour chaque demande.

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

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 :

Champ Journal Valeur
Source Microsoft.Azure.Storage
Verbosité Information
Verbosity No 3
ID de demande client c3aa328b...
Texte de l’opération 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 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.