Cómo usar la herramienta Trace

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

¿Qué es la herramienta Trace?

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.

Mire este video para obtener una introducción a la herramienta Trace.

Cómo usar Trace

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

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

    Conexión de integración

    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, sigue estos pasos:

    1. Accede a http://ms-ip:9000, en el que 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 de la que deseas hacer un seguimiento esté implementada.
  4. Haga clic en Seguimiento para ir a la vista de herramientas de seguimiento.
  5. Usa el menú desplegable Deployment to Trace para seleccionar el entorno de implementación y la revisión del proxy de los que quieres hacer un seguimiento.
  6. Haz clic en Start Trace Session. 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 Trace, se capturan los mensajes y los datos contextuales del tráfico en vivo.

  7. Si no tienes tráfico en vivo que fluya a través de tu proxy, simplemente envía una solicitud a la API. Puedes usar cualquier herramienta que desees para enviar la solicitud, como curl, Postman o cualquier herramienta conocida. También puedes enviar la solicitud directamente desde la herramienta Trace. Solo debes 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 manejan el tráfico, se admiten 20 transacciones de solicitud/respuesta. Una sesión de seguimiento 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 Stop Trace Session.
  9. En el menú de la izquierda, se muestra una lista de las transacciones de solicitud/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 se generan por 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 se generan por Edge. Por ejemplo, la siguiente es una expresión que Edge usa para verificar si se produjo un error en 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 con marcas de verificación claramente. Si se produce un error, se mostrará un signo de exclamación rojo en el ícono.

Sugerencia: Presta atención a la información sobre la herramienta o al cronograma para verificar si alguna política tarda más de lo esperado.
Aparece cuando el destino del backend es una aplicación de Node.js. Consulta 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.
Se produjo un 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 bien usa los botones Siguiente y Atrás para pasar de un paso a otro.

Detalle de la fase Descripción
Extremo de proxy Indica qué flujo ProxyEndpoint se seleccionó para realizar la ejecución. Un proxy de API puede tener varios extremos de proxy con nombre.
Variables

Enumera las variables de flujo que se leyeron y se les asignó un valor mediante una política. Consulta también Administra el estado del proxy con variables de flujo.

Nota:

  • Un signo igual (=) indica el valor que se le asignó a la variable.
  • Un signo de igual tachado (≠) indica que a la variable no se le pudo asignar un valor porque es de solo lectura o se produjo un error durante la ejecución de la política.
  • Un campo vacío indica que se leyó el valor de la variable.
Encabezados de la solicitud Muestra una lista de los encabezados de la solicitud HTTP.
Contenido de la solicitud Muestra el cuerpo de la solicitud HTTP.
Propiedades Las propiedades representan el estado interno del proxy de API. Estas no se muestran de forma predeterminada.
Extremo de destino Indica qué TargetEndpoint se seleccionó para su ejecución.
Encabezados de respuesta Enumera los encabezados de respuesta HTTP.
Contenido de la respuesta Muestra el cuerpo de la respuesta HTTP.
PostClientFlow Muestra información sobre PostClientFlow, que se ejecuta después de que se muestra la solicitud en la app cliente solicitante. Solo se pueden adjuntar políticas MessageLogging a PostClientFlow. Por el momento, PostPostFlow se usa en especial para medir el intervalo de tiempo entre las marcas de tiempo de inicio y finalización del mensaje de respuesta.

Define mejor la captura de mensajes con filtros

Puedes filtrar las solicitudes que aparecen en la herramienta de seguimiento si especificas los valores del encabezado o de los parámetros de consulta. Los filtros te permiten orientar tus anuncios a llamadas específicas que podrían causar problemas. Por ejemplo, es posible que debas enfocarte en las solicitudes que tienen contenido específico o las que provienen de socios o apps específicos. Puedes aplicar los siguientes filtros:

  • Encabezados HTTP: Limita el seguimiento a solo las llamadas que contienen un encabezado específico. Esta es una buena manera de ayudarte a solucionar problemas. Puedes enviar un encabezado al desarrollador de tu app y pedirle que lo incluya en la llamada que causa el problema. 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 el valor específico de un parámetro.

Información que debe saber sobre la función 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 del filtro son un operador Y. Todos los pares de consulta o de encabezado/valor especificados deben estar presentes en la solicitud para que haya una coincidencia correcta.
  • La coincidencia de patrones no es compatible con la herramienta Filtros.
  • Los parámetros y valores de los filtros distinguen mayúsculas de minúsculas.

Cómo crear un filtro de seguimiento

  1. Si hay una sesión de seguimiento en ejecución, haz clic en Stop Trace Session para detenerla.
  2. Haz clic en Filtros (Filters) en la esquina superior izquierda de la herramienta de seguimiento para expandir el campo Filtros.

    En la herramienta Trace, la etiqueta de la barra lateral Filtros está dentro de un círculo.
  3. En el campo Filtros, especifica el parámetro de consulta o los valores del encabezado que deseas filtrar. En este ejemplo, se especifican dos parámetros de consulta para filtrar. Ambos parámetros deben estar presentes en la solicitud para una coincidencia correcta.

    En la herramienta de seguimiento, en Filtros, debajo de Parámetro de consulta, se configuran dos nombres y valores de ejemplo.
  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 correcta.

En Transacciones, aparecerán cuatro resultados que coincidan con dos parámetros de consulta predeterminados.

En el ejemplo anterior, esta llamada a la API aparecerá en Trace:

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

Sin embargo, no ocurrirá lo siguiente:

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 identificar dónde está ocurriendo el cuello de botella. El seguimiento proporciona el tiempo (en milisegundos) que tarda cada paso de procesamiento en completarse. 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 que establecen 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 las opciones de vista

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

Opción Descripción
Mostrar políticas inhabilitadas Mostrar las políticas inhabilitadas. Se puede inhabilitar una política con la API pública. Consulta la referencia de configuración del proxy de API.
Mostrar las fases omitidas Mostrar las fases que se omitieron. Una fase omitida se produce cuando la política no se ejecuta porque la condición del paso se evaluó como falsa. Consulta las variables y condiciones de flujo para obtener más información.
Mostrar todos los FlowInfos Representa transiciones dentro de un segmento de flujo.
Compara automáticamente la fase seleccionada Compara la fase seleccionada con la anterior. Desactiva esta opción para ver solo la fase seleccionada.
Mostrar variables Muestra u oculta variables que se leyeron o a las que se les asignó un valor.
Mostrar propiedades Las propiedades representan el estado interno del proxy de API. (ocultas de manera predeterminada).

Cómo descargar resultados de seguimiento

Puedes descargar un archivo en formato XML de resultados de seguimiento sin procesar para visualizar y buscar sin conexión en un editor de texto. En el archivo, se muestran 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.

Se muestran solicitudes como curl

Después de realizar el seguimiento de una llamada a la API realizada en un servidor de destino, puedes ver la solicitud como un comando curl. Esto es particularmente útil para realizar depuraciones por las siguientes razones:

  • El proxy de API puede modificar la solicitud, por lo que resulta útil ver cómo la solicitud del proxy al servidor de destino difiere de la solicitud original. El comando curl representa la solicitud modificada.
  • Para cargas útiles de mensajes más grandes, curl te permite ver los encabezados HTTP y el contenido de los mensajes en un solo lugar. (Actualmente, hay un límite de aproximadamente 1,000 caracteres. Si quieres ver una sugerencia para superar este límite, consulta esta publicación de Comunidad).

Por razones 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" en el panel Detalles de la fase.

Las anotaciones de imagen señalan el botón Mostrar rizos y uno de los círculos del diagrama del mapa de transacciones.

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.