Konfigurace protokolování zpráv

Toto téma popisuje, jak nakonfigurovat protokolování zpráv pro různé scénáře.

Povolení protokolování zpráv

Windows Communication Foundation (WCF) ve výchozím nastavení nehlásí zprávy. Pokud chcete aktivovat protokolování zpráv, musíte přidat naslouchací zařízení trasování do System.ServiceModel.MessageLogging zdroje trasování a nastavit atributy pro <messagelogging> prvek v konfiguračním souboru.

Následující příklad ukazuje, jak povolit protokolování a zadat další možnosti.

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

Další informace o nastavení protokolování zpráv naleznete v tématu Doporučené nastavení pro trasování a protokolování zpráv.

Můžete použít add k zadání názvu a typu posluchače, který chcete použít. V příkladu konfigurace má naslouchací proces název "messages" a jako typ, který se má použít, přidá standardní naslouchací proces trasování rozhraní .NET Framework (System.Diagnostics.XmlWriterTraceListener). Pokud používáte System.Diagnostics.XmlWriterTraceListener, musíte zadat umístění a název výstupního souboru v konfiguračním souboru. To se provádí nastavením initializeData na název souboru protokolu. V opačném případě systém vyvolá výjimku. Můžete také implementovat vlastní naslouchací proces, který generuje protokoly do výchozího souboru.

Poznámka:

Vzhledem k tomu, že protokolování zpráv přistupuje k místu na disku, měli byste omezit počet zpráv, které se zapisují na disk pro určitou službu. Když je dosažen limit zpráv, vytvoří se trasování na úrovni Informace a všechny aktivity logování zpráv se zastaví.

Úroveň protokolování a další možnosti jsou popsány v části Úroveň protokolování a Možnosti.

Atribut switchValue atributu source je platný pouze pro trasování. Pokud zadáte atribut switchValue pro trasovací zdroj System.ServiceModel.MessageLogging tímto způsobem, nebude to mít žádný vliv.

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

Pokud chcete zakázat zdroj trasování, měli byste místo toho použít logMessagesAtServiceLevellogMalformedMessages, a logMessagesAtTransportLevel atributy messageLogging prvku. Všechny tyto atributy byste měli nastavit na false. To lze provést pomocí konfiguračního souboru v předchozím příkladu kódu, prostřednictvím rozhraní uživatelského rozhraní editoru konfigurace nebo pomocí rozhraní WMI. Další informace o nástroji Editor konfigurace naleznete v tématu Nástroj editoru konfigurace (SvcConfigEditor.exe). Další informace o rozhraní WMI naleznete v tématu Použití nástroje Windows Management Instrumentation pro diagnostiku.

Možnosti a úrovně protokolování

U příchozích zpráv se protokolování provádí okamžitě po vytvoření zprávy, bezprostředně před tím, než se zpráva dostane k uživatelskému kódu na úrovni služby a při zjištění poškozených zpráv.

U odchozích zpráv se protokolování provede okamžitě po opuštění uživatelského kódu a bezprostředně před tím, než zpráva přejde do přenosu.

WCF protokoluje zprávy na dvou různých úrovních, službě a přenosu. Také se zaznamenávají nesprávně formátované zprávy. Tři kategorie jsou nezávislé na sobě a je možné je aktivovat samostatně v konfiguraci.

Úroveň protokolování můžete řídit nastavením logMessagesAtServiceLevel, logMalformedMessages, a logMessagesAtTransportLevel atributů elementu messageLogging.

Úroveň služby

Zprávy zaznamenané v této vrstvě vstupují (při příjmu) nebo opouštějí (při odesílání) uživatelský kód. Pokud byly definovány filtry, protokolují se pouze zprávy, které odpovídají filtrům. V opačném případě se zaprotokolují všechny zprávy na úrovni služby. Zprávy infrastruktury (transakce, kanál partnerského vztahu a zabezpečení) se také protokolují na této úrovni, s výjimkou zpráv Reliable Messaging. U streamovaných zpráv se protokolují pouze hlavičky. Kromě toho jsou na této úrovni zabezpečené zprávy dešifrovány a zaprotokolovány.

Úroveň přenosu

Zprávy protokolované v této vrstvě jsou připravené k kódování nebo dekódování pro nebo po přepravě na drátě. Pokud byly definovány filtry, protokolují se pouze zprávy, které odpovídají filtrům. V opačném případě se zaprotokolují všechny zprávy v přenosové vrstvě. Všechny zprávy infrastruktury, včetně zpráv spolehlivého zasílání zpráv, jsou protokolovány v této vrstvě. U streamovaných zpráv se protokolují pouze hlavičky. Kromě toho jsou zabezpečené zprávy protokolovány jako šifrované na této úrovni, s výjimkou případů, kdy se používá zabezpečený přenos, jako je HTTPS.

Špatně formátovaná úroveň

Poškozené zprávy jsou zprávy, které stack WCF odmítne v jakékoli fázi zpracování. Nesprávně formátované zprávy jsou protokolovány as-is: zašifrovány, pokud jsou nesprávně, s chybným kódem XML a podobně. maxSizeOfMessageToLog definuje velikost zprávy, která se má protokolovat jako CDATA. Ve výchozím nastavení maxSizeOfMessageToLog se rovná 256 K. Další informace o tomto atributu naleznete v části Další možnosti.

Další možnosti

Kromě úrovní protokolování může uživatel zadat následující možnosti:

• Log Entire Message (logEntireMessage attribute): Tato hodnota určuje, zda je zaprotokolována celá zpráva (záhlaví zprávy a text). Výchozí hodnota je false, což znamená, že se zapisuje pouze hlavička. Toto nastavení má vliv na úrovně protokolování zpráv služby a přenosu.

• Maximální počet zpráv do protokolu (maxMessagesToLog atribut): Tato hodnota určuje maximální počet zpráv, které se mají protokolovat. Do této kvóty se započítávají všechny zprávy (služby, přenos a poškozené zprávy). Jakmile je dosaženo kvóty, vygeneruje se trasování a žádná další zpráva již nebude zaznamenána. Výchozí hodnota je 1 0000.

• Maximální velikost zprávy k protokolování (maxSizeOfMessageToLog atribut): Tato hodnota určuje maximální velikost zpráv pro zaznamenání v bajtech. Zprávy, které překračují limit velikosti, nejsou protokolovány a pro tuto zprávu se neprovádí žádná jiná aktivita. Toto nastavení má vliv na všechny úrovně trasování. Pokud je trasování ServiceModel zapnuté, v prvním bodu protokolování (ServiceModelSend* nebo TransportReceive) se vygeneruje trasování na úrovni upozornění, které uživatele upozorní. Výchozí hodnota pro zprávy na úrovni služby a přenosu je 256 K, zatímco výchozí hodnota pro poškozené zprávy je 4K.

  Upozornění

  Velikost zprávy vypočítaná k porovnání maxSizeOfMessageToLog je velikost zprávy v paměti před serializací. Tato velikost se může lišit od skutečné délky zaprotokolovaného řetězce zprávy a v mnoha případech je větší než skutečná velikost. V důsledku toho se zprávy nemusí protokolovat. Tento fakt můžete zohlednit zadáním atributu maxSizeOfMessageToLog , který má být 10% větší než očekávaná velikost zprávy. Kromě toho, pokud jsou zapsány poškozené zprávy, skutečné místo na disku využité záznamy zpráv může být až 5krát větší než hodnota určená maxSizeOfMessageToLog.

Pokud v konfiguračním souboru není definováno žádné naslouchací zařízení, nevygeneruje se žádný protokolový výstup bez ohledu na zadanou úroveň protokolování.

Možnosti protokolování zpráv, jako jsou atributy popsané v této části, je možné změnit za běhu pomocí rozhraní WMI (Windows Management Instrumentation). To lze provést přístupem k AppDomainInfo instance, která zveřejňuje tyto logické vlastnosti: LogMessagesAtServiceLevel, LogMessagesAtTransportLevela LogMalformedMessages. Proto pokud nakonfigurujete posluchač trasování pro protokolování zpráv, ale tyto možnosti nastavíte v false konfiguraci, můžete je později změnit na true při spuštění aplikace. To umožňuje protokolování zpráv za běhu. Podobně pokud v konfiguračním souboru povolíte protokolování zpráv, můžete ho za běhu zakázat pomocí rozhraní WMI. Další informace naleznete v tématu Použití nástroje Windows Management Instrumentation pro diagnostiku.

Pole source v protokolu zpráv určuje, v jakém kontextu se zpráva zaprotokoluje: při odesílání nebo přijímání žádostní zprávy, pro žádost-odpověď nebo jednosměrný požadavek, na úrovni servisního modelu nebo přenosové vrstvy, nebo v případě chybné zprávy.

V případě poškozených zpráv je source rovno Malformed. V opačném případě má zdroj následující hodnoty na základě kontextu.

Žádost/odpověď:

Vrstva	Odeslat požadavek	Přijmout žádost	Odeslat odpověď	Dostat odpověď
Vrstva modelu služby	Služba Úroveň Odeslat Žádost	Služba Úroveň Obdržet Žádost	Služba Úroveň Odeslat Odpověď	Služba Úroveň Obdržet Odpověď
Transportní vrstva	Přeprava Odeslat	Přeprava Obdržet	Přeprava Odeslat	Přeprava Obdržet

Pro jednosměrnou žádost:

Vrstva	Odeslat požadavek	Přijmout žádost
Vrstva modelu služby	Služba Úroveň Odeslat Datagram	Služba Úroveň Obdržet Datagram
Transportní vrstva	Přeprava Odeslat	Přeprava Obdržet

Filtry zpráv

Filtry zpráv jsou definovány v konfiguračním messageLogging prvku oddílu diagnostics konfigurace. Použijí se na úrovni služby a dopravy. Pokud je definován jeden nebo více filtrů, protokolují se pouze zprávy, které odpovídají alespoň jednomu z filtrů. Pokud není definovaný žádný filtr, projdou všechny zprávy.

Filtry podporují úplnou syntaxi XPath a používají se v pořadí, v jakém se zobrazují v konfiguračním souboru. Výsledkem syntakticky nesprávného filtru je konfigurační výjimka.

Filtry také poskytují bezpečnostní funkci pomocí atributu nodeQuota , který omezuje maximální počet uzlů v XPath DOM, které je možné prozkoumat tak, aby odpovídaly filtru.

Následující příklad ukazuje, jak nakonfigurovat filtr, který zaznamenává pouze zprávy, které mají oddíl záhlaví 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>

Filtry nelze použít v textu zprávy. Filtry, které se pokusí manipulovat s textem zprávy, se odeberou ze seznamu filtrů. Událost, označující to, se také vygeneruje. Například následující filtr by byl odebrán z tabulky filtrů.

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

Konfigurace vlastního naslouchacího zařízení

Můžete také nakonfigurovat vlastní posluchač s dalšími možnostmi. Vlastní posluchač může být užitečný při filtrování prvků osobních údajů specifických pro aplikaci ze zpráv před jejich protokolováním. Následující příklad ukazuje vlastní konfiguraci posluchače.

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

Měli byste vědět, že type atribut by měl být nastaven na kvalifikovaný název sestavení typu.

Viz také

• <zaznamenávání zpráv>
• protokolování zpráv
• Doporučené nastavení pro trasování a protokolování zpráv