Habilitar el análisis de trazas

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

Consulta la documentación de Apigee Edge.

En esta página se describen los pasos necesarios para configurar el rastreo distribuido en tu tiempo de ejecución de Apigee. Si no tienes experiencia con los sistemas de seguimiento distribuido y quieres obtener más información, consulta el artículo Información sobre el seguimiento distribuido.

Introducción

Los sistemas de análisis de trazas distribuidas te permiten monitorizar una solicitud en un sistema de software distribuido en varias aplicaciones, servicios y bases de datos, así como 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 distintos servicios a los que se llama durante una solicitud, lo que permite comprender mejor lo que ocurre en cada paso del sistema de software.

La herramienta de seguimiento de Apigee Edge y la herramienta de depuración de Apigee son útiles para solucionar problemas y monitorizar tus proxies de API. Sin embargo, estas herramientas no envían datos a servidores de seguimiento distribuido, como Cloud Trace o Jaeger. Para ver los datos del tiempo de ejecución de Apigee en un informe de seguimiento distribuido, debes habilitar explícitamente el seguimiento distribuido en tu tiempo de ejecución de Apigee. Una vez que se ha habilitado el análisis de trazas, el tiempo de ejecución puede enviar datos de trazas a los servidores de análisis de trazas distribuidas y participar en una traza ya existente. De esta forma, puede ver datos de dentro y fuera de su ecosistema de Apigee desde una sola ubicación.

En los informes de seguimiento distribuido, puede consultar la siguiente información:

  • Tiempo de ejecución de todo un flujo.
  • Hora a la que se recibe la solicitud.
  • Hora a la que se envía la solicitud al destino.
  • Hora a la que se recibe la respuesta del destino.
  • Tiempo de ejecución de cada política de un flujo.
  • Tiempo de ejecución de las llamadas de servicio y los flujos de destino.
  • Hora a la que se envía la respuesta al cliente.

En el informe de seguimiento distribuido, puede ver los detalles de ejecución de los flujos como spans. Un intervalo hace referencia al tiempo que tarda un flujo en una traza. El tiempo necesario para ejecutar un flujo se muestra como la suma del tiempo necesario para ejecutar cada política del flujo. Puedes ver cada uno de los siguientes flujos como intervalos individuales:

  • Solicitar
    • Proxy
      • Preflow
      • PostFlow
    • Objetivo
      • Preflow
      • PostFlow
  • Respuesta
    • Proxy
      • Preflow
      • PostFlow
    • Objetivo
      • Preflow
      • PostFlow

Una vez que habilites el rastreo distribuido, el tiempo 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 ampliar el comportamiento predeterminado del tiempo de ejecución y rastrear variables de flujo, de política o personalizadas adicionales. Para obtener más información, consulta la política de TraceCapture.

Variables de seguimiento predeterminadas en el informe de seguimiento

Una vez que se haya habilitado el rastreo distribuido, podrá ver el siguiente conjunto de variables predefinidas en el informe de rastreo. Las variables se pueden ver en los siguientes intervalos:

  • POST_RESP_SENT: este intervalo se añade después de recibir una respuesta del servidor de destino.
  • POST_CLIENT_RESP_SENT: este intervalo se añade después de que se envíe la respuesta del proxy al cliente.

Variables en el intervalo POST_RESP_SENT

Las siguientes variables se pueden ver 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 se pueden ver 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)
  • ESERROR (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 análisis de trazas distribuidas admitidos

El tiempo de ejecución de Apigee admite los siguientes sistemas de seguimiento distribuido:

  • Cloud Trace
  • Jaeger

Puede configurar su tiempo de ejecución de Apigee para que envíe datos de seguimiento a un sistema Cloud Trace o Jaeger.

Como el seguimiento de todas las llamadas a la API en el tiempo de ejecución de Apigee afectaría al rendimiento, Apigee te permite configurar una tasa de muestreo probabilística. Con la frecuencia de muestreo, puede especificar el número de llamadas a la API que se envían para el rastreo distribuido. Por ejemplo, si especifica la frecuencia de muestreo como 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.

Configurar tiempos de ejecución de Apigee para Cloud Trace

Tanto el entorno de ejecución de Apigee como el entorno de ejecución híbrido de Apigee admiten el rastreo distribuido mediante Cloud Trace. Si usas Jaeger, puedes saltarte esta sección y pasar a Habilitar el rastreo distribuido para Jaeger.

Configurar el tiempo 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 Cloud Trace. Esta opción permite que tu proyecto de Google Cloud reciba datos de trazas de fuentes autenticadas.

Para confirmar que la API Cloud Trace está habilitada, haz lo siguiente:

  1. En la consola de Google Cloud, ve a APIs y servicios:

    Ir a APIs y servicios

  2. Haz clic en Habilitar APIs y servicios.
  3. En la barra de búsqueda, escribe API Trace.
  4. Si se muestra el mensaje API habilitada, significa que esta API ya está habilitada y no tienes que hacer nada. De lo contrario, haz clic en Habilitar.

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

La API Cloud Trace debe estar habilitada para usar Cloud Trace con un entorno de ejecución híbrido de Apigee. Para confirmar que la API Cloud Trace está habilitada, sigue los pasos que se indican en el artículo sobre cómo configurar el tiempo de ejecución de Apigee para Cloud Trace.

Además de habilitar la API Cloud Trace, debe añadir la cuenta de servicio iam.gserviceaccount.com para usar Cloud Trace con el tiempo de ejecución híbrido. Para añadir la cuenta de servicio, junto con los roles y las claves necesarios, sigue estos pasos:

  1. Crea una cuenta de servicio: 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. Añade una vinculación de política de gestión de identidades y accesos 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
  3. Crea una clave de cuenta de servicio: 
    gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
  4. Añade la cuenta de servicio al archivo overrides.yaml.
    5. envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json
  5. Aplica los cambios al tiempo de ejecución con Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Habilitar el análisis de trazas

Antes de habilitar el rastreo 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

Donde:

  • TOKEN define el encabezado de autenticación con un token de portador. Utiliza este encabezado cuando llames a las APIs 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.

Habilitar el análisis de trazas para Cloud Trace

En el siguiente ejemplo se muestra cómo habilitar el rastreo distribuido de Cloud Trace:

  1. 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 al seguimiento distribuido. Para obtener más información sobre cómo definir un samplingRate para tu entorno de tiempo de ejecución, consulta Consideraciones sobre el rendimiento.
    • El parámetro exporter tiene el valor CLOUD_TRACE.
    • El endpoint se define en el proyecto de Google Cloud al que quieres enviar el rastreo. NOTA: Debe coincidir con la cuenta de servicio que se ha creado en el paso de configuración.

    Una respuesta correcta tiene un aspecto similar al siguiente:

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

Habilitar el análisis de trazas distribuido para Jaeger

En el siguiente ejemplo se muestra cómo habilitar el rastreo distribuido de 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:

  • El valor de samplingRate es 0,4. Esto significa que aproximadamente el 40% de las llamadas a la API se envían al rastreo distribuido.
  • El parámetro exporter tiene el valor JAEGER.
  • El endpoint se define en la ubicación donde se ha instalado y configurado Jaeger.

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

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

Ver la configuración del análisis de trazas distribuido

Para ver la configuración de seguimiento distribuido que ya tienes en tu tiempo de ejecución, inicia sesión en él y 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, verás una respuesta similar a la siguiente:

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

Actualizar la configuración del análisis de trazas distribuido

El siguiente comando muestra cómo actualizar la configuración de seguimiento distribuido de 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, verás una respuesta similar a la siguiente:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}
 En este ejemplo, la frecuencia de muestreo se actualiza a 0.05.

Inhabilitar la configuración del análisis de trazas distribuido

En el siguiente ejemplo se muestra cómo inhabilitar el rastreo 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, verás una respuesta similar a la siguiente:

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

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

Cuando habilitas el rastreo distribuido en tu tiempo de ejecución de Apigee, todos los proxies de API del tiempo de ejecución usan la misma configuración para el rastreo. Sin embargo, puedes anular la configuración del rastreo distribuido de un proxy de API o de un grupo de proxies de API. De esta forma, tendrás un control más detallado sobre la configuración del seguimiento.

En el siguiente ejemplo se anula la configuración del rastreo distribuido del 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.

Actualizar las anulaciones de la 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:

  1. Usa el siguiente comando para obtener las anulaciones de la configuración de seguimiento que haya: 
    curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

    Este comando debería devolver una respuesta similar a la siguiente, que contiene un campo "name" que identifica el proxy o los proxies regidos por la anulación: 

    {
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}
  2. Para actualizar el proxy, usa el valor del campo "name" para enviar una solicitud POST a la configuración de anulación de ese proxy,junto con los valores de los campos 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}}'

Eliminar anulaciones de configuración de trazas

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

  1. Usa el siguiente comando para obtener las anulaciones de la configuración de seguimiento que haya: 
    curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

    Este comando debería devolver una respuesta similar a la siguiente, que contiene un campo "name" que identifica el proxy o los proxies regidos por la anulación: 

    {
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}
  2. Para eliminar el proxy, usa el valor del campo "name" 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 sobre el rendimiento.

Si habilitas el rastreo distribuido en un entorno de ejecución de Apigee, se espera que el rendimiento se vea afectado. El impacto puede traducirse en un aumento del uso de memoria, de los requisitos de CPU y de la latencia. La magnitud del impacto dependerá en parte de la complejidad del proxy de API (por ejemplo, del número de políticas) y de la tasa de muestreo probabilística (definida como samplingRate). Cuanto mayor 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 reducción del rendimiento del 10-20% al usar el rastreo distribuido.

En entornos con mucho tráfico y requisitos de baja latencia, la tasa de muestreo probabilístico recomendada es inferior o igual al 10%. Si quieres usar el rastreo distribuido para solucionar problemas, considera la posibilidad de aumentar el muestreo probabilístico (samplingRate) solo en proxies de API específicos.