Configuration de la journalisation des messages

Cette rubrique explique comment configurer la journalisation des messages pour différents scénarios.

Activation de la journalisation des messages

Windows Communication Foundation (WCF) ne journalise pas les messages par défaut. Pour activer la journalisation des messages, vous devez ajouter un écouteur de trace à la System.ServiceModel.MessageLogging source de trace et définir des attributs pour l’élément dans le <messagelogging> fichier de configuration.

L’exemple suivant montre comment activer la journalisation et spécifier des options supplémentaires.

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel.MessageLogging">
      <listeners>
         <add name="messages"
              type="System.Diagnostics.XmlWriterTraceListener"
              initializeData="c:\logs\messages.svclog" />
        </listeners>
    </source>
  </sources>
</system.diagnostics>

<system.serviceModel>
  <diagnostics>
    <messageLogging
         logEntireMessage="true"
         logMalformedMessages="false"
         logMessagesAtServiceLevel="true"
         logMessagesAtTransportLevel="false"
         maxMessagesToLog="3000"
         maxSizeOfMessageToLog="2000"/>
  </diagnostics>
</system.serviceModel>

Pour plus d’informations sur les paramètres de journalisation des messages, consultez Paramètres recommandés pour le suivi et la journalisation des messages.

Vous pouvez utiliser add pour spécifier le nom et le type de l’écouteur que vous souhaitez utiliser. Dans l’exemple de configuration, l’écouteur est nommé « messages » et ajoute l’écouteur de trace .NET Framework standard (System.Diagnostics.XmlWriterTraceListener) comme type à utiliser. Si vous utilisez System.Diagnostics.XmlWriterTraceListener, vous devez spécifier l’emplacement et le nom du fichier de sortie dans le fichier de configuration. Pour ce faire, définissez initializeData le nom du fichier journal. Si cette consigne n'est pas respectée, le système lèvera une exception. Vous pouvez également implémenter un écouteur personnalisé qui enregistrera les journaux dans un fichier par défaut.

Le niveau de journalisation, ainsi que les options supplémentaires, sont abordés dans la section Niveau de journalisation et Options.

L’attribut switchValue d’un source n’est valide que pour le suivi. Si vous spécifiez un switchValue attribut pour la source de System.ServiceModel.MessageLogging trace comme suit, il n’a aucun effet.

<source name="System.ServiceModel.MessageLogging" switchValue="Verbose">
</source>

Si vous souhaitez désactiver la source de trace, vous devez utiliser les attributs logMessagesAtServiceLevel, logMalformedMessages et logMessagesAtTransportLevel de l’élément messageLogging à la place. Vous devez définir tous ces attributs sur false. Pour ce faire, utilisez le fichier de configuration dans l’exemple de code précédent, par le biais de l’interface utilisateur de l’éditeur de configuration ou de WMI. Pour plus d’informations sur l’outil Éditeur de configuration, consultez l’outil Éditeur de configuration (SvcConfigEditor.exe). Pour plus d’informations sur WMI, consultez Utilisation de Windows Management Instrumentation for Diagnostics.

Niveaux et options de journalisation

Pour les messages entrants, la journalisation se produit immédiatement après la formation du message, immédiatement avant que le message ne soit envoyé au code utilisateur au niveau du service et lorsque des messages mal formés sont détectés.

Pour les messages sortants, leur enregistrement intervient immédiatement après leur départ du code utilisateur et immédiatement avant leur transmission.

WCF journalise les messages à deux niveaux différents, service et transport. Les messages mal formés sont également enregistrés. Les trois catégories sont indépendantes les unes des autres et peuvent être activées séparément dans la configuration.

Vous pouvez contrôler le niveau de journalisation en définissant les attributs logMessagesAtServiceLevel, logMalformedMessages, et logMessagesAtTransportLevel de l’élément messageLogging.

Niveau de service

Les messages enregistrés à ce niveau sont ceux qui sont sur le point d'arriver (côté destinataire) dans le code utilisateur ou de quitter ce dernier (côté expéditeur). Si des filtres ont été définis, seuls les messages correspondant aux filtres sont enregistrés. Sinon, tous les messages au niveau du service sont enregistrés. Les messages d’infrastructure (transactions, canal homologue et sécurité) sont également enregistrés à ce niveau, à l’exception des messages de messagerie fiable. Sur les messages diffusés en continu, seuls les en-têtes sont enregistrés. En outre, les messages sécurisés sont déchiffrés à ce niveau.

Niveau de transport

Les messages enregistrés sur cette couche sont prêts à être encodés ou décodés pour ou après le transport sur le câble. Si des filtres ont été définis, seuls les messages correspondant aux filtres sont enregistrés. Sinon, tous les messages au niveau de la couche de transport sont enregistrés. Tous les messages d’infrastructure sont enregistrés sur cette couche, y compris les messages de messagerie fiables. Sur les messages diffusés en continu, seuls les en-têtes sont enregistrés. En outre, les messages sécurisés sont enregistrés comme chiffrés à ce niveau, sauf si un transport sécurisé tel que HTTPS est utilisé.

Niveau erreurs

Les messages mal formés sont des messages rejetés par la pile WCF à n’importe quelle étape du traitement. Les messages mal formés sont enregistrés as-is: chiffrés s’ils le sont, avec du code XML non approprié, et ainsi de suite. maxSizeOfMessageToLog a défini la taille du message à journaliser en tant que CDATA. Par défaut, maxSizeOfMessageToLog est égal à 256 Ko. Pour plus d’informations sur cet attribut, consultez la section Autres options.

Autres options

En plus des niveaux de journalisation, l’utilisateur peut spécifier les options suivantes :

• Log Entire Message (logEntireMessage attribut) : cette valeur spécifie si l’intégralité du message (en-tête et corps du message) est journalisée. La valeur par défaut est false, ce qui signifie que seul l’en-tête est enregistré. Ce paramètre affecte les niveaux de journalisation des messages de service et de transport..

• Nombre maximal de messages à consigner (maxMessagesToLog attribut) : cette valeur spécifie le nombre maximal de messages à consigner. Tous les messages (service, transport et messages mal formés) sont comptabilisés dans ce quota. Lorsque le quota est atteint, une trace est émise et aucun message supplémentaire n’est enregistré. La valeur par défaut est 10 000.

• Taille maximale du message à journaliser (maxSizeOfMessageToLog attribut) : cette valeur spécifie la taille maximale des messages à journaliser en octets. Les messages qui dépassent la limite de taille ne sont pas enregistrés et aucune autre activité n’est effectuée pour ce message. Ce paramètre affecte tous les niveaux de trace. Si le suivi ServiceModel est activé, une trace au niveau avertissement est émise au premier point de journalisation (ServiceModelSend* ou TransportReceive) pour avertir l’utilisateur. La valeur par défaut pour les messages de niveau de service et de transport est de 256 Ko, tandis que la valeur par défaut pour les messages mal formés est 4K.

  Avertissement

  La taille du message, calculée pour être comparée par rapport à maxSizeOfMessageToLog, est la taille du message en mémoire avant la sérialisation. Cette taille peut différer de la longueur réelle de la chaîne de message en cours de journalisation et, dans de nombreuses occasions, est supérieure à la taille réelle. Par conséquent, les messages peuvent ne pas être enregistrés. Vous pouvez tenir compte de ce fait en spécifiant que l’attribut maxSizeOfMessageToLog doit être de 10% supérieur à la taille de message attendue. En outre, si les messages mal formés sont enregistrés, l’espace disque réel utilisé par les journaux des messages peut être jusqu’à 5 fois la taille de la valeur spécifiée par maxSizeOfMessageToLog.

Si aucun écouteur de trace n’est défini dans le fichier de configuration, aucune sortie de journalisation n’est générée quel que soit le niveau de journalisation spécifié.

Les options de journalisation des messages, telles que les attributs décrits dans cette section, peuvent être modifiées au moment de l’exécution à l’aide de Windows Management Instrumentation (WMI). Pour ce faire, accédez à l’instance AppDomainInfo , qui expose ces propriétés booléennes : LogMessagesAtServiceLevel, LogMessagesAtTransportLevelet LogMalformedMessages. Par conséquent, si vous configurez un écouteur de suivi pour la journalisation des messages, mais définissez ces options sur false dans la configuration, vous pouvez les modifier en true ultérieurement lorsque l’application est en cours d’exécution. Cela permet efficacement la journalisation des messages au moment de l’exécution. De même, si vous activez la journalisation des messages dans votre fichier de configuration, vous pouvez la désactiver au moment de l’exécution à l’aide de WMI. Pour plus d’informations, consultez Utilisation de Windows Management Instrumentation for Diagnostics.

Le source champ d’un journal des messages spécifie dans quel contexte le message est journalisé : lors de l’envoi/de la réception d’un message de demande, d’une demande de réponse ou d’une demande 1direction, au niveau du modèle de service ou de la couche de transport, ou dans le cas d’un message mal formé.

Pour les messages mal formés, source est égal à Malformed. Sinon, la source a les valeurs suivantes en fonction du contexte.

Pour la demande/réponse :

Pour une requête unidirectionnelle

Filtres de messages

Les filtres de messages sont définis dans l’élément messageLogging de configuration de la diagnostics section de configuration. Elles sont appliquées au niveau du service et du transport. Quand un ou plusieurs filtres sont définis, seuls les messages correspondant à au moins un des filtres sont enregistrés. Si aucun filtre n’est défini, tous les messages passent.

Les filtres prennent en charge la syntaxe XPath complète et sont appliqués dans l’ordre dans lequel ils apparaissent dans le fichier de configuration. Un filtre syntactiquement incorrect entraîne une exception de configuration.

Les filtres fournissent également une fonctionnalité de sécurité à l’aide de l’attribut nodeQuota , qui limite le nombre maximal de nœuds dans le DOM XPath qui peut être examiné pour correspondre au filtre.

L’exemple suivant montre comment configurer un filtre qui enregistre uniquement les messages qui ont une section d’en-tête SOAP.

<messageLogging logEntireMessage="true"
    logMalformedMessages="true"
    logMessagesAtServiceLevel="true"
    logMessagesAtTransportLevel="true"
    maxMessagesToLog="420">
    <filters>
        <add nodeQuota="10" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
                 /soap:Envelope/soap:Header
        </add>
     </filters>
</messageLogging>

Les filtres ne peuvent pas être appliqués au corps d’un message. Les filtres qui tentent de manipuler le corps d’un message sont supprimés de la liste des filtres. Un événement signalant cette suppression est également déclenché. Par exemple, le filtre suivant est supprimé de la table de filtres.

<add xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">/s:Envelope/s:Body[contains(text(), "Hello")]</add>

Configuration d’un écouteur personnalisé

Vous pouvez également configurer un écouteur personnalisé avec des options supplémentaires. Un écouteur personnalisé peut être utile pour filtrer des éléments PII spécifiques à l’application à partir de messages avant la journalisation. L’exemple suivant illustre une configuration d’écouteur personnalisé.

<system.diagnostics>
   <sources>
     <source name="System.ServiceModel.MessageLogging">
           <listeners>
             <add name="MyListener"
                    type="YourCustomListener"
                    initializeData="c:\logs\messages.svclog"
                    maxDiskSpace="1000"/>
           </listeners>
     </source>
   </sources>
</system.diagnostics>

Vous devez savoir que l’attribut type doit être défini sur un nom d’assembly qualifié du type.

Voir aussi

• <journalisation des messages>
• Journalisation des messages
• Paramètres recommandés pour le suivi et l'enregistrement des messages