Política MessageLogging

Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X.

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 en Edge para la nube privada) o en syslog.

Samples

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

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

Esquemas

Notas de uso

Cuando adjuntes una política de MessageLogging a un flujo de proxy de API, considera colocarlo en 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. 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 Verificar clave de API causó el error 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 incluir variables, como la fecha y la hora en que se recibió la solicitud o la respuesta, la identidad del usuario en la solicitud, la dirección IP de origen desde la que se envió la solicitud, etcétera. Edge registra los mensajes de forma asíncrona, lo que significa que tu API no presentará latencia que pueda ser causada por el bloqueo de los textos destacados.

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

En Edge para la nube privada 4.16.01 y posteriores, configura la propiedad conf_message-logging_max.log.message.size.in.kb en el archivo /opt/apigee/customer/application/message-processor.properties y reinicia el procesador de mensajes.

Nota: Las variables de mensaje de respuesta 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 deseas registrar información de respuesta del 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.

Controla 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 en los destinos de syslog con el elemento DateFormat. El comportamiento de esta plantilla se describe en la documentación para la clase SimpleDateFormat de Java. De acuerdo con 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 puede generar una string con este formato:

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

Puedes usar la propiedad conf_system_apigee.syslogger.dateFormat en el procesador de mensajes perimetrales para controlar ese formato. Por ejemplo, si cambias el formato del mensaje a:

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

.

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

Para cambiar el formato, haz lo siguiente:

1. Abre el archivo message-processor.properties en un editor. Si el archivo no existe, créelo:
   > 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 pertenezca al usuario “apigee”:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicia el procesador de mensajes perimetrales:
   > /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 posteriores

De forma predeterminada, los registros de mensajes de la nube privada se encuentran en el siguiente directorio de 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 predeterminada del registro, puedes modificar las propiedades del archivo message-logging.properties en Message Processor:

• bin_setenv_data_dir: Establece la ruta raíz para el almacenamiento del archivo de registro. Por ejemplo, bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir: Si estableces 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 estableces esto en una ruta de acceso 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 tiene comentarios para obtener más información.

Si deseas almacenar archivos de registro en una estructura de archivos plana para que todos los archivos de registro se coloquen en el mismo directorio, configura conf/message-logging.properties+enable.flat.directory.structure como verdadero en el archivo message-logging.properties. Los mensajes se almacenan en el directorio especificado por 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éelo:
   > 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 pertenezca al usuario “apigee”:
   > 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 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 predeterminada del registro, modifica las siguientes propiedades del archivo message-logging.properties en los procesadores de mensajes:

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

Por ejemplo, la combinación de las dos propiedades configuraría el directorio de registro en /opt/apigee4/var/log/custom/folder/messagelog/ (ten en cuenta que /messagelog se agrega 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 quieres almacenar archivos de registro en una estructura de archivos plana para que todos los archivos de registro se coloquen en el mismo directorio, configura la propiedad enable.flat.directory.structure como verdadera en el archivo message-logging.properties en Message Processor. Los mensajes se almacenan en el directorio especificado por las propiedades anteriores y los nombres de archivo tienen la forma {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 HTTP POST al recopilador 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>.
  Consulte también esta publicación de 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 error que configura 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 expuestas por Edge: Referencia de variables