Política MessageLogging

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

Consulta la documentación de Apigee Edge.

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

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Hay dos formas de usar la política MessageLogging:

• El elemento <CloudLogging> registra mensajes en Cloud Logging. Para usar este método, debes habilitar las APIs Cloud Logging en tu proyecto de Google Cloud. Para obtener más información sobre cómo habilitar APIs en un proyecto de Google Cloud, consulta el artículo sobre cómo habilitar e inhabilitar servicios.
• El elemento <Syslog> registra mensajes en syslog, un protocolo estándar para enviar mensajes de registro del sistema o de eventos a un servidor específico. Para usar este método, debes tener un servidor syslog disponible. Si no lo haces, puedes usar servicios públicos de gestión de registros, como Splunk, Sumo Logic y Loggly. Consulta Configurar servicios de gestión de registros de terceros.

Nota: No puede usar los elementos <CloudLogging> y <Syslog> en la misma política.

Elemento <MessageLogging>

Define una política <MessageLogging>.

Valor predeterminado	Consulta la pestaña Política predeterminada que aparece más abajo.
¿Es obligatorio?	Obligatorio
Tipo	TIPO
Elemento principal	n/a
Elementos secundarios	<CloudLogging> <Syslog> <logLevel>

El elemento <MessageLogging> utiliza 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>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

Atributo	Predeterminado	¿Es obligatorio?	Descripción
name	N/A	Obligatorio	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
continueOnError	falso	Opcional	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
enabled	true	Opcional	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
async	falso	Obsoleto	Este atributo está obsoleto.

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <MessageLogging>:

Nombre del campo	Descripción del campo
CloudLogging	Configura los mensajes para que se registren en Cloud Logging.
Syslog	Configura los mensajes para que se registren 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>api</ResourceType>
    </CloudLogging>
</MessageLogging>

En este ejemplo se muestra el uso de plantillas de mensajes. Como 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 información sobre cada mensaje de solicitud que tu API recibe de las aplicaciones de consumidor. El valor 3f509b58 representa un valor de clave específico del servicio loggly. Si tienes una cuenta de Loggly, sustituye tu clave de Loggly. El mensaje de registro que se genera se rellenará con cuatro valores: la organización, el proxy de API y el nombre del entorno asociados a 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 variables. Deben contener valores estáticos.

Syslog a través de 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 externos de registro de mensajes a través de TLS/SSL añadiendo el bloque <SSLInfo>.

Referencia de elemento secundario

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

<CloudLogging>

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

Nota: Para usar <CloudLogging> debes habilitar las APIs Cloud Logging en tu proyecto de Google Cloud. Para habilitar APIs en un proyecto de Google Cloud, consulta el artículo sobre cómo habilitar e inhabilitar servicios. El elemento <CloudLogging> de la política MessageLogging está disponible en Apigee y Apigee Hybrid v1.7.0 y versiones posteriores.

Nombre del campo	¿Es obligatorio?	Descripción
LogName	Sí	Nombre del registro. El nombre del registro debe tener el formato projects/{PROJECT_ID}/logs/{LOG_ID}. Puedes usar variables en lugar de {PROJECT_ID} y {LOG_ID}. Nota: LogName especifica el nombre de recurso de un registro de Cloud Logging al que se enviará la entrada de registro. Mediante el uso de variables, la política MessageLogging te permite insertar dinámicamente un valor de nombre diferente y único para cada entrada LogName. Sin embargo, no te recomendamos que crees dinámicamente nombres de registro únicos con valores que puedan cambiar de una solicitud a otra, ya que puede provocar problemas de cardinalidad alta. En su lugar, te recomendamos que uses un nombre fijo y significativo de un conjunto fijo de nombres para LogName.
Message	Sí	El mensaje que se va a registrar. El mensaje tiene un atributo contentType, cuyo valor puede ser text/plain o application/json para mensajes de texto y JSON, respectivamente. Consulta los ejemplos. Nota: Las variables de respuesta no estarán disponibles en PostClientFlow después de un flujo de errores. Usa un message. para registrar información de respuesta en situaciones de error y de éxito. Consulta también las notas de uso. Nota: El elemento <Message> admite la función de sustitución de cadenas dinámicas llamada plantillas de mensajes.
Label	No	Etiqueta que se adjuntará al mensaje de registro, si la hay. Se mostrarán en forma de par clave-valor, como en el siguiente ejemplo: <Label> <Key>key1</Key> <Value>value1</Value> </Label>
ResourceType	No (se aplica el valor predeterminado global)	Representa el recurso monitorizado que genera los registros.

Autenticación de Cloud Logging

Para usar el elemento <CloudLogging>, debes implementar tu proxy de API para que use 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 Usar la autenticación de Google.

La cuenta de servicio que adjuntes a tu proxy de API en el momento de la implementación debe tener un rol con el permiso logging.logEntries.create. A menos que necesites un control más detallado, te recomendamos que uses el rol predefinido más inclusivo roles/logging.logWriter para la cuenta de servicio. Para obtener más información sobre los roles de Gestión de Identidades y Accesos (IAM) de <CloudLogging>, consulta la guía de control de acceso.

Despliegue de proxies en Apigee hybrid

Si usas Apigee hybrid, la cuenta de servicio de tiempo de ejecución que crees para Apigee hybrid debe suplantar a la cuenta de servicio proxy para hacer llamadas autenticadas en su nombre. Por lo tanto, la cuenta de servicio del entorno de ejecución de Apigee hybrid debe tener el rol iam.serviceAccountTokenCreator para la cuenta de servicio del proxy.

<Syslog>

Usa el elemento <Syslog> para configurar los mensajes que se registrarán en syslog. Cuando usas <Syslog>, un proxy de API reenvía 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, puedes usar servicios de gestión de registros públicos, como Splunk, Sumo Logic y Loggly. Consulta Configurar servicios de gestión de registros de terceros.

Nombre del campo	¿Es obligatorio?	Descripción del campo
Message	Sí	El mensaje que se va a registrar. El mensaje tiene un atributo contentType, cuyo valor puede ser text/plain o application/json para mensajes de texto y JSON, respectivamente. Consulta los ejemplos. Nota: El elemento <Message>> admite la función de sustitución de cadenas dinámicas llamada plantillas de mensajes. Nota: Las variables de respuesta no estarán disponibles en PostClientFlow después de un flujo de errores. Usa message. para registrar información de respuesta en situaciones de error y de éxito. Consulta también las notas de uso.
Host	No	El nombre de host o la dirección IP del servidor al que se debe enviar el syslog. Si no incluye este elemento, el valor predeterminado será localhost.
Port	No	Puerto en el que se ejecuta syslog. Si no incluye este elemento, el valor predeterminado es 514.
Protocol	No	TCP o UDP (predeterminado). Aunque UDP tiene un mejor rendimiento, el protocolo TCP garantiza que los registros de mensajes se envíen al servidor syslog. Para enviar mensajes syslog a través de TLS/SSL, solo se admite TCP.
FormatMessage	No, pero <FormatMessage>true</FormatMessage> es obligatorio para usarlo con Loggly.	true o false (predeterminado) Este elemento le permite controlar el formato del contenido generado por Apigee que se añade al principio del mensaje. Si se le asigna el valor "true", se antepondrá un número fijo de caracteres al mensaje syslog, lo que te permitirá filtrar esa información de los mensajes. A continuación, se muestra un ejemplo del formato fixed: <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) basada en el nivel de registro y el nivel de instalación del mensaje. 1: la versión actual de syslog. Fecha con un desfase de UTC (UTC = +0000). UUID del procesador de mensajes. "Apigee - - - " Si se le asigna el valor false (predeterminado), el mensaje no se antepondrá con esos caracteres fijos. Nota: Si defines <FormatMessage>false</FormatMessage>, el mensaje de registro seguirá incluyendo la puntuación de prioridad y la fecha. Para dar formato al mensaje de registro de forma que solo incluya el cuerpo del mensaje, define <PayloadOnly>true</PayloadOnly>. Consulta PayloadOnly.
PayloadOnly	No	true o false (predeterminado) Este elemento define el formato de los mensajes generados por Apigee para que solo contengan el cuerpo del mensaje syslog, sin los caracteres antepuestos especificados por FormatMessage. Si no incluye este elemento o lo deja vacío, el valor predeterminado es false. Consulta FormatMessage. Nota: Si se define <PayloadOnly>true</PayloadOnly>, se anula el ajuste de FormatMessage.
DateFormat	No	Una cadena de plantilla de formato que se usa para dar formato a 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 cadena de formato se sustituirá por un año de 4 dígitos, MM se sustituirá por un número de mes de 2 dígitos, y así sucesivamente.
SSLInfo	No	Permite registrar mensajes a través de SSL/TLS. Se usa con el subelemento <Enabled>true</Enabled>. Si no incluye este elemento o lo deja vacío, el valor predeterminado es false (sin TLS/SSL). <SSLInfo> <Enabled>true</Enabled> </SSLInfo> Puedes configurar la etiqueta <SSLInfo> de la misma forma que en un TargetEndpoint, lo que incluye habilitar TLS/SSL bidireccional, tal como se describe en la referencia de configuración de proxy de API. Solo se admite el protocolo TCP.

---

<logLevel>

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

Define un nivel específico de información que se incluirá en el registro de mensajes.

Si usas el elemento FormatMessage (con el valor true), el ajuste <logLevel> afecta a la puntuación de prioridad calculada (el número entre corchetes angulares) de la información generada por Apigee que se añade al principio del mensaje.

Notas de uso

Cuando adjuntes una política MessageLogging a un flujo de proxy de API, plantéate colocarla en la respuesta ProxyEndpoint, en un flujo especial llamado PostClientFlow. PostClientFlow se ejecuta después de que se envíe la respuesta al cliente que ha hecho la solicitud, lo que asegura que todas las métricas estén disponibles para registrarse. Para obtener información sobre cómo usar PostClientFlow, consulta la referencia de configuración de proxies de APIs.

Nota: Es importante tener en cuenta que la variable de flujo response no está disponible en PostClientFlow una vez que el procesamiento entra en el estado de error. En su lugar, puede usar la variable message para definir valores en la política MessageLogging en PostClientFlow, lo que garantiza que se definan independientemente de si el estado de error era el contexto anterior. Para obtener más información y ejemplos, consulta la referencia de variables de flujo.

PostClientFlow es especial por dos motivos:

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

Como se ejecuta independientemente de si el proxy se ha completado correctamente o no, puede colocar políticas MessageLogging en PostClientFlow y tener la garantía de que siempre se ejecutan.

En la siguiente imagen de depuración se muestra una política MessageLogging que se ejecuta como parte de PostClientFlow, después de que se ejecute DefaultFaultRule:

En este ejemplo, la política Verify API Key ha provocado el error debido a una clave no válida.

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

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

Apigee registra los mensajes como texto simple y puedes configurar el registro para incluir variables, como la fecha y la hora en las 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.

Apigee registra los mensajes de forma asíncrona: la respuesta se devuelve mientras se siguen escribiendo los registros. Por lo tanto, no se introduce ninguna latencia en tu API al bloquear las llamadas. Puede que haya ocasiones en las que no se escriba un registro sin que se devuelva un error, pero estos eventos son poco frecuentes.

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, a continuación, los escribe en el destino que configures. Cada destino tiene su propio búfer.

Nota: Las llamadas proxy se realizan correctamente cuando falla el registro

Como el registro de mensajes se escribe primero en el búfer, el proxy de API seguirá ejecutándose correctamente aunque el registro de mensajes falle (por ejemplo, si se produce un error de conexión con el destino).

Si la tasa de escritura en el búfer supera la tasa de lectura, el búfer se desbordará y el registro fallará. Si esto ocurre, es posible que veas uno de los siguientes mensajes en el archivo de registro:

• Usar <CloudLogging>:

  steps.messagelogging.TooManyPendingLoggingRequest

• Usar <Syslog>:

  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 de mensaje de respuesta de Apigee no están disponibles en el flujo de errores. Estas variables tampoco están disponibles en PostClientFlow si el flujo anterior era Error Flow. Si quieres registrar información de respuesta de PostClientFlow, usa message. Puedes usar este objeto para acceder a los encabezados y a otra información de la respuesta, tanto si se ha producido un error como si no. Consulta más información y un ejemplo en la referencia de variables de flujo.

Valores predeterminados de las variables de la plantilla de mensaje

Se pueden especificar valores predeterminados para cada variable de la plantilla de mensaje por separado. Por ejemplo, si no se puede resolver la variable request.header.id, su valor se sustituye 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 configurando el atributo defaultVariableValue en el elemento Message:

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

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

Configurar servicios de gestión de registros de terceros

La política MessageLogging te permite enviar mensajes syslog a servicios de gestión de registros de terceros, como Splunk, Sumo Logic y Loggly. Si quieres enviar syslog a uno de esos servicios, consulta la documentación del servicio para configurar el host, el puerto y el protocolo del servicio. A continuación, define el elemento Syslog en esta política.

Consulta la siguiente documentación sobre la configuración de la gestión de registros de terceros:

• Splunk (selecciona la versión del producto)
  Consulta también esta publicación de la comunidad de Apigee: Registrar mensajes en Splunk
• Sumo Logic
  • También puedes consultar esta publicación de la comunidad de Apigee: Configurar el registro con Sumo Logic
  • Para ver un ejemplo completo en el que se usa Sumo Logic como servicio de registro, consulta esta publicación de la comunidad de Apigee. La solución usa una sola política de JavaScript para enviar solicitudes HTTP POST al recopilador de fuentes HTTP de Sumo Logic: Registro en Sumo Logic mediante JavaScript y HTTP
• Loggly
  Cuando se usa Loggly, <FormatMessage>true</FormatMessage> es obligatorio en la política como elemento secundario del elemento <Syslog>.
  Consulta también 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code	HTTP status	Cause
steps.messagelogging.StepDefinitionExecutionFailed	500	See fault string.
steps.messagelogging.InvalidGoogleCloudLogName	500	This error is thrown when the LogName does not evaluate to the valid format of projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage	500	This error is thrown when the contentType attributes value has been chosen as application/json but the actual message value is not a valid JSON string,
steps.messagelogging.TooManyPendingLoggingRequest	500	This error is thrown when there are more than 2500 pending requests that are yet to be written to Cloud Logging. The 2500 limit is for each Apigee runtime pod. For example, if the traffic is distributed over two instances of Apigee runtime pods, the effective limit is 5000 requests.

-

Deployment errors

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

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidProtocol	The deployment of the MessageLogging policy can fail with this error if the protocol specified within the <Protocol> element is not valid. The valid protocols are TCP and UDP. For sending syslog messages over TLS/SSL, only TCP is supported.
InvalidPort	The deployment of the MessageLogging policy can fail with this error if the port number is not specified within the <Port> element or if it is not valid. The port number must be an integer greater than zero.

Fault variables

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

Note: Proxy calls succeed when logging fails

There's a difference between policy errors and message logging errors. The flow variables here are populated only when the policy itself fails, not when message logging fails. Because message logging is first written to buffer, the API proxy will continue successful execution even if message logging ultimately fails (for example, if there's a connection failure to the external syslog provider). Be sure to check your logs on a regular basis to make sure logging is happening as expected.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	messagelogging.ML-LogMessages.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "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 rellenan cuando se produce un error en la política.

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

Nota: Las llamadas de proxy se realizan correctamente cuando falla el registro

Hay una diferencia entre los errores de políticas y los errores de registro de mensajes. Las variables de flujo de este apartado solo se rellenan cuando falla la propia política, no cuando falla el registro de mensajes. Como el registro de mensajes se escribe primero en el búfer, el proxy de API seguirá ejecutándose correctamente aunque el registro de mensajes falle (por ejemplo, si se produce un error de conexión con el proveedor de syslog externo). Asegúrate de revisar los registros periódicamente para comprobar que se están registrando los datos como esperabas.

---

Temas relacionados

• Variables expuestas por Apigee: Referencia de variables de flujo