Política MessageLogging

Estás viendo la documentación de Apigee Edge.
Ve a la documentación de Apigee X. info

Qué

Una de las mejores formas de rastrear problemas en el entorno de ejecución de la API es registrar mensajes. Puedes adjuntar y configurar una política de MessageLogging en tu API para registrar mensajes personalizados en un disco local (solo Edge para la nube privada) o en syslog.

Ejemplos

<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>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<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>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

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

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

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

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

Referencia del elemento

Usa los siguientes elementos para configurar el tipo de política de MessageLogging.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

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

Esquemas

Notas de uso

Cuando adjuntas 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 su registro. Para obtener detalles sobre el uso de PostClientFlow, consulta la Referencia de configuración del proxy de API.

El PostClientFlow es especial de las siguientes 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 seguimiento muestra una política MessageLogging que se ejecuta como parte del PostClientFlow, después de que se ejecuta 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>

Edge 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. Edge registra los mensajes de forma asíncrona, lo que significa que no se produce ninguna latencia en la API que pueda generar los textos destacados de bloqueo.

La política MessageLogging escribe en un búfer los mensajes registrados en la memoria. 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 búfer se sobre carga y el registro fallará. Si esto sucede, es posible que aparezca un mensaje con la siguiente información en el archivo de registro:

Log message size exceeded. Increase the max message size setting

Si encuentras este problema en Edge para una nube privada 4.15.07 y versiones anteriores, busca el archivo message-logging.properties y usa esta solución:

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

Para Edge para la nube privada 4.16.01 y versiones posteriores, establece la propiedad conf/message-logging.properties+max. log.message.size.in.kb en el archivo /opt/apigee/customer/application/message-processor.properties y reinicia el procesador de mensajes. Ten en cuenta que esta propiedad está inicialmente comentada de forma predeterminada.

Nota: Las variables del mensaje de respuesta en Edge no están disponibles en el flujo de errores. Estas variables tampoco están disponibles en PostClientFlow si el flujo anterior era el de errores. Si quieres registrar la información de respuesta de PostClientFlow, usa el objeto message. Puedes usar este objeto para obtener encabezados y otra información de la respuesta, ya sea que haya un error o no. Consulta Variables de mensaje para obtener más información y un ejemplo.

Cómo controlar la marca de tiempo del mensaje de registro en Edge para la nube privada

De forma predeterminada, la marca de tiempo de todos los mensajes de registro tiene el siguiente formato:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Este valor predeterminado en todo el sistema se puede anular para los destinos de syslog con el elemento DateFormat. El comportamiento de esta plantilla se describe en la documentación de la clase SimpleDateFormat de Java. Según esa definición, yyyy se reemplazará por un año de 4 dígitos, MM se reemplazará por un número de mes de 2 dígitos, y así sucesivamente. El formato anterior podría generar una cadena de este tipo:

2022-09-28T22:38:11.721+0000

Puedes usar la propiedad conf_system_apigee.syslogger.dateFormat en el Edge Message Processor para controlar ese formato. Por ejemplo, cambiar el formato del mensaje a lo siguiente:

yy/MM/dd'T'HH:mm:ss.SSSZ

..reemplazando los guiones por barras diagonales y acortando a un año de 2 dígitos, se registra una marca de tiempo en el siguiente formato:

22/09/28T22:38:11.721+0000

Para cambiar el formato, sigue estos pasos:

1. Abre el archivo message-processor.properties en un editor. Si el archivo no existe, créalo:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Establece las propiedades como desees:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Guarda los cambios.
4. Asegúrate de que el usuario "apigee" sea el propietario del archivo de propiedades:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicia el Message Processor de Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Ubicación del archivo de registro en Edge para la nube privada

Edge para la nube privada 4.16.01 y versiones posteriores

De forma predeterminada, los registros de mensajes de la nube privada se encuentran en el siguiente directorio en los nodos del procesador de mensajes:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Para cambiar la ubicación de registro predeterminada, modifica las propiedades del archivo message-logging.properties en los procesadores de mensajes:

• bin_setenv_data_dir: Establece la ruta de acceso raíz para el almacenamiento de archivos de registro. Por ejemplo, bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir: Si configuras esto en una ruta relativa, como conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  , si configuras esto en una ruta absoluta, como conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, los registros de mensajes se almacenarán en /opt/apigee/var/log/messages/messagelog/. Una ruta de acceso absoluta tiene prioridad sobre bin_setenv_data_dir.
  
  Ten en cuenta que debes hacer referencia a la propiedad como conf/message-logging.properties+log.root.dir porque está comentada de forma predeterminada. Consulta Cómo configurar un token que actualmente está comentado para obtener más información.

Si deseas almacenar archivos de registro en una estructura de archivos planos para que todos los archivos de registro se coloquen en el mismo directorio, establece conf/message-logging.properties+enable.flat.directory.structure como verdadero en el archivo message-logging.properties. Los mensajes se almacenan en el directorio que especifican las propiedades anteriores, y los nombres de archivo tienen el formato {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Para configurar estas propiedades, sigue estos pasos:

1. Abre el archivo message-processor.properties en un editor. Si el archivo no existe, créalo:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Establece las propiedades como desees:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Guarda los cambios.
4. Asegúrate de que el usuario "apigee" sea el propietario del archivo de propiedades:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicia el componente de Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge para la nube privada 4.15.07 y versiones anteriores

De forma predeterminada, los registros de mensajes se encuentran en la siguiente ubicación en los procesadores de mensajes:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Para cambiar la ubicación de registro predeterminada, modifica las siguientes propiedades en el archivo message-logging.properties de los procesadores de mensajes:

• data.dir: Establece la ruta de acceso raíz para el almacenamiento de archivos de registro. Por ejemplo, data.dir=/opt/apigee4/var/log
• log.root.dir: Si lo configuras en una ruta de acceso relativa, como log.root.dir=custom/folder/, la ruta se adjunta a la ubicación de data.dir.

Por ejemplo, la combinación de las dos propiedades establecería el directorio de registro en /opt/apigee4/var/log/custom/folder/messagelog/ (ten en cuenta que se agrega /messagelog automáticamente).

Si estableces esto en una ruta de acceso absoluta, como log.root.dir=/opt/apigee4/var/log/messages, los registros de mensajes se almacenarán en /opt/apigee4/var/log/messages/messagelog/. Una ruta de acceso absoluta en log.root.dir tiene prioridad sobre data.dir.

Si deseas almacenar los archivos de registro en una estructura de archivos plana para que todos los archivos de registro se coloquen en el mismo directorio, establece la propiedad enable.flat.directory.structure en "true" en el archivo message-logging.properties en los procesadores de mensajes. Los mensajes se almacenan en el directorio especificado por las propiedades anteriores, y los nombres de los archivos tienen el formato {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Valores predeterminados para las variables en las plantillas de mensajes

Se pueden especificar valores predeterminados para cada variable en la plantilla de mensajes 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 esta publicación de la comunidad de Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • Consulta también esta publicación de la comunidad de Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • Para ver un ejemplo completo en el que se usa Sumo Logic como el servicio de registros, consulta la siguiente publicación de comunidad de Apigee. La solución utiliza una sola política de JavaScript para realizar solicitudes POST HTTP al colector de fuentes HTTP de Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html.
• Loggly
  Cuando se usa Loggly, <FormatMessage>true</FormatMessage> es obligatorio en la política como un 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: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Referencia de errores

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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

• Variables expuestas por Edge: Referencia de variables