Cómo usar la herramienta Trace

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
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.

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, luego haces una llamada a la API a la plataforma Edge y lees los resultados.

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

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

    Versión clásica de 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. Haz clic en Trace para ir a la vista de la herramienta de seguimiento.
  5. Usa el menú desplegable Deployment to Trace para seleccionar el entorno de implementación y la revisión del proxy de la que deseas hacer 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, los mensajes y los datos contextuales se capturan del tráfico en vivo.

  7. Si no tienes tráfico en vivo que fluya a través de tu proxy, solo envía una solicitud a la API. Puedes usar la herramienta que desees para enviar la solicitud, como curl, Postman o cualquier herramienta conocida. También puedes enviar la solicitud directamente desde la herramienta de seguimiento. 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 o 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 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 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 mediante 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 mediante 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 con marcas de verificación. En caso de error, se muestra 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 Next y Back para desplazarte 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 qué solicitudes aparecen en la Herramienta de seguimiento si especificas los valores de los parámetros de consulta o encabezado. Los filtros te permiten orientarte a llamadas específicas que podrían estar causando problemas. Por ejemplo, es posible que debas concentrarte en las solicitudes que tienen contenido específico o las que provienen de apps o socios específicos. Puedes aplicar los siguientes filtros:

  • Encabezados HTTP: Limita el seguimiento a solo las llamadas que contengan 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 problemas. Luego, Apigee Edge solo grabará 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.

Información que debes 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 de filtro se combinan mediante el operador AND. Todos los pares de consulta o nombre/valor de encabezado 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 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 en la esquina superior izquierda de la herramienta de seguimiento para expandir el campo Filtros.

    En la herramienta de seguimiento, 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 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 obtener una coincidencia correcta.

    En la Herramienta de seguimiento, en Filtros, en 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, aparecen cuatro resultados que coinciden con dos parámetros de consulta predeterminados.

En el ejemplo anterior, esta llamada a la API se mostrará 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 se produce el cuello de botella. Trace proporciona el tiempo (en milisegundos) que tarda en completarse cada paso del 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 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).

Descarga los resultados de seguimiento

Puedes descargar un archivo en formato XML con los resultados de seguimiento sin procesar para verlo y buscar 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 ello, haz clic en Descargar sesión de seguimiento.

Muestra solicitudes como curl

Después de hacer el 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 las siguientes dos razones:

  • El proxy de API puede modificar la solicitud, por lo que resulta ú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.
  • 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 obtener una sugerencia para superar este límite, consulta esta publicación de la comunidad.

Por 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 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 imágenes señalan el botón Mostrar rizo y uno de los círculos en el 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.