Política MessageLogging

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué

La política MessageLogging te permite registrar mensajes personalizados en Cloud Logging o syslog. Puedes usar la información en los registros para varias tareas, como el seguimiento de problemas en el entorno de ejecución de la API.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Existen dos maneras de usar la política MessageLogging:

• Con el elemento <CloudLogging>, se registran los mensajes en Cloud Logging. Para usar este método, debes habilitar las API de Cloud Logging en tu proyecto de Google Cloud. A fin de obtener más información sobre cómo habilitar las API para un proyecto de Google Cloud, consulta Habilita o inhabilita servicios.
• El elemento <Syslog> registra los mensajes en syslog, un protocolo estándar para enviar registros del sistema o mensajes de eventos a un servidor específico. Para usar este método, debes tener un Servidor Syslog disponible. Si no lo haces, puedes usar 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.

Nota: No puedes usar el elemento <CloudLogging> ni el elemento <Syslog> en la misma política.

Elemento <MessageLogging>

Define una política <MessageLogging>.

Valor predeterminado	Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio?	Obligatorio
Tipo	TYPE
Elemento principal	n/a
Elementos secundarios	<CloudLogging> <Syslog> <logLevel>

El elemento <MessageLogging> usa la siguiente sintaxis:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <MessageLogging>:

Nombre del campo	Descripción del campo
CloudLogging	Configura los mensajes que se registrarán en Cloud Logging.
Syslog	Configura los mensajes que se van a registrar en syslog.

Ejemplos

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
</MessageLogging>

En este ejemplo, se ilustra el uso de las plantillas de mensajes. Dado que el elemento Message contiene las variables de flujo

{"{message.queryparam.key}": "{message.queryparam.value}"}

cuando alguien llama al proxy con los valores message.queryparam.key = "fruit" y message.queryparam.value = "apple", la entrada de registro resultante sería {"fruit": "apple"}.

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

En este ejemplo, supongamos que necesitas registrar la información sobre cada mensaje de solicitud que recibe tu API de las aplicaciones para consumidores. El valor 3f509b58 representa un par clave-valor específico para el servicio de Loggly. Si tienes una cuenta de Loggly, sustituye la clave. 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. El formato de las marcas de tiempo será similar a 230704-13:42:17.376, según el formato especificado en el elemento DateFormat.

Nota: Los elementos Host y Port no pueden hacer referencia a las variables. Deben contener valores estáticos.

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>

Agrega el bloque <SSLInfo> para enviar mensajes a proveedores de registro de mensajes de terceros a través de TLS/SSL.

Referencia del elemento secundario

En las siguientes secciones, se describen los elementos secundarios de <MessageLogging>.

<CloudLogging>

Usa el elemento <CloudLogging> para registrar los mensajes en Cloud Logging.

Nota: Para usar <CloudLogging>, debes habilitar las API de Cloud Logging en tu proyecto de Google Cloud. A fin de habilitar las API para un proyecto de Google Cloud, consulta Habilita e inhabilita servicios. El elemento <CloudLogging> de la política MessageLogging está disponible en Apigee y las versiones de Apigee Hybrid 1.7.0 y posteriores.

Nombre del campo	¿Es obligatorio?	Descripción
LogName	Sí	Nombre del registro. El nombre del registro debe estar en formato projects/{PROJECT_ID}/logs/{LOG_ID}. Puedes usar variables en lugar de {PROJECT_ID} y {LOG_ID}.
Message	Sí	El mensaje que se registrará. El mensaje tiene un atributo contentType, cuyo valor puede ser text/plain o application/json para los mensajes de texto y JSON, respectivamente. Consulta las muestras. Nota: Las variables de respuesta no estarán disponibles en PostClientFlow después de un flujo de error. Usa un objeto message. para registrar la información de la respuesta ante situaciones de errores y éxito. Consulta también las Notas de uso. Nota: El elemento <Message> admite la función de sustitución dinámica de string llamada plantillas de mensajes,
Label	No	La etiqueta que se adjuntará al mensaje de registro, si corresponde. Tendrán el formato de un par clave-valor como el siguiente: <Label> <Key>key1</Key> <Value>value1</Value> </Label>
ResourceType	No (el valor predeterminado es global)	Representa el recurso supervisado que genera los registros.

Autenticación para Cloud Logging

Para usar el elemento <CloudLogging>, debes implementar el proxy de API a fin de usar la autenticación de Google. Apigee usará las credenciales correspondientes a la identidad de la cuenta de servicio que especifiques en las solicitudes salientes a Cloud Logging. Para obtener más información, consulta Usa la autenticación de Google. La cuenta de servicio que conectes a tu proxy de API en el momento de la implementación debe tener un rol con el permiso logging.logEntries.create. Para obtener más información sobre los roles de Identity and Access Management (IAM) para <CloudLogging>, consulta Guía de control de acceso.

<Syslog>

Usa el elemento <Syslog> a fin de configurar los mensajes que se van a registrar en syslog. Cuando usas <Syslog>, un proxy de API reenvía los mensajes de registro de Apigee a un Servidor Syslog remoto. Para usar este método, debes tener un Servidor Syslog disponible. Si no lo haces, 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.

Nombre del campo	¿Es obligatorio?	Descripción del campo
Message	Sí	El mensaje que se registrará. El mensaje tiene un atributo contentType, cuyo valor puede ser text/plain o application/json para los mensajes de texto y JSON, respectivamente. Consulta las muestras. Nota: El elemento <Message>> es compatible con la función de sustitución de string dinámica llamada plantillas de mensajes, Nota: Las variables de respuesta no estarán disponible en PostClientFlow después de un flujo de error. Usa un objeto message para registrar la información de la respuesta ante situaciones de errores y éxito. Consulta también las Notas de uso.
Host	No	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	No	Puerto donde se ejecuta syslog. Si no incluyes este elemento, el valor predeterminado será 514.
Protocol	No	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	No, pero se requiere <FormatMessage>true</FormatMessage> para usar con Loggly.	true o false (predeterminado) Este elemento te permite controlar el formato del contenido generado por Apigee precedido por el mensaje. Si se configura como verdadero, el mensaje syslog recibe una cantidad fija de caracteres, lo que te permite filtrar esa información de los mensajes. Este es un ejemplo para el formato fijo: <14>1 2023-03-20T09: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. Nota: Si configuras <FormatMessage>false</FormatMessage>, el mensaje de registro aún incluye la puntuación de prioridad y la fecha. Si deseas dar formato al mensaje de registro para que solo incluya el cuerpo del mensaje, configura <PayloadOnly>true</PayloadOnly>. Consulta PayloadOnly.
PayloadOnly	No	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 que preceden y se especifican por FormatMessage. Si no incluyes este elemento o dejas el campo vacío, el valor predeterminado será false. Consulta FormatMessage. Nota: La configuración <PayloadOnly>true</PayloadOnly> anula la configuración de FormatMessage.
DateFormat	No	Una string de plantilla de formato para usar en el formato de la marca de tiempo de cada mensaje de registro. De forma predeterminada, Apigee usa yyyy-MM-dd'T'HH:mm:ss.SSSZ. El comportamiento de esta plantilla se describe en la documentación de la clase SimpleDateFormat de Java. Según esa definición, yyyy en la string de formato 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.
SSLInfo	No	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 de un TargetEndpoint, además de habilitar TLS/SSL de forma bidireccional, como se describe en Referencia de configuración de proxy de API. Solo se admite el protocolo TCP.

---

<logLevel>

Los valores válidos para el elemento <logLevel> son: INFO (predeterminado), ALERT, WARN y ERROR.

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

Si usas el elemento <logLevel> (si lo estableces en verdadero), la configuración 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.

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.

Nota: Es importante tener en cuenta que la variable de flujo response no está disponible en PostClientFlow una vez que el procesamiento ingresa al estado de error. En su lugar, puedes usar la variable message para establecer los valores de la política MessageLogging de PostPostFlow, a fin de asegurarte de que se establecerán tanto si el estado de error correspondía al contexto anterior como si no. Para obtener más información y ejemplos, consulta Referencia de variables de flujo.

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 depuración 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 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: la respuesta se muestra mientras se escriben. Como resultado, no se introduce latencia en tu API mediante el bloqueo de textos destacados. Puede haber ocasiones en que los registros no se escriban sin que se muestre un error, pero estos eventos son poco frecuentes.

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.

Nota: Las llamadas al proxy se ejecutan correctamente cuando el registro falla

Debido a que el registro de mensajes se escribe primero en el búfer, el proxy de API continuará con la ejecución correcta incluso si el registro de mensajes falla al final (por ejemplo, si se produce una falla en la conexión con el destino).

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 encuentres uno de los siguientes mensajes en el archivo de registro:

• Usa <CloudLoggingg> de la siguiente manera:

  steps.messagelogging.TooManyPendingLoggingRequest

• Usa <Syslog> de la siguiente manera:

  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.

Nota: Las variables del mensaje de respuesta en Apigee 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 message. Puedes usar este objeto para obtener encabezados y otra información de la respuesta, ya sea que haya un error o no. Consulta la referencia de variables de flujo para obtener más información y un ejemplo.

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>

Nota: El valor de variable predeterminado no puede contener espacios.

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 comunidad de Apigee: Registra mensajes en Splunk
• Sumo Logic
  • Consulta también esta publicación de comunidad de Apigee: Configura Logging con Sumo Logic
  • 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: Cómo registrar en Sumo Logic mediante JavaScript y HTTP.
• 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: Registrar mensajes en Loggly

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla 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.
steps.messagelogging.InvalidGoogleCloudLogName	500	Este error se produce cuando LogName no se evalúa como el formato válido de projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage	500	Este error se produce cuando el valor de los atributos contentType se eligió como application/json, pero el valor del mensaje real no es una string JSON válida.
steps.messagelogging.TooManyPendingLoggingRequest	500	Se produce este error cuando hay más de 2,500 solicitudes pendientes que aún no se escriben en Cloud Logging. El límite de 2,500 es para cada Pod del entorno de ejecución de Apigee. Por ejemplo, si el tráfico se distribuye a través de dos instancias de Pods del entorno de ejecución de Apigee, el límite efectivo es de 5,000 solicitudes.

-

Errores en la implementación

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

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Nombre del error	Causa	Corregir
InvalidProtocol	La implementación de la política de MessageLoggingpuede generar 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 de MessageLogging puede fallar con este error si no se especifica el número de puerto en el elemento <Port> o 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.

Nota: Las llamadas al proxy se ejecutan correctamente cuando el registro falla

Existe una diferencia entre los errores de política y los de registro de mensajes. Aquí, las variables de flujo se propagan solo cuando falla la política, no el registro de mensajes. Debido a que el registro de mensajes se escribe primero en el búfer, el proxy de la API continuará con la ejecución correcta incluso si el registro de mensajes falla al final (por ejemplo, si se produce una falla en la conexión con el proveedor syslog externo). Asegúrate de revisar los registros con regularidad para garantizar que el registro ocurra como se espera.

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

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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

Nota: Las llamadas al proxy se ejecutan correctamente cuando el registro falla

Existe una diferencia entre los errores de política y los de registro de mensajes. Aquí, las variables de flujo se propagan solo cuando falla la política, no el registro de mensajes. Debido a que el registro de mensajes se escribe primero en el búfer, el proxy de la API continuará con la ejecución correcta incluso si el registro de mensajes falla al final (por ejemplo, si se produce una falla en la conexión con el proveedor syslog externo). Asegúrate de revisar los registros con regularidad para garantizar que el registro ocurra como se espera.

---

Temas relacionados

• Variables expuestas por Apigee: Referencia de variables de flujo