Konfigurace protokolování zpráv

Článek
03/05/2024

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í proces 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 naslouchacího procesu, 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. Po dosažení limitu zprávy se vytvoří trasování na úrovni Informace a všechny aktivity protokolová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 switchValue atribut pro System.ServiceModel.MessageLogging zdroj trasování následujícím způsobem, nemá žá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.

Úrovně a možnosti 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. Zaprotokolují se také poškozené 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 logMessagesAtServiceLevellogMalformedMessages, a logMessagesAtTransportLevel atributy elementumessageLogging.

Úroveň služeb

Zprávy zaprotokolované v této vrstvě se chystá zadat (při příjmu) nebo opustit (při odesílání) uživatelského kódu. 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 zabezpečené zprávy zaprotokolovány dešifrovány na této úrovni.

Ú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 jsou protokolovány v této vrstvě, včetně spolehlivých zpráv zasílání zpráv. 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í. Poškozené zprávy se protokolují tak, jak jsou: zašifrované, pokud ano, s jiným než správným kódem XML atd. 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 protokoluje 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). Po dosažení kvóty se vygeneruje trasování a zaprotokoluje se žádná další zpráva. Výchozí hodnota je 1 0000.
Maximální velikost zprávy protokolu (maxSizeOfMessageToLog atribut): Tato hodnota určuje maximální velikost zpráv pro přihlášení bajtů. 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 zaprotokolovány poškozené zprávy, skutečné místo na disku využité protokoly zpráv může být až 5krát velikost hodnoty určené maxSizeOfMessageToLoghodnotou .

Pokud v konfiguračním souboru není definován žádný naslouchací proces trasování, nevygeneruje se žádný výstup protokolování 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 naslouchací proces 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 efektivně 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 zakázat za běhu 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í a příjmu zprávy žádosti, pro žádost-odpověď nebo 1 cestný požadavek, v modelu služby nebo přenosové vrstvě nebo v případě chybné zprávy.

U poškozených zpráv source je 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ěď	Přijmout odpověď
Vrstva modelu služby	Služba Level Odeslat Žádost	Služba Level Přijmout Žádost	Služba Level Odeslat Odpověď	Služba Level Přijmout Odpověď
Transportní vrstva	Přeprava Odeslat	Přeprava Přijmout	Přeprava Odeslat	Přeprava Přijmout

Pro jednosměrnou žádost:

Vrstva	Odeslat požadavek	Přijmout žádost
Vrstva modelu služby	Služba Level Odeslat Datagram	Služba Level Přijmout Datagram
Transportní vrstva	Přeprava Odeslat	Přeprava Přijmout

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 výjimka konfigurace.

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 se také vygeneruje, která to značí. 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 procesu

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

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

Sdílet prostřednictvím