Habilitar el seguimiento distribuido

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se muestran los pasos necesarios a fin de configurar el seguimiento distribuido para tu entorno de ejecución de Apigee. Si no tienes experiencia en los sistemas de seguimiento distribuido y quieres obtener más información, consulta Información sobre el seguimiento distribuido.

Introducción

Los sistemas de seguimiento distribuido te permiten realizar un seguimiento de una solicitud en un sistema de software distribuido en varios servicios, aplicaciones y bases de datos, además de intermediarios como proxies. Estos sistemas de seguimiento generan informes que muestran el tiempo que tarda una solicitud en cada paso. Los informes de seguimiento también pueden proporcionar una vista detallada de los diversos servicios llamados durante una solicitud, lo que permite una comprensión más profunda de lo que sucede en cada paso en tu sistema de software.

La herramienta de seguimiento en Apigee Edge y la herramienta de depuración en Apigee son útiles para solucionar problemas y supervisar tus proxies de API. Sin embargo, estas herramientas no envían datos a los servidores de seguimiento distribuidos, como Cloud Trace o Jaeger. Para ver los datos del entorno de ejecución de Apigee en un informe de seguimiento distribuido, debes habilitar el seguimiento distribuido de forma explícita en el entorno de ejecución de Apigee. Una vez habilitado el seguimiento, el entorno de ejecución puede enviar datos de seguimiento a servidores de seguimiento distribuidos y participar en un seguimiento existente. Como resultado, puedes ver los datos desde y hacia tu ecosistema de Apigee desde una sola ubicación.

Puedes ver la siguiente información en informes de seguimiento distribuido:

Tiempo de ejecución de un flujo completo.
Hora en la que se recibe la solicitud.
Hora en la que se envía la solicitud al destino.
Hora en la que se recibe la respuesta del objetivo.
Tiempo de ejecución de cada política en un flujo.
Tiempo de ejecución de los textos destacados del servicio y los flujos de destino.
La hora a la que se envía la respuesta al cliente.

En el informe de seguimiento distribuido, puedes ver los detalles de ejecución de los flujos como intervalos. Un intervalo hace referencia al tiempo que tarda un flujo en un seguimiento. El tiempo que lleva ejecutar un flujo se muestra como un agregado del tiempo necesario a fin de ejecutar cada política en el flujo. Puedes ver cada uno de los siguientes flujos como intervalos individuales:

Solicitud
- Proxy
  - Anterior al flujo
  - PostFlow
- Target
  - Anterior al flujo
  - PostFlow
Respuesta
- Proxy
  - Anterior al flujo
  - PostFlow
- Target
  - Anterior al flujo
  - PostFlow

Una vez que habilites el seguimiento distribuido, el entorno de ejecución de Apigee rastreará un conjunto de variables predefinidas de forma predeterminada. Para obtener más información, consulta Variables de seguimiento predeterminadas en el informe de seguimiento. Puedes usar la política TraceCapture para extender el comportamiento del entorno de ejecución predeterminado y realizar un seguimiento de los flujos, las políticas o las variables personalizadas adicionales. Para obtener más información, consulta la política TraceCapture.

Una llamada entrante de la API a Apigee puede contener encabezados de seguimiento, ya que es parte de un seguimiento existente. En este caso, Apigee participa en el seguimiento existente y propaga los encabezados a la llamada saliente a la API. El entorno de ejecución de Apigee comprende el formato del encabezado Zipkin B3. Por lo tanto, reconoce los encabezados x-b3-traceid, x-b3-spanid y x-b3-sampled cuando participa en un seguimiento existente. Sin embargo, si no hay encabezados de seguimiento en una llamada a la API entrante, Apigee agregará sus encabezados de seguimiento y los propagará a la llamada a la API saliente. Otros servicios pueden acceder a los encabezados y participar en el seguimiento si es necesario.

Variables de seguimiento predeterminadas en el informe de seguimiento

Una vez que el seguimiento distribuido esté habilitado, podrás ver el siguiente conjunto de variables predefinidas en el informe de seguimiento. Las variables son visibles en los siguientes intervalos:

POST_RESP_SENT: Este intervalo se agrega después de que se recibe una respuesta del servidor de destino.
POST_CLIENT_RESP_SENT: este intervalo se agrega después de que se envía la respuesta del proxy al cliente.

Variables del intervalo POST_RESP_SENT

Las siguientes variables son visibles en el intervalo POST_RESP_SENT:

REQUEST_URL (request.url)
REQUEST_VERB (request.verb)
RESPONSE_STATUS_CODE (response.status.code)
ROUTE_NAME (route.name)
ROUTE_TARGET (route.target)
TARGET_BASE_PATH (target.basepath)
TARGET_HOST (target.host)
TARGET_IP (target.ip)
TARGET_NAME (target.name)
TARGET_PORT (target.port)
TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
TARGET_SSL_ENABLED (target.ssl.enabled)
TARGET_URL (target.url)

Variables en el intervalo POST_CLIENT_RESP_SENT

Las siguientes variables son visibles en el intervalo POST_CLIENT_RESP_SENT:

API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
ENVIRONMENT_NAME (environment.name)
FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
IS_ERROR (is.error)
MESSAGE_ID (message.id)
MESSAGE_STATUS_CODE (message.status.code)
PROXY_BASE_PATH (proxy.basepath)
PROXY_CLIENT_IP (proxy.client.ip)
PROXY_NAME (proxy.name)
PROXY_PATH_SUFFIX (proxy.pathsuffix)
PROXY_URL (proxy.url)

Sistemas de seguimiento distribuido compatibles

El entorno de ejecución de Apigee es compatible con los siguientes sistemas de seguimiento distribuido:

Cloud Trace
Jaeger

Puedes configurar el entorno de ejecución de Apigee para que envíe los datos de seguimiento a Cloud Trace o a un sistema de Jaeger.

Debido a que el seguimiento de todas las llamadas a la API en el entorno de ejecución de Apigee afectaría el rendimiento, Apigee te permite configurar una tasa de muestreo probabilística. Mediante la tasa de muestreo, puedes especificar la cantidad de llamadas a la API que se envían para el seguimiento distribuido. Por ejemplo, si especificas la tasa de muestreo en 0.4, significa que el 40% de las llamadas a la API se envían para el seguimiento. Para obtener más información, consulta Consideraciones sobre el rendimiento.

La tasa de muestreo máxima configurable es de 0.5.

Configura los entornos de ejecución de Apigee para Cloud Trace

El entorno de ejecución de Apigee y el entorno de ejecución híbrido de Apigee admiten el seguimiento distribuido mediante Cloud Trace. Si usas Jaeger, puedes omitir esta sección y continuar con Habilita el seguimiento distribuido para Jaeger.

Configura el entorno de ejecución de Apigee para Cloud Trace

Para usar Cloud Trace con un entorno de ejecución de Apigee, tu proyecto de Google Cloud debe tener habilitada la API de Cloud Trace. Esta configuración permite que tu proyecto de Google Cloud reciba datos de seguimiento de fuentes autenticadas.

Para confirmar que la API de Cloud Trace esté habilitada, sigue estos pasos:

En la consola de Google Cloud, ve a API y servicios:
Ir a API y Services.
Haga clic en Habilitar API y servicios.
En la barra de búsqueda, ingresa API de Trace.
Si se muestra API habilitada, esta API ya está habilitada y no necesitas hacer nada. De lo contrario, haz clic en Habilitar.

Configura el entorno de ejecución de Apigee Hybrid para Cloud Trace

La API de Cloud Trace debe estar habilitada para usar Cloud Trace con un entorno de ejecución híbrido de Apigee. Para confirmar que la API de Cloud Trace esté habilitada, sigue los pasos en Configura el entorno de ejecución de Apigee para Cloud Trace.

Además de habilitar la API de Cloud Trace, debes agregar la cuenta de servicio iam.gserviceaccount.com para usar Cloud Trace con el entorno de ejecución híbrido. Para agregar la cuenta de servicio, junto con las funciones y claves requeridas, sigue estos pasos:

Cree una cuenta de servicio nueva:

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

Agrega una vinculación de política de IAM a la cuenta de servicio:

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

Para crear una clave de cuenta de servicio, haz lo siguiente:
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
Las claves de cuenta de servicio son un riesgo de seguridad si no se administran de forma adecuada. Eres responsable de la seguridad de la clave privada y de otras operaciones que se describen en Prácticas recomendadas para administrar claves de cuentas de servicio. Si no se te permite crear una clave de cuenta de servicio, es posible que la creación de claves de cuentas de servicio esté inhabilitada para tu organización. Para obtener más información, consulta Administra los recursos de la organización con seguridad de forma predeterminada.
Agrega la cuenta de servicio al archivo overrides.yaml

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

Aplica los cambios al entorno de ejecución.

apigeectl apply -f overrides.yaml --env=ENV_NAME

Habilita el seguimiento distribuido

Antes de habilitar el seguimiento distribuido para Cloud Trace o Jaeger, crea las siguientes variables de entorno:

TOKEN="Authorization: Bearer $(gcloud auth print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

Aquí:

TOKEN define el encabezado de autenticación con un token del portador. Usarás este encabezado cuando llames a las API de Apigee. Para obtener más información, consulta la página de referencia del comando print-access-token.
ENV_NAME es el nombre de un entorno de tu organización.
PROJECT_ID es el ID de tu proyecto de Google Cloud.

Habilita el seguimiento distribuido para Cloud Trace

En el siguiente ejemplo, se muestra cómo habilitar el seguimiento distribuido para Cloud Trace:

Ejecuta esta llamada a la API de Apigee:
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'",
    "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
```
El cuerpo de la solicitud de ejemplo consta de los siguientes elementos:
- El valor de samplingRate es 0.1. Esto significa que aproximadamente el 10% de las llamadas a la API se envían para el seguimiento distribuido. Para obtener más información sobre la configuración de un samplingRate para tu entorno de ejecución, consulta Consideraciones de rendimiento.
- El parámetro exporter está configurado como CLOUD_TRACE.
- El extremo se configura en el proyecto de Google Cloud al que deseas que se envíe el seguimiento. NOTA: Debe coincidir con la cuenta de servicio que se agregó en el paso de configuración.
Una respuesta correcta es similar a la siguiente:
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

Habilita el seguimiento distribuido para Jaeger

En el siguiente ejemplo, se muestra cómo habilitar el seguimiento distribuido para Jaeger:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

En este ejemplo:

samplingRate se establece en 0.4. Esto significa que aproximadamente el 40% de las llamadas a la API se envían para el seguimiento distribuido.
El parámetro exporter está configurado como JAEGER.
El extremo se establece en el lugar en el que Jaeger está instalado y configurado.

Cuando ejecutes el comando, podrás ver una respuesta similar a la siguiente:

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

Observa la configuración del seguimiento distribuido

Para ver la configuración de seguimiento distribuido existente en tu entorno de ejecución, accede a este y, luego, ejecuta el siguiente comando:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

Cuando ejecutes el comando, podrás ver una respuesta similar a la siguiente:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

Actualiza la configuración del seguimiento distribuido

En el siguiente comando, se muestra cómo actualizar la configuración de seguimiento distribuido existente para Cloud Trace:

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

Cuando ejecutes el comando, podrás ver una respuesta similar a la siguiente:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

En este ejemplo, la tasa de muestreo se actualiza a 0.05.

A fin de actualizar la configuración de Jaeger, establece el campo exporter de la solicitud en JAEGER.

Inhabilita la configuración de seguimiento distribuido

En el siguiente ejemplo, se muestra cómo inhabilitar el seguimiento distribuido configurado para Cloud Trace:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

Cuando ejecutes el comando, podrás ver una respuesta similar a la siguiente:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

Anula la configuración de seguimiento de los proxies de API

Cuando habilitas el seguimiento distribuido en el entorno de ejecución de Apigee, todos los proxies de API del entorno de ejecución usan la misma configuración para el seguimiento. Sin embargo, puedes anular la configuración de seguimiento distribuido para un proxy de API o un grupo de proxies de API. Esto te brinda un control más detallado sobre la configuración de seguimiento.

En el siguiente ejemplo, se anula la configuración de seguimiento distribuido para el proxy de API hello-world:

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

Puedes anular la configuración para solucionar problemas específicos de un proxy de API sin tener que cambiar la configuración de todos los proxies de API.

Actualiza anulaciones de configuración de seguimiento

Para actualizar una anulación de la configuración de seguimiento de un proxy de API o un grupo de proxies de API, sigue estos pasos:

Usa el siguiente comando para recuperar cualquier anulación de configuración de seguimiento existente:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

Este comando debe mostrar una respuesta similar a la siguiente, que contiene un campo "nombre" que identifica el proxy o los proxies que se rigen por la anulación:

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

Si deseas actualizar el proxy, usa el valor del campo "nombre" para enviar una solicitud POST a la configuración de anulación de ese proxy, junto con los valores de campo actualizados. Por ejemplo:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

Borra anulaciones de configuración de seguimiento

Para borrar una anulación de la configuración de seguimiento de un proxy de API o un grupo de proxies de API, sigue estos pasos:

Usa el siguiente comando para recuperar cualquier anulación de configuración de seguimiento existente:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

Este comando debe mostrar una respuesta similar a la siguiente, que contiene un campo "nombre" que identifica el proxy o los proxies que se rigen por la anulación:

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

Si deseas borrar el proxy, usa el valor del campo "nombre" para enviar una solicitud DELETE a la configuración de anulación de ese proxy, junto con los valores de campo actualizados. Por ejemplo:
```
curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \
```

Consideraciones de rendimiento

Se espera un impacto en el rendimiento cuando habilitas el seguimiento distribuido para un entorno de ejecución de Apigee. El impacto puede aumentar el uso de memoria, los requisitos de CPU y la latencia. La magnitud del impacto dependerá en parte de la complejidad del proxy de API (por ejemplo, la cantidad de políticas) y la tasa de muestreo probabilística (configurada como samplingRate). Cuanto más alta sea la tasa de muestreo, mayor será el impacto en el rendimiento. Aunque el impacto en el rendimiento depende de varios factores, puedes esperar una disminución del 10 al 20% en el rendimiento cuando se usa el seguimiento distribuido.

Para entornos con tráfico alto y requisitos de latencia baja, la tasa de muestreo probabilística recomendada es inferior al 10%. Si deseas usar el seguimiento distribuido para solucionar problemas, considera aumentar el muestreo probabilístico (samplingRate) solo para proxies de API específicos.