Política MessageLogging

Qué

Una de las mejores formas de rastrear problemas en el entorno de ejecución de la API es registrar mensajes. Puede adjuntar y configurar una política de MessageLogging en su API para registrar mensajes personalizados en syslog.

Ejemplos

Syslog

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Un uso común del tipo de política MessageLogging es acceder a una cuenta syslog. Cuando se configura para syslog, un proxy de API reenvía los mensajes de registro de Apigee a un servidor syslog remoto. Ya debe tener un servidor syslog disponible. Si no es así, están disponibles los servicios de administración de registros públicos, como Splunk, Sumo Logic y Loggly. Consulta Configura servicios de administración de registros de terceros.

Por ejemplo, imagina que necesitas registrar información sobre cada mensaje de solicitud que tu API recibe de las aplicaciones para consumidores. El valor 3f509b58 representa un valor clave específico para el servicio de registro. Si tienes una cuenta de registro, sustituye la clave de registro. El mensaje de registro que se genera se propaga con cuatro valores: la organización, el proxy de API y el nombre del entorno asociado con la transacción, junto con el valor de un parámetro de consulta en el mensaje de solicitud.

Syslog por TLS/SSL

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

Puedes enviar mensajes a proveedores de registro de mensajes de terceros a través de TLS/SSL si agregas el bloque <SSLInfo>.

Rotación del archivo: tamaño

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotación de archivo en función del tamaño.

Rotación del archivo: tiempo

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotación de los archivos en función del tiempo.

Rotación del archivo: tiempo y tamaño

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotación de los archivos en función del tiempo y el tamaño.

Transmisión habilitada

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

Registro de mensajes con transmisiones habilitadas


Referencia del elemento

Usa los elementos de la siguiente tabla para configurar el tipo de política de MessageLogging.

Para enviar syslog a Splunk, Sumo Logic o Loggly, consulta Configura servicios de administración de registros de terceros.

Nombre del campo Descripción del campo
Message

Compila el mensaje que se enviará a syslog y combina texto con variables para capturar la información que deseas. Consulta las muestras.

Host El nombre de host o la dirección IP del servidor donde se debe enviar syslog. Si no incluyes este elemento, el valor predeterminado será localhost.
Port Puerto donde se ejecuta syslog. Si no incluyes este elemento, el valor predeterminado será 514.
Protocol TCP o UDP (predeterminado). Si bien UDP es más eficaz, el protocolo TCP garantiza la entrega del registro de mensajes al servidor syslog. Para enviar mensajes de syslog a través de TLS y SSL, solo se admite TCP.
FormatMessage

true o false (predeterminado)

Opcional, pero <FormatMessage>true</FormatMessage> es obligatorio para usar con Loggly.

Este elemento te permite controlar el formato del contenido generado por Apigee precedido por el mensaje. Si se configura como verdadero, el mensaje syslog está precedido una cantidad fija de caracteres, lo que te permite filtrar esa información de los mensajes. Este es un ejemplo del formato fijo:

<14>1 2016-02-23T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

La información generada por Apigee incluye lo siguiente:

  • <14>: Una puntuación de prioridad (consulta el Protocolo Syslog) según el nivel de registro y el nivel de instalación del mensaje.
  • 1. La versión de syslog actual.
  • Fecha con un desplazamiento UTC (UTC = +0000).
  • UUID del procesador de mensajes.
  • "Apigee - - - "

Si se configura como falso (predeterminado), al mensaje no se le agregan los caracteres fijos.

PayloadOnly

true o false (predeterminado)

Este elemento establece el formato de los mensajes generados por Apigee para que contengan solo el cuerpo del mensaje syslog, sin los caracteres precedidos por FormatMessage.

Si no incluyes este elemento o dejas el campo vacío, el valor predeterminado será false.

Consulta FormatMessage.

SSLInfo

Te permite registrar mensajes a través de SSL/TLS. Se usa con el subelemento <Enabled>true</Enabled>.

Si no incluyes este elemento o dejas el campo vacío, el valor predeterminado será falso (sin TLS/SSL).


<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

Puedes configurar la etiqueta <SSLInfo> de la misma forma en que puedes hacerlo en un TargetEndpoint, además de habilitar TLS/SSL bidireccional, como se describe en Referencia de configuración de proxy de API. Solo se admite el protocolo TCP.

logLevel

Opcional.

Valores válidos: INFO (predeterminado), ALERT, WARN, ERROR

Establezca un nivel específico de información para incluir en el registro de mensajes.

Si usas el elemento FormatMessage (si lo estableces en verdadero), la configuración logLevel afectará la puntuación de prioridad calculada (el número dentro de los corchetes angulares) en la información generada por Apigee que se agrega al mensaje.

Esquemas


Notas de uso

Cuando adjuntes una política de MessageLogging a un flujo de proxy de API, considera colocarla en la respuesta ProxyEndpoint, en un flujo especial llamado PostClientFlow. El PostClientFlow se ejecuta después de que la respuesta se envía al cliente solicitante, lo que garantiza que todas las métricas estén disponibles para el registro. Para obtener detalles sobre el uso de PostClientFlow, consulta Referencia de configuración del proxy de API.

El PostClientFlow es especial de dos maneras:

  1. Solo se ejecuta como parte del flujo de respuesta.
  2. Es el único flujo que se ejecuta después de que el proxy entra en el estado de error.

Debido a que se ejecuta sin importar si el proxy se realizó de forma correcta o no, puedes colocar las políticas MessageLogging en PostClientFlow y estar seguro de que siempre se ejecutarán.

La siguiente imagen de Trace muestra una política de MessageLogging que se ejecuta como parte del PostClientFlow, después de que se ejecuta la DefaultFaultRule:

En este ejemplo, la política de verificación de la clave de la API causó la falla debido a una clave no válida.

A continuación, se muestra la definición de ProxyEndpoint que incluye PostPostFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Apigee registra mensajes como texto simple y puedes configurar el registro para incluir variables, como la fecha y la hora en que se recibió la solicitud o respuesta, la identidad del usuario en la solicitud, la dirección IP de origen desde la cual la solicitud fue enviada, y así sucesivamente. Apigee registra los mensajes de forma asíncrona, lo que significa que no se producirá ninguna latencia en la API que pueda generar los textos destacados de bloqueo.

La política MessageLogging escribe los mensajes registrados en la memoria en un búfer. El registrador de mensajes lee los mensajes del búfer y, luego, escribe en el destino que configuras. Cada destino tiene su propio búfer.

Si la tasa de escritura en el búfer aumenta más allá de la tasa de lectura, el buffer se desborda y falla el registro. Si esto sucede, es posible que aparezca un mensaje que contenga lo siguiente en el archivo de registro:

Log message size exceeded. Increase the max message size setting

Aumenta la propiedad max.log.message.size.in.kb (valor predeterminado = 128 KB) en el archivo message-logging.properties.

Valores predeterminados para variables en plantillas de mensajes

Se pueden especificar valores predeterminados para cada variable en la plantilla de mensaje por separado. Por ejemplo, si la variable request.header.id no se puede resolver, entonces su valor se reemplaza por el valor unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Se puede especificar un valor predeterminado común para todas las variables sin resolver mediante la configuración del atributo defaultVariableValue en el elemento Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Configura servicios de administración de registros de terceros

La política MessageLogging te permite enviar mensajes syslog a servicios de administración de registros de terceros, como Splunk, Sumo Logic y Loggly. Si deseas enviar syslog a uno de esos servicios, consulta la documentación de ese servicio para configurar el host, el puerto y el protocolo del servicio y, luego, establece el elemento Syslog en esta política según corresponda.

Consulta la siguiente documentación para la configuración de administración de registros de terceros:

  • Splunk (selecciona la versión del producto)
    Consulta también esta publicación de la comunidad de Apigee: Cómo registrar mensajes en Splunk
  • Sumo Logic
  • Loggly
    Cuando se usa Loggly, <FormatMessage>true</FormatMessage> es obligatorio en la política como elemento secundario del elemento <Syslog>.
    Consulta esta publicación de la comunidad de Apigee para obtener más información sobre el registro de mensajes en Loggly: Registrar 7 mensajes en Loggly

Referencia de errores

En esta sección, se describen los códigos de error y los mensajes de error que se muestran y las variables de fallas que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa
steps.messagelogging.StepDefinitionExecutionFailed 500 Consulta la cadena de errores.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa Corregir
InvalidProtocol La implementación de la política MessageLogging puede mostrar este error si el protocolo especificado en el elemento <Protocol> no es válido. Los protocolos válidos son TCP y UDP. Para enviar mensajes de syslog a través de TLS y SSL, solo se admite TCP.
InvalidPort La implementación de la política MessageLogging puede generar este error si el número de puerto no se especifica en el elemento <Port> o si no es válido. El número de puerto debe ser un número entero mayor que cero.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. messagelogging.ML-LogMessages.failed = true

Ejemplo de respuesta de error

{
   "fault":{
      "detail":{
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Ejemplo de regla de falla

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>


Variables de flujo

Las siguientes variables se propagan sobre fallas de política.

  • messagelogging.failed
  • messagelogging.{stepdefinition-name}.failed

Temas relacionados