Cómo usar la herramienta Trace

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

¿Qué es la herramienta de seguimiento?

Trace es una herramienta para solucionar problemas y supervisar proxies de API que se ejecutan en Apigee Edge. Trace te permite sondear los detalles de cada paso a través de un flujo de proxy de API.

Cómo usar Trace

Trace es fácil de usar. Comienzas una sesión de registro, luego realizas una llamada a la API de la plataforma de Edge y lees los resultados.

1. Accede a la página Proxies de API, como se describe a continuación.
   

   Edge

   Para acceder a la página de proxies de API con la IU de Edge, haz lo siguiente:

   1. Accede a apigee.com/edge.
   2. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.

   Classic Edge (nube privada)

   Para acceder a la página de proxies de API con la IU clásica de Edge, haz lo siguiente:

   1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
   2. Selecciona API > Proxies de API en la barra de navegación superior.
2. Selecciona un proxy de API en la página Proxies de API.
3. Asegúrate de que la API que deseas rastrear esté implementada.
4. Haz clic en Trace para ir a la vista de la herramienta Trace.
5. Usa el menú desplegable Deployment to Trace para seleccionar el entorno de implementación y la revisión del proxy que deseas rastrear.
6. Haz clic en Iniciar sesión de seguimiento. Cuando la sesión de Trace está activa, el proxy de API registra los detalles de cada paso en la canalización de procesamiento. Mientras se ejecuta la sesión de registro, se capturan mensajes y datos contextuales del tráfico en vivo.
   

   

7. Si no tienes tráfico activo que fluya a través de tu proxy, simplemente envía una solicitud a la API. Puedes usar la herramienta que desees para enviar la solicitud, como curl, Postman o cualquier otra herramienta que conozcas. También puedes enviar la solicitud directamente desde la herramienta Trace. Solo tienes que ingresar la URL y hacer clic en Enviar. Nota: Solo puedes enviar una solicitud GET desde la herramienta Trace, pero no una solicitud POST.
   
   Nota: Una sesión de Trace puede admitir 10 transacciones de solicitud/respuesta por procesador de mensajes a través del proxy de API seleccionado. En la nube perimetral, con 2 procesadores de mensajes que controlan el tráfico, se admiten 20 transacciones de solicitud/respuesta. Una sesión de registro se detiene automáticamente después de 10 minutos si no la detienes de forma manual.
   
8. Cuando hayas capturado una cantidad suficiente de solicitudes, haz clic en Detener sesión de registro.
9. En el menú de la izquierda, se muestra una lista de las transacciones de solicitud y respuesta capturadas. Haz clic en cualquiera de las transacciones para ver los resultados detallados.

Cómo leer un seguimiento

La herramienta de seguimiento tiene dos partes principales: el mapa de transacciones y los detalles de la fase:

• El mapa de transacciones usa íconos para marcar cada paso destacado que se produce durante una transacción de proxy de API, incluidas la ejecución de políticas, los pasos condicionales y las transiciones. Coloca el cursor sobre cualquier ícono para ver información de resumen. Los pasos del flujo de solicitud aparecen en la parte superior del mapa de transacciones y los pasos del flujo de respuesta en la parte inferior.
• La sección de detalles de la fase de la herramienta muestra información sobre el procesamiento interno del proxy, incluidas las variables que se configuraron o leyeron, los encabezados de respuesta y solicitud, y mucho más. Haz clic en cualquier ícono a fin de ver los detalles de la fase de ese paso.

Aquí se incluye un mapa de muestra de seguimiento con los segmentos principales de procesamiento del proxy etiquetados:

Mapa de transacciones de la herramienta de seguimiento

Leyenda del mapa de transacciones

En la siguiente tabla, se describe el intent de los íconos que verás en el mapa de transacciones. Estos íconos marcan cada uno de los pasos destacados del procesamiento en el flujo del proxy.

Íconos del mapa de transacciones

	La app cliente que envía una solicitud al ProxyEndpoint del proxy de API.
	Los círculos marcan extremos de transición en el flujo del proxy. Están allí cuando llega una solicitud del cliente, cuando la solicitud va al destino, cuando la respuesta regresa del destino y cuando la respuesta regresa al cliente.
	Las barras largas indican el comienzo de un segmento del flujo en el proxy de API. Los segmentos de flujo son: solicitud de ProxyEndpoint, solicitud de TargetEndpoint, respuesta de TargetEndpoint y respuesta de ProxyEndpoint. Un segmento incluye PreFlow, flujos condicionales y PostFlow. Para obtener más información, consulta Configura flujos.
	Indica que las acciones de estadísticas ocurrieron en segundo plano.
	Flujo condicional que se evalúa como verdadero. Para obtener una introducción a los flujos condicionales, consulta Configura flujos. Ten en cuenta que algunas condiciones las genera Edge. Por ejemplo, la siguiente es una expresión que Edge usa para verificar si se produjo un error en el ProxyEndpoint: ((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))
	Un flujo condicional que se evalúa como falso. Para obtener una introducción a los flujos condicionales, consulta Configura flujos. Ten en cuenta que algunas condiciones las genera Edge. Por ejemplo, la siguiente es una expresión que Edge usa para verificar si se produjo un error en el TargetEndpoint: (((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))
	Políticas Cada tipo de política tiene un ícono único. Este es para la política AssignMessage. Estos íconos te permiten ver dónde se ejecutan las políticas en el orden adecuado y si son exitosas o no. Puedes hacer clic en el ícono de una política para ver los resultados de su ejecución y si se espera o no. Por ejemplo, puedes ver si el mensaje se transformó de forma correcta o si se está almacenando en caché. Las políticas que se ejecutan de forma correcta se indican claramente mediante marcas de verificación. Si se genera un error, aparecerá un signo de exclamación rojo en el ícono. Sugerencia: Presta atención a la información sobre la herramienta o la línea de tiempo para ver si alguna política tarda más de lo esperado.
	Aparece cuando el destino del backend es una aplicación Node.js. Consulta la Descripción general de Node.js en Apigee Edge.
	El destino de backend al que llama el proxy de API.
	La línea de tiempo indica cuánto tiempo (en milisegundos) tardó en completarse el tiempo de procesamiento. La comparación de los segmentos de tiempo transcurrido te ayuda a aislar las políticas que tardan más en ejecutarse que ralentizan las llamadas a la API.
	Epsilon indica un intervalo de tiempo menor que un milisegundo.
	Inhabilitada Aparece en el ícono de una política cuando está inhabilitada. Se puede inhabilitar una política con la API pública. Consulta la referencia de configuración de proxy de API.
	Error. Aparece en un ícono de política cuando la condición del Paso de política se evalúa como falsa (consulta Condiciones y variables de flujo) o en el ícono de la política RaiseFault cuando una política de RaiseFault se ejecuta.
	Omitida. Aparece en un ícono de política cuando la política no se ejecutó porque la condición del paso se evaluó como falsa. Consulta las variables y condiciones de flujo para obtener más información.

Información sobre los detalles de la fase

La parte de Detalles de la fase de la herramienta te indica mucho sobre el estado de tu proxy en cada paso de procesamiento. Estos son algunos de los detalles que se proporcionan en los Detalles de la fase. Haz clic en cualquier ícono de la herramienta de seguimiento para ver los detalles del paso seleccionado o usa los botones Siguiente/Atrás para pasar de un paso a otro.

Cómo definir mejor la captura de mensajes con filtros

Puedes especificar valores de encabezado o parámetros de consulta para filtrar qué solicitudes aparecen en la herramienta de Trace. Los filtros te permiten segmentar llamadas específicas que pueden estar causando problemas. Por ejemplo, es posible que debas enfocarte en las solicitudes que tienen contenido específico o que provienen de socios o apps específicos. Puedes aplicar los siguientes filtros:

• Encabezados HTTP: Limita el registro de seguimiento solo a las llamadas que contienen un encabezado específico. Esta es una buena forma de ayudarte a solucionar problemas. Puedes enviar un encabezado al desarrollador de la app y pedirle que lo incluya en la llamada que está causando problemas. Luego, Apigee Edge solo registrará las llamadas con ese encabezado específico para que puedas examinar los resultados.
• Parámetros de consulta: Solo se registrarán las llamadas con un valor específico de un parámetro.

Aspectos que debes tener en cuenta sobre la función de filtro

• Debes reiniciar la sesión de Trace después de especificar los parámetros de filtro en los campos de filtro.
• Los parámetros de filtro se combinan con el operador AND. Todos los pares de nombre/valor de encabezado o consulta especificados deben estar presentes en la solicitud para que la coincidencia sea exitosa.
• La herramienta Filters no admite la búsqueda de coincidencias de patrones.
• Los parámetros y valores de los filtros distinguen mayúsculas de minúsculas.

Cómo crear un filtro de registro de seguimiento

1. Si se está ejecutando una sesión de registro, haz clic en Detener sesión de registro para detenerla.
2. Haz clic en Filters en la esquina superior izquierda de la herramienta Trace para expandir el campo Filters.
   
   
   
3. En el campo Filters, especifica los valores del encabezado o del parámetro de consulta según los que deseas filtrar. En este ejemplo, especificamos dos parámetros de consulta para filtrar. Ambos parámetros deben estar presentes en la solicitud para que la coincidencia sea exitosa.
   
   
   
4. Inicia la sesión de registro.
5. Llama a tus APIs. Solo las solicitudes que incluyen todos los encabezados o parámetros de consulta especificados producen una coincidencia exitosa.

En el ejemplo anterior, esta llamada a la API aparecerá en el registro de seguimiento de la siguiente manera:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

Pero esto no funcionará:

http://docs-test.apigee.net/cats?name=Penny

Depuración con Trace

Trace te permite ver muchos detalles internos sobre un proxy de API. Por ejemplo:

• Puedes ver rápidamente qué políticas se ejecutan de forma correcta o fallan.
• Supongamos que notaste en uno de los paneles de Analytics que una de tus API experimenta una disminución inusual en el rendimiento. Ahora puedes usar Trace para ayudar a identificar dónde se produce el cuello de botella. El registro proporciona el tiempo, en milisegundos, que tarda en completarse cada paso de procesamiento. Si notas que un paso tarda demasiado, puedes tomar medidas correctivas.
• Si observas los detalles de la fase, puedes verificar los encabezados que se envían al backend, ver las variables establecidas por las políticas, etcétera.
• Verifica la ruta base para asegurarte de que una política enrute el mensaje al servidor correcto.

Cómo seleccionar opciones de vista

Elige las opciones de vista para la sesión de registro.

Cómo descargar los resultados del registro

Puedes descargar un archivo XML de los resultados de seguimiento sin procesar para verlo y buscarlo sin conexión en un editor de texto. El archivo muestra los detalles completos de la sesión de escucha, incluido el contenido de todos los encabezados, variables y políticas.

Para descargarla, haz clic en Download Trace Session.

Cómo mostrar solicitudes como curl

Después de rastrear una llamada a la API realizada a un servidor de destino, puedes ver la solicitud como un comando curl. Esto es particularmente útil para la depuración por los siguientes motivos:

• El proxy de API puede modificar la solicitud, por lo que es útil ver en qué se diferencia la solicitud del proxy al servidor de destino de la solicitud original. El comando curl representa la solicitud modificada.
• En el caso de cargas útiles de mensajes más grandes, curl te permite ver los encabezados HTTP y el contenido del mensaje en un solo lugar. (Actualmente, hay un límite de aproximadamente 1,000 caracteres. Para obtener una sugerencia sobre cómo superar este límite, consulta esta publicación de la comunidad.

Por motivos de seguridad, la función curl enmascara el encabezado de autorización HTTP.

Para ver las solicitudes como curl después de que se realiza una llamada a la API en Trace, selecciona la etapa "Solicitud enviada al servidor de destino" en el diagrama del mapa de transacciones y, luego, haz clic en el botón Mostrar curl en la columna "Solicitud enviada al servidor de destino" del panel Detalles de la fase.

Asistencia de Apigee para el uso de Trace

De forma predeterminada, Apigee Edge permite que la asistencia de Apigee use la herramienta Trace en los proxies de tu API para proporcionar asistencia. Puedes inhabilitar esta opción en cualquier momento. Sin embargo, inhabilitar esta opción puede limitar la capacidad de la asistencia de Apigee para proporcionarte asistencia.

Para inhabilitar la asistencia de Apigee mediante la herramienta Trace:

1. Acceda a https://apigee.com/edge.
2. En la barra de navegación izquierda, seleccione Administrador > Privacidad y seguridad.
3. Haz clic en el botón de activación Habilita la asistencia de Apigee para Trace a fin de inhabilitar el uso de la herramienta de seguimiento por parte de la asistencia de Apigee.