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
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>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat> </Syslog> <logLevel>ALERT</logLevel> </MessageLogging>
Un uso común del tipo de política MessageLogging es acceder a una cuenta syslog. Cuando se configura para syslog, un proxy de API reenvía los mensajes de registro de Apigee Edge a un Servidor Syslog remoto. Ya debes tener un Servidor Syslog disponible. Si no es así, los servicios de administración de registros públicos, como Splunk, Sumo Logic y Loggly, están disponibles. Consulta Configura servicios de administración de registros de terceros.
Por ejemplo, imagina que necesitas registrar información sobre cada mensaje de solicitud que tu API recibe de las apps 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.
Si tienes una implementación de Edge para la nube privada, también puedes escribir mensajes de registro en un archivo.
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> <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat> </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.
Rotación del archivo: tamaño
<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>
Rotación de archivo en función del tamaño.
Rotación del archivo: tiempo
<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>
Rotación de los archivos en función del tiempo.
Rotación del archivo: tiempo y tamaño
<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>
Rotación de los archivos en función del tiempo y el tamaño.
Transmisión habilitada
<MessageLogging name="LogPolicy"> <File> .... .... </File> <BufferMessage>true</BufferMessage> </MessageLogging>
Registro de mensajes con transmisiones habilitadas
Referencia del elemento
Usa los siguientes elementos para configurar el tipo de política de MessageLogging.
Nombre del campo | Descripción del campo | |
---|---|---|
Es el destino del archivo local. (El registro de archivos solo se admite en las implementaciones de Edge para la nube privada). Para obtener información sobre dónde se almacenan los archivos, consulta Ubicación de los archivos de registro en Edge para la nube privada. |
Message |
Compila el mensaje que se enviará al archivo de registro y combina texto con variables para capturar la información que deseas. Consulta las muestras. |
FileName |
Es el nombre base del archivo de registro.
No especifiques una ruta de acceso al archivo. Por ejemplo, este elemento FileName especifica una ruta de acceso de archivo y no es válido:
<FileName>/opt/apigee/var/log/messages/mylog.log</FileName> Este código solo especifica un nombre de archivo y es válido: <FileName>mylog.log</FileName> Para obtener información sobre dónde se almacena el archivo, consulta Ubicación del archivo de registro en Edge para la nube privada. |
|
FileRotationOptions |
||
rotateFileOnStartup |
Atributo. Valores válidos: Si se establece como verdadero, el archivo de registro se rota cada vez que se reinicia el motor de mensajería. |
|
FileRotationType |
Especifica la política de rotación (size o time ) de un archivo de registro. |
|
MaxFileSizeInMB |
(Cuando se selecciona size como tipo de rotación)
Especifica el tamaño de un archivo de registro que activa el servidor para que mueva los mensajes de registro a un archivo
separado. Después de que el archivo de registro alcanza el tamaño especificado, el servidor cambia el nombre del archivo de registro actual. |
|
RotationFrequency |
(Cuando se selecciona time como tipo de rotación)
Especifica el tiempo en minutos que activa el servidor para mover los mensajes de registro a un archivo
independiente. Después de que transcurra el intervalo especificado, se cambiará el nombre del archivo de registro actual. |
|
MaxFilesToRetain |
Especifica la cantidad máxima de archivos que se retendrán en el contexto de la configuración de rotación. El valor predeterminado es 8. Si especificas cero (0), los archivos de registro se retienen de forma indefinida, pero están sujetos a la configuración de rotación de archivos, aunque no se borra ninguno de los archivos ni se les cambia el nombre. Por lo tanto, para evitar errores de disco lleno en el futuro, configúralo en un valor superior a cero o implementa un sistema automatizado y periódico de purga o archivado de archivos de registro retenidos más antiguos. |
|
BufferMessage |
Si la transmisión HTTP está habilitada para tu proxy, los mensajes de solicitud o respuesta no se almacenan en búfer. Si quieres registrar contenido que requiere que se analice el mensaje de flujo, configura BufferMessage como verdadero. Consulta la pestaña de ejemplo "Habilitada para transmisiones" para ver un ejemplo. Valor predeterminado: false |
|
Un destino de syslog. Para enviar syslog a Splunk, Sumo Logic o Loggly, consulta Configura servicios de administración de registros de terceros. |
Message |
Compila el mensaje que se enviará a syslog y combina texto con variables para capturar la información que deseas. Consulta las muestras. Nota: Las variables de respuesta no estarán disponibles en PostClientFlow después de un flujo de error. Usa variables de mensaje para registrar la información de la respuesta ante situaciones de errores y éxito. Consulta también las Notas de uso. |
Host |
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 |
Puerto donde se ejecuta syslog. Si no incluyes este elemento, el valor predeterminado será 514. | |
Protocol |
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 |
Opcional, pero 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:
La información generada por Apigee incluye lo siguiente:
Si se configura como falso (predeterminado), al mensaje no se le agregan los caracteres fijos. |
|
PayloadOnly |
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á Consulta FormatMessage. |
|
DateFormat |
Opcional. 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 |
|
SSLInfo |
Te permite registrar mensajes a través de SSL/TLS. Se usa con el subelemento 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 |
Opcional. Valores válidos: Establezca un nivel específico de información para incluir en el registro de mensajes. Si usas el elemento |
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:
- Solo se ejecuta como parte del flujo de respuesta.
- 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:
- Abre el archivo message-processor.properties en un editor. Si el archivo no existe, créalo:
> vi /opt/apigee/customer/application/message-processor.properties - Establece las propiedades como desees:
conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ - Guarda los cambios.
- Asegúrate de que el usuario "apigee" sea el propietario del archivo de propiedades:
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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, comoconf/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 sobrebin_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:
- Abre el archivo message-processor.properties en un editor. Si el archivo no existe, créalo:
> vi /opt/apigee/customer/application/message-processor.properties - Establece las propiedades como desees:
conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages - Guarda los cambios.
- Asegúrate de que el usuario "apigee" sea el propietario del archivo de propiedades:
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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
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.
Código de falla | Estado de HTTP | Causa |
---|---|---|
steps.messagelogging.StepDefinitionExecutionFailed |
500 | Consulta la cadena de errores. |
Errores en la implementación
Estos errores pueden generarse cuando implementas un proxy que contiene esta política.
Nombre del error | Causa | Corregir |
---|---|---|
InvalidProtocol |
La implementación de la política MessageLogging puede fallar 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. |
build |
InvalidPort |
La implementación de la política MessageLogging puede fallar con este error si el número de puerto
no se especifica en el elemento <Port> o si no es válido. El número de puerto debe ser un número entero mayor que cero. |
build |
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.
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
{ "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