Rastrear tu API

OpenAPI   |  gRPC

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

En esta página se explica cómo:

• Consulta las trazas en la Google Cloud consola.
• Calcula el coste de Trace.
• Configura el proxy para inhabilitar el muestreo de trazas.

Ver trazas

Un rastreo monitoriza una solicitud entrante a tu API y los distintos eventos (como llamadas a RPC o secciones de código instrumentadas), así como los tiempos precisos de cada evento. Estos eventos se representan como intervalos en el rastreo.

Para ver las trazas de tu proyecto, ve a la página Cloud Trace en Google Cloud console:

Ir a Trace

En la página Explorador de trazas, puede desglosar la información para ver una traza concreta y los intervalos que crea ESP en una traza. Puedes usar el filtro para ver las trazas de una sola API u operación.

Las trazas y los intervalos creados para tu API variarán en función de si tu API usa ESPv2 o ESP. A continuación, se muestra un resumen de los formatos de traza de cada implementación.

Para obtener más información sobre la página Explorador de trazas, consulta Buscar y explorar trazas.

Intervalos creados por ESPv2

ESPv2 crea trazas con el siguiente formato:

Como mínimo, ESPv2 crea dos intervalos por traza:

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

En función de la configuración de tu API, ESPv2 puede crear spans adicionales:

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

Por lo general, ESPv2 solo crea intervalos para las llamadas de red que bloquean la solicitud entrante. Las solicitudes no bloqueantes no se rastrearán. Cualquier procesamiento local creará eventos de tiempo en lugar de intervalos. Por ejemplo:

• Para aplicar la cuota, se necesitan llamadas remotas, pero estas no se producen en la ruta de una solicitud de API y no tendrán intervalos asociados en el seguimiento.
• ESPv2 almacena en caché las claves de API durante un breve periodo. Las solicitudes que usen la caché tendrán un evento de tiempo asociado en el seguimiento.

Intervalos creados por ESP

Advertencia: ESP no proporciona información detallada sobre los intervalos. También crea spans adicionales que no tienen sentido. Migra a ESPv2 para ver los registros detallados que siguen las prácticas recomendadas de registro.

ESP crea trazas con el siguiente formato:

Como mínimo, ESP crea 4 intervalos por traza:

• Intervalo de toda la solicitud y la respuesta.
• Un intervalo CheckServiceControl para la llamada al método services.check de Service Control para obtener la configuración de tu API.
• Un intervalo QuotaControl para comprobar si hay una cuota configurada en tu API.
• Un intervalo Backend que registra el tiempo empleado en el código de backend de tu API.

En función de la configuración de tu API, ESP crea tramos adicionales:

• Si tu API requiere autenticación, ESP crea un CheckAuth span en cada traza. Para autenticar una solicitud, ESP almacena en caché la clave pública que necesita para autenticar durante 5 minutos. Si la clave pública no está en la caché, ESP la obtiene y la almacena en caché, y crea un intervalo HttpFetch.
• Si tu API requiere una clave de API, ESP crea un CheckServiceControlCache span en cada traza. ESP almacena en caché la información que necesita para validar la clave de API. Si la información no está en la caché, ESP llama a Service Control y crea un intervalo Call ServiceControl server.
• Si has definido una cuota para tu API, ESP crea un intervalo QuotaServiceControlCache en cada traza. ESP almacena en caché la información que necesita para comprobar la cuota. Si la información no está en la caché, ESP llama a Service Control y crea un intervalo Call ServiceControl server.

Frecuencia de muestreo de trazas

ESP toma una muestra de un pequeño número de solicitudes a tu API para obtener datos de seguimiento. Para controlar la frecuencia de muestreo, ESP mantiene un contador de solicitudes y un temporizador. El número de solicitudes por segundo a tu API determina la frecuencia de muestreo. Si no hay solicitudes en un segundo, ESP no envía un rastreo.

Si el número de solicitudes por segundo es:

• Si es menor o igual que 999, el proveedor de servicios de correo electrónico envía 1 traza.
• Entre 1000 y 1999, el proveedor de servicios de correo electrónico envía 2 trazas.
• Entre 2000 y 2999, ESP envía 3 trazas.
• Y así sucesivamente.

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

Estimar el coste de Trace

Para estimar el coste de Trace, debes calcular el número de intervalos que ESP envía a Trace en un mes.

Para estimar el número de intervalos al mes, sigue estos pasos:

1. Estima el número de solicitudes por segundo a tu API. Para obtener esta estimación, puedes usar el gráfico Solicitudes de la página Endpoints > Servicios o Cloud Logging. Consulta más información en el artículo Monitorizar tu API.
2. Calcula el número de trazas que envía ESP a Trazas por segundo: ceiling(requests per second/1000)
3. Calcula el número de intervalos de una traza. Para obtener esta estimación, puedes usar la información de Intervalos creados por ESP o consultar la página Lista de trazas para ver las trazas de tu API.
4. Estima el número de segundos al mes en los que tu API recibe tráfico. Por ejemplo, algunas APIs solo reciben solicitudes durante determinadas horas del día, mientras que otras las reciben de forma esporádica.
5. Multiplica el número de segundos del mes por el número de intervalos.

Por ejemplo:

1. Supongamos que el número máximo de solicitudes por segundo de una API es 5.
2. La frecuencia de muestreo de la traza es el valor máximo de (5/1000) = 1.
3. La API no tiene ninguna cuota configurada, no requiere una clave de API ni autenticación. Por lo tanto, el número de intervalos que crea ESP por cada traza es 4.
4. Esta API solo recibe solicitudes durante el horario de oficina, de lunes a viernes. El número de segundos al mes en los que la API recibe tráfico es aproximadamente el siguiente: 3600 × 8 × 20 = 576.000
5. El número de intervalos al mes es de aproximadamente 576.000 x 4 = 2.304.000.

Cuando sepas el número aproximado de intervalos de un mes, consulta la página Precios de Trace para obtener información detallada sobre los precios.

Inhabilitar el muestreo de trazas

Si quieres que el ESP deje de muestrear solicitudes y enviar trazas, puedes definir una opción de inicio del ESP y reiniciar el ESP. Las trazas que envía ESP a Cloud Trace son independientes de los gráficos que se muestran en la página Endpoints > Services (Endpoints > Servicios). Los gráficos seguirán estando disponibles si inhabilitas el muestreo de trazas.

En la siguiente sección se presupone que ya has implementado tu API y ESP, o que conoces el proceso de implementación. Para obtener más información, consulta Implementar el backend de la API.

Compute Engine

Para inhabilitar el muestreo de trazas de ESP en Compute Engine con Docker, sigue estos pasos:

1. Conéctate a tu instancia de VM:

   gcloud compute ssh [INSTANCE_NAME]

2. En las marcas de ESP del comando docker run, añade 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. Ejecuta el comando docker run para reiniciar el ESP.

Para volver a habilitar el muestreo de trazas, haz lo siguiente:

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

GKE

Para inhabilitar el muestreo de trazas de ESP en GKE, sigue estos pasos:

1. Abre el archivo de manifiesto de la implementación, denominado deployment.yaml, y añade 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 trazas, haz lo siguiente:

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

   kubectl create -f deployment.yaml

Si ejecutas ESP en una instancia de máquina virtual de Compute Engine sin un contenedor Docker, no hay ningún par clave-valor de metadatos de instancia de máquina virtual equivalente para la opción --disable_cloud_trace_auto_sampling. Si quieres inhabilitar el muestreo de trazas, debes ejecutar ESP en un contenedor.

Un cliente puede forzar que se rastree una solicitud añadiendo el encabezado X-Cloud-Trace-Context a la solicitud, tal como se describe en la sección Forzar que se rastree una solicitud. Si una solicitud contiene el encabezado X-Cloud-Trace-Context, el ESP envía los datos de la traza a Trace aunque hayas inhabilitado el muestreo de trazas.

Propagación del contexto de rastreo

En el caso del rastreo distribuido, un encabezado de solicitud puede contener un contexto de rastreo que especifique un ID de rastreo. El ID de traza se usa cuando ESPv2 crea nuevos intervalos de traza y los envía a Cloud Trace. El ID de la traza se usa para buscar todas las trazas y combinar los intervalos de una sola solicitud. Si no se especifica ningún contexto de rastreo en la solicitud y el rastreo está habilitado, se genera un ID de rastreo aleatorio para todos los intervalos de rastreo.

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

Para obtener más información, consulta el artículo Conceptos básicos de OpenTelemetry: propagación de contexto.

Nota: El rastreo distribuido requiere que tus clientes o tus back-ends admitan el rastreo. Esto queda fuera del ámbito de esta documentación. Te recomendamos que uses OpenTelemetry.

Encabezados admitidos

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

• traceparent: encabezado de propagación de contexto de seguimiento estándar de 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 antiguos y bibliotecas de Google, pero específico de cada proveedor.
• grpc-trace-bin: encabezado de propagación del contexto de traza usado por los backends de gRPC con la biblioteca de trazas OpenCensus.

Si estás creando una aplicación nueva, te recomendamos que uses la propagación de traceparentcontexto de rastreo. ESPv2 extraerá y propagará este encabezado de forma predeterminada. Consulta Opciones de inicio de la monitorización de ESPv2 para obtener más información sobre cómo cambiar el comportamiento predeterminado.

Nota: A diferencia de ESPv2, la propagación del contexto de rastreo en ESP debe habilitarse manualmente mediante las opciones de inicio. El ESP no admite el encabezado traceparent.