Haz un seguimiento de tu API

OpenAPI  |  gRPC

Después de implementar el proxy de servicio extensible (ESP) o el proxy de servicio extensible V2 (ESPv2) y el código de backend de la API, el proxy intercepta todas las solicitudes y realiza las verificaciones necesarias antes de reenviar la solicitud al backend de la API. Cuando el backend responde, el proxy informa y recopila la telemetría. Una parte de los datos de telemetría que el proxy captura es el seguimiento mediante Cloud Trace.

En esta página se explica cómo:

• Visualiza seguimientos en la consola de Google Cloud.
• Calcular el costo para Trace
• Configurar el proxy para inhabilitar el muestreo de seguimientos

Ver seguimientos

Un seguimiento rastrea una solicitud entrante a tu API y los diversos eventos (como llamadas RPC o secciones instrumentadas de código), junto con los tiempos precisos de cada evento. Estos eventos se representan como intervalos en el seguimiento.

Para ver los seguimientos de tu proyecto, ve a la página de Cloud Trace en la consola de Google Cloud:

Ir a Trace

En la página Explorador de seguimientos, puedes desglosar un seguimiento individual y ver los intervalos que crea el ESP en un seguimiento. Puedes usar el filtro para ver los seguimientos de una operación o API única.

Los intervalos y seguimientos creados para tu API variarán en función de si tu API usa ESPv2 o ESP. A continuación, se presenta un resumen de los formatos de seguimiento para cada implementación.

Para obtener más información sobre la página Explorador de seguimientos, consulta Busca y explora seguimientos.

Intervalos creados por ESPv2

El ESPv2 crea seguimientos en el siguiente formato:

Como mínimo, el ESPv2 crea 2 intervalos por seguimiento:

• Un intervalo ingress OPERATION_NAME para toda la solicitud y respuesta.
• Un intervalo router BACKEND egress durante el tiempo que ESPv2 espera que el backend procese la solicitud y responda. Esto incluye el salto de red entre ESPv2 y el backend.

Según la configuración de tu API, el ESPv2 puede crear intervalos adicionales:

• Si tu API requiere autenticación, el ESPv2 almacena en caché la clave pública que necesita a fin de realizar la autenticación durante 5 minutos. Si la clave pública no está en la caché, el ESPv2 recupera y almacena en caché la clave pública, y crea un intervalo JWT Remote PubKey Fetch.
• Si la API requiere una clave de API, el ESPv2 almacena en caché la información que necesita para validar la clave. Si la información no está en la caché, el ESPv2 llama al Control de servicios y crea un intervalo Service Control remote call: Check.

Por lo general, el ESPv2 solo crea intervalos para las llamadas de red que bloquean la solicitud entrante. No se realizará un seguimiento de las solicitudes que no generen bloqueos. Cualquier procesamiento local creará eventos de tiempo en lugar de intervalos. Por ejemplo:

• La aplicación de la cuota requiere llamadas remotas, pero estas no se producen en la ruta de una solicitud a la API y no tendrán intervalos asociados en ellas.
• El ESPv2 almacena en caché las claves de API durante un período corto. Todas las solicitudes que usen la caché tendrán un evento de tiempo asociado en el seguimiento.

Intervalos creados por ESP

Advertencia: El ESP no proporciona información detallada de los intervalos. También crea intervalos adicionales que no son significativos. Migra a ESPv2 para ver los seguimientos detallados que siguen las prácticas recomendadas de seguimiento.

El ESP crea seguimientos en el siguiente formato:

Como mínimo, el ESP crea 4 intervalos por seguimiento:

• Un intervalo para toda la solicitud y respuesta
• Un intervalo CheckServiceControl para la llamada al método services.check del Control de servicios a fin de obtener la configuración de tu API.
• Un intervalo QuotaControl para verificar si hay una cuota configurada en tu API.
• Un intervalo Backend que realiza un seguimiento del tiempo que se emplea en el código de backend de tu API.

Según la configuración de tu API, el ESP crea intervalos adicionales:

• Si tu API requiere autenticación, el ESP crea un intervalo CheckAuth en cada seguimiento. Si deseas autenticar un solicitud, el ESP almacena en caché la clave pública que necesita a fin de realizar la autenticación durante 5 minutos. Si la clave pública no está en la caché, el ESP recupera y almacena en caché la clave pública, y crea un intervalo HttpFetch.
• Si tu API requiere una clave de API, el ESP crea un intervalo CheckServiceControlCache en cada seguimiento. El ESP almacena en caché la información que necesita para validar la clave de API. Si la información no está en la caché, el ESP llama al Control de servicios y crea un intervalo Call ServiceControl server.
• Si tienes una cuota configurada en tu API, el ESP crea un intervalo QuotaServiceControlCache en cada seguimiento. El ESP almacena en caché la información que necesita para verificar la cuota. Si la información no está en la caché, el ESP llama al Control de servicios y crea un intervalo Call ServiceControl server.

Tasa de muestreo de seguimientos

El ESP envía muestras de una cantidad pequeña de solicitudes a tu API a fin de obtener los datos de seguimiento. Para controlar la tasa de muestreo, el ESP mantiene un recuento de solicitudes y un temporizador. La cantidad de solicitudes por segundo a tu API determina la tasa de muestreo. Si no hay solicitudes en un segundo, el ESP no envía un seguimiento.

Si el número de solicitudes en un segundo es:

• Menor o igual que 999, el ESP envía 1 seguimiento.
• Entre 1000 y 1999, el ESP envía 2 seguimientos.
• Entre 2000 y 2999, el ESP envía 3 seguimientos.
• Y así sucesivamente.

En resumen, puedes calcular la tasa de muestreo con la función ceiling: ceiling(requests per second/1000)

Cómo calcular el costo de Trace

Si quieres calcular el costo de Trace, debes computar la cantidad de intervalos que el ESP envía a Trace en un mes.

Para estimar el número de intervalos por mes, haz lo siguiente:

1. Calcula la cantidad de solicitudes por segundo que se envían a tu API. Para obtener esta estimación, puedes usar el grafo Solicitudes en la página Servicios > Endpoints o Cloud Logging. Consulta Cómo supervisar tu API para obtener más información.
2. Calcula la cantidad de seguimientos que ESP envía a Trace por segundo: ceiling(requests per second/1000)
3. Estima el número de intervalos en un seguimiento. Para obtener esta estimación, puedes usar la información que aparece en Intervalos creados por ESP o ver la página Lista de seguimientos si quieres ver los seguimientos de tu API.
4. Calcula la cantidad de segundos en la que tu API recibe tráfico en un mes. Por ejemplo, algunas API obtienen solicitudes solo durante ciertos momentos del día, mientras que otras API obtienen solicitudes de manera esporádica.
5. Multiplica el número de segundos en el mes por el número de intervalos.

Por ejemplo:

1. Supongamos que el número máximo de solicitudes por segundo para una API es de 5.
2. La tasa de muestreo de seguimientos es techo (5/1000) = 1.
3. La API no tiene una cuota configurada, no requiere una clave de API ni autenticación. Por lo tanto, la cantidad de intervalos que el ESP crea por seguimiento es 4.
4. Esta API solo recibe solicitudes de lunes a viernes durante el horario de atención. La cantidad de segundos en un mes en la que la API obtiene tráfico es aproximadamente: 3600 X 8 X 20 = 576,000.
5. La cantidad de intervalos por mes es de alrededor de 576,000 x 4 = 2,304,000.

Después de conocer la cantidad aproximada de intervalos en un mes, consulta la página de precios de Trace para obtener información detallada sobre los precios.

Inhabilitar el muestreo de seguimientos

Si quieres que el ESP deje de realizar el muestreo de solicitudes y de enviar seguimientos, puedes configurar una opción de inicio del ESP y reiniciar el ESP. Los seguimientos que el ESP envía a Cloud Trace son independientes de los grafos que se muestran en la página Endpoints > Servicios. Los grafos seguirán estando disponibles si inhabilitas el muestreo de seguimiento.

En la siguiente sección se supone que ya implementaste tu API y el ESP, o que estás familiarizado con el proceso de implementación. Para obtener más información, consulta la sección sobre cómo implementar el backend de la API.

App Engine

Si quieres inhabilitar el muestreo de seguimiento del ESP en el entorno flexible de App Engine, haz lo siguiente:

1. Edita el archivo app.yaml. En la sección endpoints_api_service, agrega la opción trace_samplingy establece su valor en false. Por ejemplo:

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false

   Si tu aplicación se basa en microservicios, debes incluir trace_sampling: false en cada archivo app.yaml.

2. Si hace mucho que actualizas Google Cloud CLI, ejecuta el siguiente comando:

   gcloud components update

3. Guarda el o los archivos app.yaml.
4. Implementa tu código de backend y el ESP en App Engine:

   gcloud app deploy

Para volver a habilitar el muestreo de seguimientos, sigue estos pasos:

1. Quita la opción trace_sampling de app.yaml.
2. Implementa tu código de backend y el ESP en App Engine:

   gcloud app deploy

Compute Engine

Si quieres inhabilitar el muestreo de seguimiento del ESP en Compute Engine con Docker, haz lo siguiente:

1. Conéctate a tu instancia de VM:

   gcloud compute ssh [INSTANCE_NAME]

2. En las marcas del ESP para el comando docker run, agrega la opción --disable_cloud_trace_auto_sampling:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. Emite el comando docker run para reiniciar el ESP.

Para volver a habilitar el muestreo de seguimientos, sigue estos pasos:

1. Quita el --disable_cloud_trace_auto_sampling.
2. Emite el comando docker run para reiniciar el ESP.

GKE

Si quieres inhabilitar el muestreo de seguimiento del ESP en GKE, sigue estos pasos:

1. Abre tu archivo de manifiesto de la implementación, denominado deployment.yaml y agrega lo siguiente a la sección containers:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. Inicia el servicio de Kubernetes con el comando kubectl create:

   kubectl create -f deployment.yaml

Para volver a habilitar el muestreo de seguimientos, sigue estos pasos:

1. Quita la opción --disable_cloud_trace_auto_sampling.
2. Inicia el servicio de Kubernetes:

   kubectl create -f deployment.yaml

Si ejecutas el ESP en una instancia de VM de Compute Engine sin un contenedor de Docker, no habrá un par clave-valor de metadatos de instancia de VM equivalente para la opción --disable_cloud_trace_auto_sampling. Si quieres inhabilitar el muestreo de seguimientos, debes ejecutar el ESP en un contenedor.

Un cliente puede forzar el seguimiento de una solicitud si agrega el encabezado X-Cloud-Trace-Context a la solicitud, como se describe en Fuerza el seguimiento de una solicitud. Si una solicitud contiene el encabezado X-Cloud-Trace-Context, el ESP envía los datos de seguimiento a Trace, incluso si inhabilitaste el muestreo de seguimientos.

Propagación del contexto de seguimiento

Para el seguimiento distribuido, un encabezado de solicitud puede contener un contexto de seguimiento que especifique un ID de seguimiento. El ID de seguimiento se usa cuando el ESPv2 crea intervalos de seguimiento nuevos y los envía a Cloud Trace. El ID de seguimiento se usa para buscar todos los seguimientos y unir intervalos en una solicitud única. Si no se especifica ningún contexto de seguimiento en la solicitud y el seguimiento está habilitado, se genera un ID de seguimiento aleatorio para todos los intervalos de seguimiento.

En el siguiente ejemplo, Cloud Trace correlaciona los intervalos que creó ESPv2 (1) con los intervalos que creó el backend (2) para una sola solicitud. Esto ayuda a depurar problemas de latencia en todo el sistema:

Para obtener más detalles, consulta Conceptos básicos de OpenTelemetry: Propagación de contexto.

Nota: El seguimiento distribuido requiere que tus clientes o backends admitan el seguimiento. Esto está fuera del alcance de esta documentación. Recomendamos usar OpenTelemetry.

Encabezados admitidos

El ESPv2 admite los siguientes encabezados de propagación del contexto de seguimiento:

• traceparent: El encabezado de propagación estándar de contexto de seguimiento W3C. Compatible con la mayoría de los frameworks de seguimiento modernos.
• x-cloud-trace-context: encabezado de propagación del contexto de seguimiento de GCP. Compatible con frameworks de seguimiento más antiguos y bibliotecas de Google, pero específicos del proveedor.
• grpc-trace-bin: Encabezado de propagación del contexto de seguimiento que usan los backends de gRPC con la biblioteca de seguimiento de OpenCensus.

Si compilas una aplicación nueva, recomendamos usar la propagación de seguimiento de contexto traceparent. El ESPv2 extraerá y propagará este encabezado de forma predeterminada. Consulta las Opciones de inicio del seguimiento del ESPv2 a fin de obtener detalles para cambiar el comportamiento predeterminado.

Nota: A diferencia del ESPv2, la propagación del seguimiento de contexto en el ESP debe habilitarse de forma manual a través de las opciones de inicio. El ESP no admite el encabezado traceparent.