Üzenetnaplózás konfigurálása

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 beállítások nyomkövetéshez és üzenetnaplózáshoz.

A add segítségével megadhatja 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.

Megjegyzé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 inkább a logMessagesAtServiceLevel, logMalformedMessages és logMessagesAtTransportLevel attribútumait a messageLogging elemnek. 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 Configuration Editor Tool (SvcConfigEditor.exe) című cikkben 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ó.

Az logMessagesAtServiceLevel, logMalformedMessages és logMessagesAtTransportLevel attribútumok beállításával szabályozhatja a naplózási szintet a messageLogging elem esetében.

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 üzenetek esetén csak a fejlécek kerülnek naplózásra. Emellett a biztonságos üzenetek ezen a szinten visszafejtve vannak naplózva.

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 üzenetek esetén csak a fejlécek kerülnek naplózásra. 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 üzeneteket naplózzuk as-is: titkosítva, ha azok hibásak, nem megfelelő az XML, és így tovább. 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.

Figyelmeztetés

Az a kiszámított üzenetméret, amelyet az maxSizeOfMessageToLog értékkel hasonlítanak össze, a memória üzenetmérete a szerializálás előtt van. 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 értéke 10% nagyobb, mint a várt üzenetméret. Továbbá, ha helytelenül formázott üzenetek naplózásra kerülnek, az üzenetnaplók által felhasznált tényleges lemezterület akár ötszöröse is lehet a maxSizeOfMessageToLog által megadott é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, és ezeket a beállításokat false értékre állítja be a konfigurációban, később megváltoztathatja őket true értékre, amikor az alkalmazás fut. Ez hatékonyan teszi lehetővé az üzenetek futásidőben történő naplózását. Hasonlóképpen, ha engedélyezi az üzenetnaplózást a konfigurációs fájlban, futásidőben 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.

Hibásan formázott üzenetek esetén a source egyenlő a Malformed értékével. 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 szint Küld Kérelem	Szolgáltatás szint Megkap Kérelem	Szolgáltatás szint Küld Válasz	Szolgáltatás szint Megkap Válasz
Átviteli réteg	Szállítás Küld	Szállítás Megkap	Szállítás Küld	Szállítás Megkap

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 szint Küld Datagram	Szolgáltatás szint Megkap Datagram
Átviteli réteg	Szállítás Küld	Szállítás Megkap

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

Lásd még

Last updated on 2025-06-17

Megosztás: