Política MessageLogging

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

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 una disco local (Edge solo para la nube privada) o a 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

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

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

Esquemas

Notas de uso

Cuando adjuntes una política de MessageLogging a un flujo del proxy de API, considera colocarla en Es la respuesta de 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. Si deseas obtener detalles sobre cómo usar PostClientFlow, consulta la referencia de configuración de 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 los mensajes como texto simple, y puedes configurar el registro para que incluya variables, 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 que se envió la solicitud, etcétera. Mensaje de registros perimetrales de forma asíncrona, lo que significa que no se genera latencia a tu API.

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 la nube privada 4.15.07 y versiones anteriores, busca el 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.

En Edge for Private Cloud 4.16.01 y versiones posteriores, configura 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 Message Processor. Ten en cuenta que, en un principio, esta propiedad está marcada como comentario de forma predeterminada.

Nota: El mensaje de respuesta variables en Edge no están disponibles en el flujo de error. Estas variables tampoco están disponibles en PostClientFlow si el flujo anterior era el de errores. Si quieres registrar respuestas información 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 Mensaje variables para obtener más información y ver un ejemplo.

Controla el mensaje de registro marca de tiempo en Edge para la nube privada

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

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

Esta configuración predeterminada en todo el sistema puede anularse para los destinos de syslog con el DateFormat. El comportamiento de esta plantilla se describe en el documentación sobre la clase SimpleDateFormat de Java. Según esa definición, se reemplazará yyyy 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 puede generar una cadena con el siguiente formato:

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

Puedes usar conf_system_apigee.syslogger.dateFormat en el procesador de mensajes de Edge para controlar ese formato. Por ejemplo, cambiar el mensaje formato para:

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

..reemplazando los guiones con 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 una Editor. Si el archivo no existe, créalo:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Configura 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 archivo de propiedades sea propiedad de “apigee” usuario:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicia el procesador de mensajes 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 la pestaña Mensajes Nodos del procesador:

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

Puedes cambiar la ubicación predeterminada del registro si modificas las propiedades message-logging.properties en Message Processor:

• bin_setenv_data_dir - Establece la ruta 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 establece esto en una ruta de acceso 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 como una ruta de acceso absoluta, como conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, mensaje 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á marcado como comentario de forma predeterminada. Consulta Cómo configurar un token que actualmente está marcado como comentario para obtener más información.

Si quieres almacenar archivos de registro en una estructura plana, para que todos los archivos de registro se ubiquen mismo directorio, configura conf/message-logging.properties+enable.flat.directory.structure como true en el archivo message-logging.properties. Los mensajes se almacenan en el directorio especificado por las propiedades anteriores, y los nombres de los archivos toman la forma de {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}

Para establecer estas propiedades, sigue estos pasos:

1. Abre el archivo message-processor.properties en una Editor. Si el archivo no existe, créalo:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Configura 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 archivo de propiedades sea propiedad de “apigee” usuario:
   > 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 ubican en la siguiente ubicación procesadores:

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

Puedes cambiar la ubicación predeterminada del registro modificando las siguientes propiedades en message-logging.properties en los procesadores de mensajes:

• data.dir: Establece la raíz. para el almacenamiento del archivo de registro. Por ejemplo, data.dir=/opt/apigee4/var/log
• log.root.dir: si configuras a una ruta relativa, como log.root.dir=custom/folder/, la ruta se agrega al archivo 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 /messagelog se agregó automáticamente).

Si configuras esto como 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 quieres almacenar archivos de registro en una estructura plana, para que todos los archivos de registro se ubiquen mismo directorio, establece la propiedad enable.flat.directory.structure en true en el archivo message-logging.properties en Message Procesadores. Los mensajes se almacenan en el directorio especificado por las propiedades anteriores, y el archivo toman la forma de {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 usa una sola política de JavaScript para hacer HTTP POST Solicitudes al colector de fuente 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>.
  Consulte también 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

En esta sección, se describen los códigos y mensajes de error que se muestran, y las variables de falla que establece Edge 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.

Errores en la implementación

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

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.

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

• Variables que expone Edge: Referencia de las variables