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 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.

Mira 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 de Edge y lees los resultados.

  1. Accede a la página de 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, sigue estos pasos:

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

    IU de Edge nueva (nube privada)

    Para acceder a la página de proxies de API con la IU de New Edge, sigue estos pasos:

    1. Accede a la IU de Edge nueva en http://host:3001/edge, donde host es la dirección IP o el nombre de DNS del host que ejecuta la IU de Edge nueva.
    2. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.
  2. Selecciona un proxy de API en la página Proxies de API.
  3. Asegúrate de que la API de la que quieres hacer un seguimiento esté implementada.
  4. Haz clic en Seguimiento para ir a la vista de la herramienta Trace.
  5. Usa el menú desplegable Implementación para el seguimiento para seleccionar el entorno de implementación y la revisión del proxy de los que deseas realizar un seguimiento.
  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 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 ingresa la URL y haz 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 Message Processor a través del proxy de API seleccionado. En Edge para la nube, con 2 Message Processors que controlan 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 Detener sesión de seguimiento.
  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 correctamente se indican con marcas de verificación. En caso de que se produzca 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 a la línea de tiempo para ver si alguna política tarda más de lo esperado.

Aparece cuando el destino de 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.

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 Variables de flujo y condiciones 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.

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 una política leyó y a las que asignó un valor. 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 Trace especificando los valores de los parámetros de encabezado o de consulta. Los filtros te permiten segmentar llamadas específicas que podrían 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 seguimiento solo a 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 apps y pedirle que lo incluya en la llamada que causa 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 grabará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 seguimiento después de especificar los parámetros de filtro en los campos de filtro.
  • Los parámetros de filtro se unen con 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 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 se está ejecutando una sesión de seguimiento, haz clic en Stop Trace Session para detenerla.
  2. Haz clic en Filters en la esquina superior izquierda de la herramienta Trace para expandir el campo Filters.

    En la herramienta Trace, la etiqueta de la barra lateral Filters está encerrada en un círculo.
  3. En el campo Filtros, especifica el parámetro de consulta o los valores de encabezado 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.

    En la herramienta Trace, en Filtros, en Parámetro de consulta, se establecen dos nombres y valores de ejemplo.
  4. Inicia la sesión de seguimiento.
  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, aparecen cuatro resultados que coinciden 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

Pero esta no:

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

Depura 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 se produce el cuello de botella. Trace indica 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 políticas, etcétera.
  • Verifica la ruta base para asegurarte de que una política enrute el mensaje al servidor correcto.

Selecciona opciones de vista

Elige las opciones de visualización para la sesión de seguimiento.

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 Variables de flujo y condiciones 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).

Descargando los resultados del seguimiento

Puedes descargar un archivo en formato XML con los resultados de seguimiento sin procesar para verlos y buscarlos 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, las variables y las políticas.

Para descargar, haz clic en Descargar sesión de seguimiento.

Cómo mostrar solicitudes como curl

Después de realizar un seguimiento de 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 un par de motivos:

  • El proxy de API puede modificar la solicitud, por lo que es útil ver cómo difiere la solicitud del proxy al servidor de destino 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 alrededor de 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 de 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 la imagen indican el botón Show Curl 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.