メッセージ ログの構成Configuring Message Logging

ここでは、さまざまなシナリオでのメッセージ ログの構成方法を示します。This topic describes how you can configure message logging for different scenarios.

メッセージ ログの有効化Enabling Message Logging

Windows Communication Foundation (WCF) では、既定でメッセージを記録しません。Windows Communication Foundation (WCF) does not log messages by default. メッセージ ログをアクティブにするには、トレース リスナーを System.ServiceModel.MessageLogging トレース ソースに追加し、構成ファイルで <messagelogging> 要素の属性を設定する必要があります。To activate message logging, you must add a trace listener to the System.ServiceModel.MessageLogging trace source and set attributes for the <messagelogging> element in the configuration file.

次の例は、ログを有効にして追加オプションを指定する方法を示しています。The following example shows how to enable logging and specify additional options.

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

メッセージ ログの設定の詳細については、次を参照してください。トレースとメッセージ ログの推奨設定します。For more information about message logging settings, see Recommended Settings for Tracing and Message Logging.

add を使用して、使用するリスナーの名前と型を指定することができます。You can use add to specify the name and type of the listener you want to use. この例の構成では、リスナーに "messages" という名前を付け、使用する型として標準の .NET Framework トレース リスナー (System.Diagnostics.XmlWriterTraceListener) を追加しています。In the example configuration, the Listener is named "messages" and adds the standard .NET Framework trace listener (System.Diagnostics.XmlWriterTraceListener) as the type to use. System.Diagnostics.XmlWriterTraceListener を使用する場合は、構成ファイルで出力ファイルの場所と名前を指定する必要があります。If you use System.Diagnostics.XmlWriterTraceListener, you must specify the output file location and name in the configuration file. 指定するには、initializeData をログ ファイルの名前に設定します。This is done by setting initializeData to the name of the log file. それ以外の場合、例外がスローされます。Otherwise, the system throws an exception. また、既定のファイルにログを出力するカスタム リスナーを実装することもできます。You can also implement a custom listener that emits logs to a default file.

注意

メッセージ ログはディスク領域にアクセスするため、ディスクに書き込む特定のサービスのメッセージ数を制限する必要があります。Because message logging accesses disk space, you should limit the number of messages that are written to disk for a particular service. メッセージ数が上限に達すると、情報レベルでのトレースが生成され、すべてのメッセージ ログ処理が停止します。When the message limit is reached, a trace at the Information level is produced and all message logging activities stop.

ログ レベルと追加オプションについては、「ログ レベルとオプション」のセクションで説明します。The logging level, as well as the additional options, are discussed in the Logging Level and Options section.

switchValuesource 属性は、トレースに対してのみ有効です。The switchValue attribute of a source is only valid for tracing. switchValue 属性を System.ServiceModel.MessageLogging トレース ソースに対して次のように指定しても無効です。If you specify a switchValue attribute for the System.ServiceModel.MessageLogging trace source as follows, it has no effect.

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

トレース ソースを無効にする場合は、代わりに logMessagesAtServiceLevel 要素の logMalformedMessages 属性、logMessagesAtTransportLevel 属性、および messageLogging 属性を使用する必要があります。If you want to disable the trace source, you should use the logMessagesAtServiceLevel, logMalformedMessages, and logMessagesAtTransportLevel attributes of the messageLogging element instead. これらすべての属性を false に設定します。You should set all these attributes to false. この設定を行うには、構成エディター UI インターフェイスで前のコード例の構成ファイルを使用するか、または WMI を使用します。This can be done by using the configuration file in the previous code example, through the Configuration Editor UI interface, or using WMI. 構成エディター ツールの詳細については、次を参照してください。構成エディター ツール (SvcConfigEditor.exe)します。For more information about the Configuration Editor tool, see Configuration Editor Tool (SvcConfigEditor.exe). WMI の詳細については、次を参照してください。診断用の Windows Management Instrumentation のを使用してします。For more information about WMI, see Using Windows Management Instrumentation for Diagnostics.

ログ レベルとオプションLogging Levels and Options

受信メッセージの場合は、メッセージが形成された直後、サービス レベルでメッセージがユーザー コードで処理される直前、および正しくないメッセージが検出されたときに、ログが記録されます。For incoming messages, logging happens immediately after the message is formed, immediately before the message gets to user code in the service level, and when malformed messages are detected.

送信メッセージの場合は、メッセージがユーザー コードから出力された直後およびメッセージがネットワークに出力される直前に、ログが記録されます。For outgoing messages, logging happens immediately after the message leaves user code and immediately before the message goes on the wire.

WCF では、2 つの異なるレベル、サービスとトランスポートでメッセージを記録します。WCF logs messages at two different levels, service and transport. 不正なメッセージも記録されます。Malformed messages are also logged. 3 つのカテゴリは互いに独立しており、構成で個別に有効にすることができます。The three categories are independent from each other and can be activated separately in configuration.

logMessagesAtServiceLevel 要素の logMalformedMessageslogMessagesAtTransportLevel、および messageLogging の各属性を設定することによって、ログ レベルを制御することができます。You can control the logging level by setting the logMessagesAtServiceLevel, logMalformedMessages, and logMessagesAtTransportLevel attributes of the messageLogging element.

サービス レベルService Level

このレイヤーでは、ユーザー コードに入力 (受信時) される直前、またはユーザー コードから出力 (送信時) される直前のメッセージが記録されます。Messages logged at this layer are about to enter (on receiving) or leave (on sending) user code. フィルターを定義した場合は、そのフィルターと一致するメッセージだけが記録されます。If filters have been defined, only messages that match the filters are logged. それ以外の場合は、サービス レベルのすべてのメッセージが記録されます。Otherwise, all messages at the service level are logged. このレベルでは、インフラストラクチャ メッセージ (トランザクション、ピア チャネル、およびセキュリティ) も記録されます。ただし、信頼できるメッセージング メッセージは記録されません。Infrastructure messages (transactions, peer channel, and security) are also logged at this level, except for Reliable Messaging messages. ストリーム メッセージの場合は、ヘッダーだけが記録されます。On streamed messages, only the headers are logged. また、セキュリティで保護されたメッセージもこのレベルで復号化されて記録されます。In addition, secure messages are logged decrypted at this level.

トランスポート レベルTransport Level

このレイヤーで記録されるメッセージは、ネットワーク上での転送に向けてエンコードできる状態になっているもの、および転送後にデコードできる状態になっているものです。Messages logged at this layer are ready to be encoded or decoded for or after transportation on the wire. フィルターを定義した場合は、そのフィルターと一致するメッセージだけが記録されます。If filters have been defined, only messages that match the filters are logged. それ以外の場合は、トランスポート レイヤーのすべてのメッセージが記録されます。Otherwise, all messages at the transport layer are logged. このレイヤーでは、信頼できるメッセージング メッセージを含むすべてのインフラストラクチャ メッセージが記録されます。All infrastructure messages are logged at this layer, including reliable messaging messages. ストリーム メッセージの場合は、ヘッダーだけが記録されます。On streamed messages, only the headers are logged. また、セキュリティで保護されたメッセージも、HTTPS などのセキュリティで保護されたトランスポートを使用している場合を除き、暗号化された状態でこのレベルで記録されます。In addition, secure messages are logged as encrypted at this level, except if a secure transport such as HTTPS is used.

不正レベルMalformed Level

形式が正しくないメッセージは、処理のいずれかの段階にある WCF スタックによって拒否されたメッセージです。Malformed messages are messages that are rejected by the WCF stack at any stage of processing. 正しくないメッセージは、そのままの状態で記録されます。暗号化されていれば、暗号化されたままで、適切でない XML も、そのままになります。Malformed messages are logged as-is: encrypted if they are so, with non-proper XML, and so on. maxSizeOfMessageToLog は、CDATA として記録されるメッセージのサイズを定義します。maxSizeOfMessageToLog defined the size of the message to be logged as CDATA. maxSizeOfMessageToLog の既定値は 256 K です。By default, maxSizeOfMessageToLog is equal to 256K. この属性の詳細については、その他のオプションを参照してください。For more information about this attribute, see the Other Options section.

その他のオプションOther Options

ログ レベルに加えて、次のオプションを指定することができます。In addition to the logging levels, the user can specify the following options:

  • メッセージ全体をログイン (logEntireMessage属性)。この値は、メッセージ全体 (メッセージ ヘッダーと本文) がログに記録するかどうかを指定します。Log Entire Message (logEntireMessage attribute): This value specifies whether the entire message (message header and body) is logged. 既定値は、false で、ヘッダーだけ記録することを意味します。The default value is false, meaning that only the header is logged. この設定は、サービス メッセージ ログ レベルおよびトランスポート メッセージ ログ レベルに影響を与えます。This setting affects service and transport message logging levels..

  • 記録するメッセージの最大数 (maxMessagesToLog属性)。この値は、記録するメッセージの最大数を指定します。Max messages to log (maxMessagesToLog attribute): This value specifies the maximum number of messages to log. すべてのメッセージ (サービス メッセージ、トランスポート メッセージ、および不正メッセージ) が、このクォータに対してカウントされます。All messages (service, transport, and malformed messages) are counted towards this quota. クォータに達すると、トレースが出力され、それ以上メッセージは記録されません。When the quota is reached, a trace is emitted and no additional message is logged. 既定値は、10000 です。The default value is 10000.

  • 記録するメッセージの最大サイズ (maxSizeOfMessageToLog属性)。この値は、バイト単位で記録するメッセージの最大サイズを指定します。Max size of message to log (maxSizeOfMessageToLog attribute): This value specifies the maximum size of messages to log in bytes. サイズ制限を超えたメッセージは記録されず、そのメッセージに対して何の処理も実行されません。Messages that exceed the size limit are not logged, and no other activity is performed for that message. この設定は、すべてのトレース レベルに影響を与えます。This setting affects all trace levels. ServiceModel トレースがオンの場合は、最初の記録ポイントで警告レベル トレース (ServiceModelSend* または TransportReceive) が出力され、ユーザーに通知します。If ServiceModel tracing is on, a Warning level trace is emitted at the first logging point (ServiceModelSend* or TransportReceive) to notify the user. サービス レベルとトランスポート レベルのメッセージの既定値は 256 K ですが、正しくないメッセージの既定値は 4 K です。The default value for service level and transport level messages is 256K, while the default value for malformed messages is 4K.

    注意事項

    maxSizeOfMessageToLog と照合するために計算されるメッセージ サイズは、シリアル化される前のメモリ上でのメッセージ サイズです。The message size that is computed to compare against maxSizeOfMessageToLog is the message size in memory before serialization. このサイズは、記録されるメッセージ文字列の実際の長さとは異なります。実際のサイズよりも大きい場合がほとんどです。This size can differ from the actual length of the message string that is being logged, and in many occasions is bigger than the actual size. その結果、メッセージが記録されない場合があります。As a result, messages may not be logged. maxSizeOfMessageToLog 属性をメッセージの見積もりサイズよりも 10% 大きく設定することによって、この現象を回避することができます。You can account for this fact by specifying the maxSizeOfMessageToLog attribute to be 10% larger than the expected message size. また、不正メッセージを記録する場合は、メッセージ ログに使用する実際のディスク領域を、maxSizeOfMessageToLog で指定した値の最大 5 倍にすることができます。In addition, if malformed messages are logged, the actual disk space utilized by the message logs can be up to 5 times the size of the value specified by maxSizeOfMessageToLog.

構成ファイルでトレース リスナーを定義していない場合は、ログ レベルの指定に関係なくログ出力は生成されません。If no trace listener is defined in the configuration file, no logging output is generated regardless of the specified logging level.

このセクションで説明されている属性などのメッセージ ログ オプションは、実行時に WMI (Windows Management Instrumentation) を使用して変更できます。Message logging options, such as the attributes described in this section, can be changed at runtime using Windows Management Instrumentation (WMI). これを行うへのアクセス、 AppDomainInfoインスタンスで、これらのブール型プロパティを公開します: LogMessagesAtServiceLevelLogMessagesAtTransportLevel、およびLogMalformedMessagesします。This can be done by accessing the AppDomainInfo instance, which exposes these Boolean properties: LogMessagesAtServiceLevel, LogMessagesAtTransportLevel, and LogMalformedMessages. そのため、メッセージ ログ用のトレース リスナーを構成していても、これらのオプションを構成で false に設定している場合は、後でアプリケーションを実行しているときに true に変更できます。Therefore, if you configure a trace listener for message logging, but set these options to false in configuration, you can later change them to true when the application is running. これで、メッセージ ログが実行時に有効になります。This effectively enables message logging at runtime. 同様に、構成ファイルでメッセージ ログを有効にしている場合は、実行時に WMI を使用して無効にできます。Similarly, if you enable message logging in your configuration file, you can disable it at runtime using WMI. 詳細については、次を参照してください。診断用の Windows Management Instrumentation のを使用してします。For more information, see Using Windows Management Instrumentation for Diagnostics.

メッセージ ログの source フィールドは、要求メッセージを送信または受信する際に要求/応答または一方向の要求については、サービス モデル レイヤーまたはトランスポート レイヤーで、または正しくないメッセージの場合に、メッセージを記録するコンテキストを指定します。The source field in a message log specifies in which context the message is logged: when sending/receiving a request message, for a request-reply or 1-way request, at service model or transport layer, or in the case of a malformed message.

正しくないメッセージは、のsourceと等しいMalformedします。For malformed messages, source is equal to Malformed. それ以外の場合、source には、コンテキストに基づいて、以下の値が設定されます。Otherwise, source has the following values based on the context.

要求/応答の場合For Request/Reply

Send RequestSend Request Receive RequestReceive Request Send ReplySend Reply Receive ReplyReceive Reply
Service Model layerService Model layer サービスService

レベルLevel

送信Send

要求Request
サービスService

レベルLevel

ReceiveReceive

要求Request
サービスService

レベルLevel

送信Send

ReplyReply
サービスService

レベルLevel

ReceiveReceive

ReplyReply
Transport layerTransport layer TransportTransport

送信Send
TransportTransport

ReceiveReceive
TransportTransport

送信Send
TransportTransport

ReceiveReceive

一方向の要求の場合For One-way Request

Send RequestSend Request Receive RequestReceive Request
Service Model layerService Model layer サービスService

レベルLevel

送信Send

データグラムDatagram
サービスService

レベルLevel

ReceiveReceive

データグラムDatagram
Transport layerTransport layer TransportTransport

送信Send
TransportTransport

ReceiveReceive

メッセージ フィルターMessage Filters

メッセージ フィルターは、messageLogging 構成セクションの diagnostics 構成要素で定義されます。Message filters are defined in the messageLogging configuration element of the diagnostics configuration section. これらは、サービス レベルとトランスポート レベルで適用されます。They are applied at the service and transport level. 1 つ以上のフィルターを定義した場合は、少なくとも 1 つのフィルターと一致するメッセージだけが記録されます。When one or more filters are defined, only messages that match at least one of the filters are logged. フィルターを定義しなかった場合は、すべてのメッセージが通過します。If no filter is defined, all messages pass through.

フィルターは、完全な XPath 構文をサポートし、構成ファイルでの出現順に適用されます。Filters support the full XPath syntax and are applied in the order they appear in the configuration file. フィルターが構文的に正しくない場合は、構成例外が発生します。A syntactically incorrect filter results in a configuration exception.

フィルターは、フィルターに一致するかどうかを確認できる、XPath DOM 内のノードの最大数を制限する nodeQuota 属性を使用することで、安全機能も提供します。Filters also provide a safety feature using the nodeQuota attribute, which limits the maximum number of nodes in the XPath DOM that can be examined to match the filter.

次の例は、SOAP ヘッダー セクションがあるメッセージだけを記録するフィルターの設定方法を示します。The following example shows how to configure a filter that records only messages that have a SOAP header section.

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

フィルターは、メッセージの本文には適用できません。Filters cannot be applied to the body of a message. メッセージの本文を操作しようとするフィルターは、フィルターの一覧から削除されます。Filters that attempt to manipulate the body of a message are removed from the list of filters. その場合には、このことを示すイベントも出力されます。An event is also emitted that indicates this. たとえば、次のフィルターは、フィルター テーブルから削除されます。For example, the following filter would be removed from the filter table.

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

カスタム リスナーの構成Configuring a Custom Listener

追加オプションでカスタム リスナーを構成することもできます。You can also configure a custom listener with additional options. カスタム リスナーは、記録を行う前に、アプリケーション固有の PII 要素をメッセージからフィルター処理するのに役立ちます。A custom listener can be useful in filtering application-specific PII elements from messages before logging. 次の例は、カスタム リスナーの構成を示しています。The following example demonstrates a custom listener configuration.

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

type 属性は、型のアセンブリ修飾名に設定する必要があることに注意してください。You should be aware that the type attribute should be set to a qualified assembly name of the type.

関連項目See also