Configuración del registro de mensajes

En este tema se describe cómo configurar el registro de mensajes para distintos escenarios.

Habilitación del registro de mensajes

Windows Communication Foundation (WCF) no registra mensajes de forma predeterminada. Para activar el registro de mensajes, debe agregar un agente de escucha de seguimiento al origen de seguimiento System.ServiceModel.MessageLogging y definir atributos para el elemento <messagelogging> en el archivo de configuración.

En el ejemplo siguiente se muestra cómo habilitar el registro y especificar opciones adicionales.

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

Para obtener más información sobre la configuración de registro de mensajes, consulte Configuración recomendada para seguimiento y registro de mensajes.

Puede usar add para especificar el nombre y el tipo del agente de escucha que desea usar. En la configuración de ejemplo, el agente de escucha se denomina "mensajes" y agrega el agente de escucha de seguimiento de .NET Framework estándar (System.Diagnostics.XmlWriterTraceListener) como el tipo que se va a utilizar. Si usa System.Diagnostics.XmlWriterTraceListener, debe especificar la ubicación y el nombre del archivo de salida en el archivo de configuración. Para ello, establezca initializeData en el nombre del archivo de registro. De lo contrario, el sistema produce una excepción. También puede implementar un agente de escucha personalizado que emita registros a un archivo predeterminado.

El nivel de registro, así como las opciones adicionales, se describen en la sección Nivel de registro y Opciones.

El switchValue atributo de un source objeto solo es válido para el seguimiento. Si especifica un atributo switchValue para la fuente System.ServiceModel.MessageLogging de seguimiento de la siguiente manera, no tendrá ningún efecto.

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

Si desea deshabilitar el origen de seguimiento, debe usar los atributos logMessagesAtServiceLevel, logMalformedMessages y logMessagesAtTransportLevel del elemento messageLogging en su lugar. Debe establecer todos estos atributos en false. Esto se puede hacer mediante el archivo de configuración del ejemplo de código anterior, a través de la interfaz de usuario del Editor de configuración o mediante WMI. Para obtener más información sobre la herramienta Editor de configuración, vea Herramienta del Editor de configuración (SvcConfigEditor.exe). Para más información sobre WMI, consulte Uso de Instrumental de administración de Windows para el diagnóstico.

Niveles y opciones de registro

Para los mensajes entrantes, el registro se produce inmediatamente después de que se forma el mensaje, inmediatamente antes de que el mensaje llegue al código de usuario en el nivel de servicio y cuando se detecten mensajes con formato incorrecto.

En el caso de los mensajes salientes, el registro se produce inmediatamente después de que el mensaje deje el código de usuario e inmediatamente antes de que el mensaje pase a la red.

WCF registra mensajes en dos niveles diferentes, servicio y transporte. Los mensajes con formato incorrecto también se registran. Las tres categorías son independientes entre sí y se pueden activar por separado en la configuración.

Puede controlar el nivel de registro estableciendo los atributos logMessagesAtServiceLevel, logMalformedMessages y logMessagesAtTransportLevel del elemento messageLogging.

Nivel de servicio

Los mensajes registrados en este nivel están a punto de introducir (al recibir) o dejar (al enviar) código de usuario. Si se han definido filtros, solo se registran los mensajes que coinciden con los filtros. De lo contrario, se registran todos los mensajes en el nivel de servicio. Los mensajes de infraestructura (transacciones, canal entre pares y seguridad) también se registran en este nivel, excepto los mensajes de Mensajería Confiable. En los mensajes transmitidos, solo se registran los encabezados. Además, los mensajes seguros se registran descifrados en este nivel.

Nivel de transporte

Los mensajes registrados en esta capa están listos para codificarse o decodificarse antes o después del transporte en la línea. Si se han definido filtros, solo se registran los mensajes que coinciden con los filtros. De lo contrario, se registran todos los mensajes de la capa de transporte. Todos los mensajes de infraestructura se registran en esta capa, incluidos los mensajes de mensajería confiables. En los mensajes transmitidos, solo se registran los encabezados. Además, los mensajes seguros se registran como cifrados en este nivel, excepto si se usa un transporte seguro como HTTPS.

Nivel incorrecto

Los mensajes con un formato incorrecto son mensajes rechazados por la pila de WCF en cualquier fase del procesamiento. Los mensajes con formato incorrecto se registran as-is: se cifran si son así, con XML no adecuado, etc. maxSizeOfMessageToLog definió el tamaño del mensaje que se va a registrar como CDATA. De forma predeterminada, maxSizeOfMessageToLog es igual a 256 000. Para obtener más información sobre este atributo, consulte la sección Otras opciones.

Otras opciones

Además de los niveles de registro, el usuario puede especificar las siguientes opciones:

• Log Entire Message (logEntireMessage attribute): este valor especifica si se registra todo el mensaje (encabezado del mensaje y cuerpo). El valor predeterminado es false, lo que significa que solo se registra el encabezado. Esta configuración afecta a los niveles de registro de mensajes de servicio y transporte.

• Número máximo de mensajes para registrar (maxMessagesToLog atributo): este valor especifica el número máximo de mensajes que se van a registrar. Todos los mensajes (servicio, transporte y mensajes con formato incorrecto) se cuentan para esta cuota. Cuando se alcanza la cuota, se emite un seguimiento y no se registra ningún mensaje adicional. El valor predeterminado es 10000.

• Tamaño máximo del mensaje que se va a registrar (maxSizeOfMessageToLog atributo): este valor especifica el tamaño máximo de los mensajes para iniciar sesión en bytes. Los mensajes que superan el límite de tamaño no se registran y no se realiza ninguna otra actividad para ese mensaje. Esta configuración afecta a todos los niveles de seguimiento. Si el seguimiento de ServiceModel está activado, se emite un seguimiento de nivel de advertencia en el primer punto de registro (ServiceModelSend* o TransportReceive) para notificar al usuario. El valor predeterminado para los mensajes de nivel de servicio y de transporte es 256K, mientras que el valor predeterminado para los mensajes con errores de formato es 4K.

  Precaución

  El tamaño del mensaje que se calcula para comparar maxSizeOfMessageToLog es el tamaño del mensaje en memoria antes de la serialización. Este tamaño puede diferir de la longitud real de la cadena de mensaje que se registra y, en muchas ocasiones, es mayor que el tamaño real. Como resultado, es posible que los mensajes no se registren. Puede tener en cuenta este hecho especificando que el maxSizeOfMessageToLog atributo sea 10% mayor que el tamaño esperado del mensaje. Además, si se registran mensajes con formato incorrecto, el espacio en disco real utilizado por los registros de mensajes puede ser de hasta 5 veces el tamaño del valor especificado por maxSizeOfMessageToLog.

Si no se define ningún agente de escucha de seguimiento en el archivo de configuración, no se genera ningún resultado de registro independientemente del nivel de registro especificado.

Las opciones de registro de mensajes, como los atributos descritos en esta sección, se pueden cambiar en tiempo de ejecución mediante Instrumental de administración de Windows (WMI). Para ello, se puede acceder a la instancia de AppDomainInfo , que expone estas propiedades booleanas: LogMessagesAtServiceLevel, LogMessagesAtTransportLevely LogMalformedMessages. Por lo tanto, si configura un agente de escucha de seguimiento para el registro de mensajes, pero establece estas opciones false en la configuración, puede cambiarlas más adelante a true cuando se ejecuta la aplicación. Esto habilita eficazmente el registro de mensajes en tiempo de ejecución. Del mismo modo, si habilita el registro de mensajes en el archivo de configuración, puede deshabilitarlo en tiempo de ejecución mediante WMI. Para obtener más información, consulte Uso de Instrumental de administración de Windows para diagnósticos.

El source campo de un registro de mensajes especifica en qué contexto se registra el mensaje: al enviar o recibir un mensaje de solicitud, para una solicitud-respuesta o una solicitud unidireccional, en el modelo de servicio o en la capa de transporte, o en el caso de un mensaje malformado.

Para los mensajes con formato incorrecto, source es igual a Malformed. De lo contrario, el origen tiene los valores siguientes en función del contexto.

Para solicitud/respuesta:

Para solicitud unidireccional:

Filtros de mensajes

Los filtros de mensaje se definen en el messageLogging elemento de configuración de la diagnostics sección de configuración. Se aplican en el nivel de servicio y transporte. Cuando se definen uno o varios filtros, solo se registran los mensajes que coinciden con al menos uno de los filtros. Si no se define ningún filtro, todos los mensajes pasan a través.

Los filtros admiten la sintaxis XPath completa y se aplican en el orden en que aparecen en el archivo de configuración. Un filtro sintácticomente incorrecto produce una excepción de configuración.

Los filtros también proporcionan una característica de seguridad mediante el nodeQuota atributo , que limita el número máximo de nodos del DOM de XPath que se puede examinar para que coincida con el filtro.

En el ejemplo siguiente se muestra cómo configurar un filtro que registra solo los mensajes que tienen una sección de encabezado 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>

Los filtros no se pueden aplicar al cuerpo de un mensaje. Los filtros que intentan manipular el cuerpo de un mensaje se quitan de la lista de filtros. También se emite un evento que indica esto. Por ejemplo, el siguiente filtro se quitaría de la tabla de filtros.

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

Configuración de un agente de escucha personalizado

También puede configurar un agente de escucha personalizado con opciones adicionales. Un agente de escucha personalizado puede ser útil para filtrar los elementos PII específicos de la aplicación de los mensajes antes de registrar. En el ejemplo siguiente se muestra una configuración personalizada del agente de escucha.

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

Debería tener en cuenta que el atributo type debería estar establecido en un nombre de ensamblado certificado del tipo.

Consulte también

• <registroDeMensajes>
• Registro de Mensajes
• Configuración recomendada para el seguimiento y el registro de mensajes