Üzenetnaplózás konfigurálása

Cikk
03/02/2024

Ez a témakör azt ismerteti, hogyan konfigurálhatja az üzenetnaplózást különböző helyzetekben.

Üzenetnaplózás engedélyezése

A Windows Communication Foundation (WCF) alapértelmezés szerint nem naplózza az üzeneteket. Az üzenetnaplózás aktiválásához fel kell vennie egy nyomkövetési figyelőt a System.ServiceModel.MessageLogging nyomkövetési forráshoz, és meg kell adnia a <messagelogging> konfigurációs fájlban lévő elem attribútumait.

Az alábbi példa bemutatja, hogyan engedélyezheti a naplózást, és hogyan adhat meg további beállításokat.

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

További információ az üzenetnaplózási beállításokról: Ajánlott Gépház nyomkövetéshez és üzenetnaplózáshoz.

Megadhatja add a használni kívánt figyelő nevét és típusát. A példakonfigurációban a figyelő neve "üzenetek", és a szabványos .NET-keretrendszer nyomkövetési figyelőt (System.Diagnostics.XmlWriterTraceListener) adja hozzá a használni kívánt típushoz. Ha használja System.Diagnostics.XmlWriterTraceListener, meg kell adnia a kimeneti fájl helyét és nevét a konfigurációs fájlban. Ez a naplófájl nevére való beállítással initializeData végezhető el. Ellenkező esetben a rendszer kivételt jelez. Olyan egyéni figyelőt is implementálhat, amely naplókat bocsát ki egy alapértelmezett fájlba.

Feljegyzés

Mivel az üzenetnaplózás hozzáfér a lemezterülethez, korlátoznia kell az adott szolgáltatás lemezére írt üzenetek számát. Az üzenetkorlát elérésekor a rendszer az információs szinten létrehoz egy nyomkövetést, és az összes üzenetnaplózási tevékenység leáll.

A naplózási szintet és a további lehetőségeket a Naplózási szint és beállítások szakaszban tárgyaljuk.

Egy switchValue attribútum source csak nyomkövetésre érvényes. Ha az alábbiak szerint ad meg egy switchValue attribútumot a System.ServiceModel.MessageLogging nyomkövetési forráshoz, annak nincs hatása.

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

Ha le szeretné tiltani a nyomkövetési forrást, használja helyette az logMessagesAtServiceLevelelem , logMalformedMessagesés logMessagesAtTransportLevel attribútumait messageLogging . Ezeket az attribútumokat a következőre falsekell beállítania: . Ez az előző kódpéldában található konfigurációs fájl használatával, a Configuration Editor felhasználói felületén vagy a WMI használatával végezhető el. A Konfigurációszerkesztő eszközről további információt a Konfigurációszerkesztő eszköz (SvcConfigEditor.exe) című témakörben talál. A WMI-ről további információt a Windows Management Instrumentation for Diagnostics használata című témakörben talál.

Naplózási szintek és beállítások

Bejövő üzenetek esetén a naplózás közvetlenül az üzenet létrejötte után történik, közvetlenül azelőtt, hogy az üzenet a szolgáltatás szintjén a felhasználói kódhoz jutna, és ha a rendszer hibásan formázott üzeneteket észlel.

Kimenő üzenetek esetén a naplózás közvetlenül azután történik, hogy az üzenet elhagyja a felhasználói kódot, és közvetlenül azelőtt, hogy az üzenet a vezetékre kerül.

A WCF két különböző szinten naplózza az üzeneteket, a szolgáltatást és az átvitelt. A rendszer a hibásan formázott üzeneteket is naplózza. A három kategória egymástól független, és konfigurációban külön aktiválható.

A naplózási szintet az elem , logMalformedMessagesés logMessagesAtTransportLevel attribútumainak messageLogging beállításával logMessagesAtServiceLevelszabályozhatja.

Szolgáltatásszint

Az ezen a rétegen naplózott üzenetek a felhasználói kód megadására (fogadáskor) vagy kilépésre (küldéskor) kerülnek. Ha a szűrők definiálva vannak, a rendszer csak a szűrőknek megfelelő üzeneteket naplózza. Ellenkező esetben a szolgáltatásszinten lévő összes üzenet naplózva lesz. Az infrastruktúra-üzenetek (tranzakciók, társcsatorna és biztonság) is ezen a szinten vannak naplózva, kivéve a megbízható üzenetküldési üzeneteket. Streamelt üzenetekben csak a fejlécek naplózása lesz naplózva. Emellett a biztonságos üzenetek naplózása ezen a szinten lesz visszafejtve.

Szállítási szint

Az ezen a rétegen naplózott üzenetek készen állnak a vezetéken való szállításra vagy azok után történő kódolásra vagy dekódolásra. Ha a szűrők definiálva vannak, a rendszer csak a szűrőknek megfelelő üzeneteket naplózza. Ellenkező esetben a rendszer az átviteli réteg összes üzenetét naplózza. A rendszer ezen a rétegen naplózza az összes infrastrukturális üzenetet, beleértve a megbízható üzenetküldési üzeneteket is. Streamelt üzenetekben csak a fejlécek naplózása lesz naplózva. A biztonságos üzeneteket ezen a szinten titkosítva naplózza a rendszer, kivéve, ha biztonságos átvitelt használ, például HTTPS-t.

Hibásan formázott szint

A hibásan formázott üzenetek olyan üzenetek, amelyeket a WCF-verem a feldolgozás bármely szakaszában elutasít. A hibásan formázott üzenetek naplózása a következőképpen történik: ha igen, titkosítva, nem megfelelő XML-fájllal stb. maxSizeOfMessageToLog meghatározta a CDATA-ként naplózandó üzenet méretét. Alapértelmezés szerint maxSizeOfMessageToLog 256K-nak felel meg. Az attribútummal kapcsolatos további információkért lásd az Egyéb beállítások szakaszt.

Egyéb beállítások

A naplózási szinteken kívül a felhasználó a következő beállításokat is megadhatja:

Teljes üzenet naplózása (logEntireMessage attribútum): Ez az érték azt határozza meg, hogy a teljes üzenet (üzenetfejléc és szövegtörzs) naplózva van-e. Az alapértelmezett érték az false, ami azt jelenti, hogy csak a fejléc van naplózva. Ez a beállítás hatással van a szolgáltatás és az átviteli üzenetek naplózási szintjére.
Naplózandó üzenetek maximális száma (maxMessagesToLog attribútum): Ez az érték határozza meg a naplózandó üzenetek maximális számát. Az összes üzenet (szolgáltatás, átvitel és hibásan formázott üzenetek) beleszámít ebbe a kvótába. A kvóta elérésekor a rendszer nyomkövetést bocsát ki, és nem naplóz további üzenetet. Az alapértelmezett érték 10000.
A naplózni kívánt üzenet maximális mérete (maxSizeOfMessageToLog attribútum): Ez az érték határozza meg a bájtokban bejelentkezni kívánt üzenetek maximális méretét. A rendszer nem naplózza a méretkorlátot meghaladó üzeneteket, és nem végez más tevékenységet az üzenethez. Ez a beállítás minden nyomkövetési szintet érint. Ha a ServiceModel-nyomkövetés be van kapcsolva, a rendszer figyelmeztetési szintű nyomkövetést ad ki az első naplózási ponton (ServiceModelSend* vagy TransportReceive), amely értesíti a felhasználót. A szolgáltatásszintű és az átviteli szintű üzenetek alapértelmezett értéke 256 K, míg a hibásan formázott üzenetek alapértelmezett értéke 4K.

Figyelemfelhívás

Az összehasonlítandó maxSizeOfMessageToLog üzenetméret a memória üzenetmérete a szerializálás előtt. Ez a méret eltérhet a naplózott üzenetsztring tényleges hosszától, és sok esetben nagyobb, mint a tényleges méret. Emiatt előfordulhat, hogy az üzenetek nem lesznek naplózva. Ezt a tényt úgy tudja figyelembe venni, hogy az maxSizeOfMessageToLog attribútum 10%-kal nagyobb a várt üzenetméretnél. Ha helytelenül formázott üzeneteket naplóz, az üzenetnaplók által használt tényleges lemezterület akár ötszöröse is lehet a megadott maxSizeOfMessageToLogértéknek.

Ha a konfigurációs fájlban nincs nyomkövetési figyelő, a megadott naplózási szinttől függetlenül nem jön létre naplózási kimenet.

Az üzenetnaplózási beállítások, például az ebben a szakaszban ismertetett attribútumok futásidőben módosíthatók a Windows Management Instrumentation (WMI) használatával. Ez az AppDomainInfo-példány elérésével végezhető el, amely a következő logikai tulajdonságokat teszi elérhetővé: LogMessagesAtServiceLevel, LogMessagesAtTransportLevelés LogMalformedMessages. Ezért ha konfigurál egy nyomkövetési figyelőt az üzenetnaplózáshoz, de konfigurálja ezeket a beállításokat false , később módosíthatja őket true az alkalmazás futtatásakor. Ez hatékonyan teszi lehetővé az üzenetek naplózását futásidőben. Hasonlóképpen, ha engedélyezi az üzenetnaplózást a konfigurációs fájlban, futtatáskor letilthatja azt a WMI használatával. További információ: A Windows Management Instrumentation használata a diagnosztika számára.

Az source üzenetnapló mezője meghatározza, hogy az üzenet mely környezetben legyen naplózva: kérésüzenet küldésekor/fogadásakor, válaszkérés vagy egyirányú kérés esetén, szolgáltatási modellben vagy átviteli rétegben, vagy hibásan formázott üzenet esetén.

A hibásan formázott üzenetek source esetében a következő egyenlő Malformed: . Ellenkező esetben a forrás a következő értékekkel rendelkezik a környezet alapján.

Kérés/válasz esetén:

Réteg	Kérés küldése	Kérés fogadása	Válasz küldése	Válasz fogadása
Szolgáltatásmodell-réteg	Szolgáltatás Level Küldés Kérés	Szolgáltatás Level Fogadás Kérés	Szolgáltatás Level Küldés Válasz	Szolgáltatás Level Fogadás Válasz
Átviteli réteg	Átvitel Küldés	Átvitel Fogadás	Átvitel Küldés	Átvitel Fogadás

Egyirányú kérés esetén:

Réteg	Kérés küldése	Kérés fogadása
Szolgáltatásmodell-réteg	Szolgáltatás Level Küldés Datagram	Szolgáltatás Level Fogadás Datagram
Átviteli réteg	Átvitel Küldés	Átvitel Fogadás

Üzenetszűrők

Az üzenetszűrők a messageLogging konfigurációs szakasz konfigurációs elemében diagnostics vannak definiálva. Az alkalmazásuk a szolgáltatás és a szállítás szintjén történik. Egy vagy több szűrő definiálásakor a rendszer csak az egyik szűrőnek megfelelő üzeneteket naplózza. Ha nincs definiálva szűrő, az összes üzenet áthalad.

A szűrők támogatják a teljes XPath-szintaxist, és a konfigurációs fájlban megjelenő sorrendben lesznek alkalmazva. A szintaktikailag helytelen szűrő konfigurációs kivételt eredményez.

A szűrők egy biztonsági funkciót is biztosítanak az nodeQuota attribútum használatával, amely korlátozza az XPath DOM-ban a maximálisan megvizsgálható csomópontok számát a szűrőnek megfelelően.

Az alábbi példa bemutatja, hogyan konfigurálhat olyan szűrőt, amely csak a SOAP fejlécszakaszt tartalmazó üzeneteket rögzíti.

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

A szűrők nem alkalmazhatók az üzenet törzsére. Az üzenetek törzsét manipulálni próbáló szűrők törlődnek a szűrők listájából. A rendszer egy eseményt is kibocsát, amely ezt jelzi. A következő szűrő például el lesz távolítva a szűrőtáblából.

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

Egyéni figyelő konfigurálása

Egyéni figyelőt további beállításokkal is konfigurálhat. Az egyéni figyelők hasznosak lehetnek az alkalmazásspecifikus PII-elemek szűrésében az üzenetekből a naplózás előtt. Az alábbi példa egy egyéni figyelőkonfigurációt mutat be.

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

Vegye figyelembe, hogy az type attribútumot a típus minősített szerelvénynevére kell beállítani.

Megosztás a következőn keresztül: