Konfigurowanie rejestrowania komunikatów

Artykuł
03/05/2024

W tym temacie opisano sposób konfigurowania rejestrowania komunikatów dla różnych scenariuszy.

Włączanie rejestrowania komunikatów

Program Windows Communication Foundation (WCF) domyślnie nie rejestruje komunikatów. Aby aktywować rejestrowanie komunikatów, należy dodać odbiornik śledzenia do System.ServiceModel.MessageLogging źródła śledzenia i ustawić atrybuty elementu <messagelogging> w pliku konfiguracji.

W poniższym przykładzie pokazano, jak włączyć rejestrowanie i określić dodatkowe opcje.

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

Aby uzyskać więcej informacji na temat ustawień rejestrowania komunikatów, zobacz Zalecane Ustawienia dotyczące śledzenia i rejestrowania komunikatów.

Możesz użyć add polecenia , aby określić nazwę i typ odbiornika, którego chcesz użyć. W przykładowej konfiguracji odbiornik ma nazwę "messages" i dodaje standardowy odbiornik śledzenia programu .NET Framework (System.Diagnostics.XmlWriterTraceListener) jako typ do użycia. Jeśli używasz System.Diagnostics.XmlWriterTraceListenerpolecenia , musisz określić lokalizację pliku wyjściowego i nazwę w pliku konfiguracji. W tym celu należy ustawić initializeData nazwę pliku dziennika. W przeciwnym razie system zgłasza wyjątek. Można również zaimplementować odbiornik niestandardowy, który emituje dzienniki do pliku domyślnego.

Uwaga

Ponieważ rejestrowanie komunikatów uzyskuje dostęp do miejsca na dysku, należy ograniczyć liczbę komunikatów zapisywanych na dysku dla określonej usługi. Po osiągnięciu limitu komunikatów zostanie wygenerowany ślad na poziomie informacje i zatrzymanie wszystkich działań rejestrowania komunikatów.

Poziom rejestrowania, a także dodatkowe opcje, zostały omówione w sekcji Poziom rejestrowania i opcje.

Atrybut switchValue elementu source jest prawidłowy tylko do śledzenia. Jeśli określisz switchValue atrybut dla System.ServiceModel.MessageLogging źródła śledzenia w następujący sposób, nie ma to wpływu.

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

Jeśli chcesz wyłączyć źródło śledzenia, należy zamiast tego messageLogging użyć logMessagesAtServiceLevelatrybutów , logMalformedMessagesi logMessagesAtTransportLevel elementu . Należy ustawić wszystkie te atrybuty na false. Można to zrobić przy użyciu pliku konfiguracji w poprzednim przykładzie kodu, za pośrednictwem interfejsu interfejsu użytkownika edytora konfiguracji lub przy użyciu usługi WMI. Aby uzyskać więcej informacji na temat narzędzia Edytor konfiguracji, zobacz Narzędzie edytora konfiguracji (SvcConfigEditor.exe). Aby uzyskać więcej informacji na temat usługi WMI, zobacz Using Windows Management Instrumentation for Diagnostics (Używanie instrumentacji zarządzania Windows do diagnostyki).

Poziomy i opcje rejestrowania

W przypadku komunikatów przychodzących rejestrowanie odbywa się natychmiast po utworzeniu komunikatu, bezpośrednio przed pobraniem komunikatu do kodu użytkownika na poziomie usługi, a po wykryciu źle sformułowanych komunikatów.

W przypadku komunikatów wychodzących rejestrowanie odbywa się natychmiast po opuszczeniu kodu użytkownika i bezpośrednio przed przejściem komunikatu do sieci.

Program WCF rejestruje komunikaty na dwóch różnych poziomach: usługi i transportu. Źle sformułowane komunikaty są również rejestrowane. Trzy kategorie są niezależne od siebie i można je aktywować oddzielnie w konfiguracji.

Poziom rejestrowania można kontrolować, ustawiając logMessagesAtServiceLevelatrybuty , logMalformedMessagesi logMessagesAtTransportLevel elementu messageLogging .

Poziom usługi

Komunikaty zarejestrowane w tej warstwie mają na celu wprowadzenie (po odebraniu) lub pozostawienie (przy wysyłaniu) kodu użytkownika. Jeśli filtry zostały zdefiniowane, rejestrowane są tylko komunikaty zgodne z filtrami. W przeciwnym razie wszystkie komunikaty na poziomie usługi są rejestrowane. Komunikaty infrastruktury (transakcje, kanał równorzędny i zabezpieczenia) są również rejestrowane na tym poziomie, z wyjątkiem komunikatów reliable messaging. W przypadku komunikatów przesyłanych strumieniowo rejestrowane są tylko nagłówki. Ponadto bezpieczne komunikaty są rejestrowane na tym poziomie.

Poziom transportu

Komunikaty zarejestrowane w tej warstwie są gotowe do kodowania lub dekodowania dla lub po przewiezieniu przewodu. Jeśli filtry zostały zdefiniowane, rejestrowane są tylko komunikaty zgodne z filtrami. W przeciwnym razie wszystkie komunikaty w warstwie transportu są rejestrowane. Wszystkie komunikaty infrastruktury są rejestrowane w tej warstwie, w tym niezawodne komunikaty komunikatów. W przypadku komunikatów przesyłanych strumieniowo rejestrowane są tylko nagłówki. Ponadto bezpieczne komunikaty są rejestrowane jako zaszyfrowane na tym poziomie, z wyjątkiem sytuacji, gdy jest używany bezpieczny transport, taki jak HTTPS.

Źle sformułowany poziom

Źle sformułowane komunikaty to komunikaty, które są odrzucane przez stos WCF na dowolnym etapie przetwarzania. Źle sformułowane komunikaty są rejestrowane jako: szyfrowane, jeśli tak, z nieprawidłowym kodem XML itd. maxSizeOfMessageToLog zdefiniowano rozmiar komunikatu do zarejestrowania jako CDATA. Domyślnie maxSizeOfMessageToLog jest równe 256K. Aby uzyskać więcej informacji na temat tego atrybutu, zobacz sekcję Inne opcje.

Inne opcje

Oprócz poziomów rejestrowania użytkownik może określić następujące opcje:

Dziennik cały komunikat (logEntireMessage atrybut): ta wartość określa, czy cały komunikat (nagłówek i treść wiadomości) jest rejestrowany. Wartość domyślna to false, co oznacza, że rejestrowany jest tylko nagłówek. To ustawienie ma wpływ na poziomy rejestrowania komunikatów usługi i transportu.
Maksymalna liczba komunikatów do dziennika (maxMessagesToLog atrybut): ta wartość określa maksymalną liczbę komunikatów do zarejestrowania. Wszystkie komunikaty (usługa, transport i źle sformułowane komunikaty) są liczone do tego limitu przydziału. Po osiągnięciu limitu przydziału jest emitowany ślad i nie jest rejestrowany żaden dodatkowy komunikat. Wartość domyślna to 10000.
Maksymalny rozmiar komunikatu do dziennika (maxSizeOfMessageToLog atrybut): ta wartość określa maksymalny rozmiar komunikatów do logowania się w bajtach. Komunikaty, które przekraczają limit rozmiaru, nie są rejestrowane i nie są wykonywane żadne inne działania dla tego komunikatu. To ustawienie ma wpływ na wszystkie poziomy śledzenia. Jeśli śledzenie modelu ServiceModel jest włączone, śledzenie na poziomie ostrzeżenia jest emitowane w pierwszym punkcie rejestrowania (ServiceModelSend* lub TransportReceive), aby powiadomić użytkownika. Wartość domyślna komunikatów na poziomie usługi i na poziomie transportu to 256K, a wartość domyślna źle sformułowanych komunikatów to 4K.

Uwaga

Rozmiar komunikatu obliczony do porównania maxSizeOfMessageToLog jest rozmiarem komunikatu w pamięci przed serializacji. Ten rozmiar może różnić się od rzeczywistej długości rejestrowanego ciągu komunikatu, a w wielu przypadkach jest większy niż rzeczywisty rozmiar. W związku z tym komunikaty mogą nie być rejestrowane. Ten fakt można uwzględnić, określając maxSizeOfMessageToLog atrybut o rozmiarze 10% większym niż oczekiwany rozmiar komunikatu. Ponadto, jeśli źle sformułowane komunikaty są rejestrowane, rzeczywiste miejsce na dysku używane przez dzienniki komunikatów może wynosić do 5 razy więcej niż rozmiar wartości określonej przez maxSizeOfMessageToLog.

Jeśli w pliku konfiguracji nie zdefiniowano odbiornika śledzenia, żadne dane wyjściowe rejestrowania nie są generowane niezależnie od określonego poziomu rejestrowania.

Opcje rejestrowania komunikatów, takie jak atrybuty opisane w tej sekcji, można zmienić w czasie wykonywania przy użyciu instrumentacji zarządzania Windows (WMI). Można to zrobić, korzystając z wystąpienia AppDomainInfo , które uwidacznia następujące właściwości logiczne: LogMessagesAtServiceLevel, LogMessagesAtTransportLeveli LogMalformedMessages. W związku z tym jeśli skonfigurujesz odbiornik śledzenia na potrzeby rejestrowania komunikatów, ale ustawisz te opcje na false w konfiguracji, możesz później zmienić je na true gdy aplikacja jest uruchomiona. Umożliwia to efektywne rejestrowanie komunikatów w czasie wykonywania. Podobnie, jeśli włączysz rejestrowanie komunikatów w pliku konfiguracji, możesz go wyłączyć w czasie wykonywania przy użyciu usługi WMI. Aby uzyskać więcej informacji, zobacz Using Windows Management Instrumentation for Diagnostics (Używanie instrumentacji zarządzania Windows do diagnostyki).

Pole source w dzienniku komunikatów określa, w którym kontekście jest rejestrowany komunikat: podczas wysyłania/odbierania wiadomości żądania, żądania odpowiedzi lub żądania 1-way, modelu usługi lub warstwy transportu lub w przypadku źle sformułowanej wiadomości.

W przypadku źle sformułowanych komunikatów source wartość jest równa Malformed. W przeciwnym razie źródło ma następujące wartości na podstawie kontekstu.

W przypadku żądania/odpowiedzi:

Warstwa	Wyślij żądanie	Żądanie odbioru	Wyślij odpowiedź	Odbierz odpowiedź
Warstwa modelu usługi	Usługa Poziom Wysyłanie Żądanie	Usługa Poziom Pobierz Żądanie	Usługa Poziom Wysyłanie Odpowiedź	Usługa Poziom Pobierz Odpowiedź
Warstwa transportowa	Transport Wysyłanie	Transport Pobierz	Transport Wysyłanie	Transport Pobierz

W przypadku żądania jednokierunkowego:

Warstwa	Wyślij żądanie	Żądanie odbioru
Warstwa modelu usługi	Usługa Poziom Wysyłanie Datagram	Usługa Poziom Pobierz Datagram
Warstwa transportowa	Transport Wysyłanie	Transport Pobierz

Filtry komunikatów

Filtry komunikatów są definiowane w messageLogging elemecie diagnostics konfiguracji sekcji konfiguracji. Są one stosowane na poziomie usług i transportu. Po zdefiniowaniu co najmniej jednego filtru rejestrowane są tylko komunikaty zgodne z co najmniej jednym z filtrów. Jeśli żaden filtr nie jest zdefiniowany, wszystkie komunikaty przechodzą przez.

Filtry obsługują pełną składnię XPath i są stosowane w kolejności, w której są wyświetlane w pliku konfiguracji. Niepoprawny składniowo filtr powoduje wyjątek konfiguracji.

Filtry zapewniają również funkcję bezpieczeństwa przy użyciu atrybutu nodeQuota , który ogranicza maksymalną liczbę węzłów w XPath DOM, które można zbadać w celu dopasowania filtru.

W poniższym przykładzie pokazano, jak skonfigurować filtr, który rejestruje tylko komunikaty, które mają sekcję nagłówka protokołu 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>

Nie można zastosować filtrów do treści komunikatu. Filtry, które próbują manipulować treścią wiadomości, są usuwane z listy filtrów. Zdarzenie jest również emitowane, które wskazuje na to. Na przykład następujący filtr zostanie usunięty z tabeli filtrów.

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

Konfigurowanie odbiornika niestandardowego

Można również skonfigurować odbiornik niestandardowy przy użyciu dodatkowych opcji. Niestandardowy odbiornik może być przydatny podczas filtrowania elementów piI specyficznych dla aplikacji przed rejestrowaniem. W poniższym przykładzie pokazano konfigurację odbiornika niestandardowego.

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

Należy pamiętać, że type atrybut powinien być ustawiony na kwalifikowaną nazwę zestawu typu.

Udostępnij za pośrednictwem