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.

Para obtener más información sobre los términos que se usan en esta página, consulta la descripción general de Cloud Trace.

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 distribuido, como Cloud Trace, Jaeger o un recopilador de OpenTelemetry.

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:

Fase Extremo Flujo
Solicitud Proxy Anterior al flujo
PostFlow
Objetivo Anterior al flujo
PostFlow
Respuesta Proxy Anterior al flujo
PostFlow
Objetivo Anterior al flujo
Posterior al flujo

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.

Variables de seguimiento predeterminadas en el informe de seguimiento

Se aplica a: ambas configuraciones de OpenTelemetry y OpenCensus.

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:

  • RESP_SENT: Este intervalo se agrega después de que se recibe una respuesta del servidor de destino. Contiene los atributos del destino que se enumeran en Variables in the RESP_SENT span.
  • PROXY_POST_RESP_SENT: Este intervalo se agrega después de que se envía la respuesta del proxy al cliente. Contiene los atributos del servidor proxy que se enumeran en Variables en el intervalo PROXY_POST_RESP_SENT.
  • EVENT_FLOW_RESP y EVENT_FLOW_END: Estos intervalos se agregan para los proxies de API que controlan las respuestas de transmisión de eventos enviados por el servidor (SSE). EVENT_FLOW_RESP marca el flujo de respuesta de SSE (se ejecuta una vez por mensaje de respuesta). EVENT_FLOW_END marca el final de la transmisión de SSE. Actualmente, estos intervalos no incluyen atributos predeterminados, sino que aparecen en el registro como intervalos con nombre para que las fases de SSE del proxy sean visibles en el informe de registro.

Atributos de recursos predeterminados

Se aplica a: Solo OpenTelemetry. Esta sección no se aplica a la configuración de OpenCensus.

Cuando usas OpenTelemetry con el protocolo de seguimiento de OTLP, el entorno de ejecución de Apigee adjunta los siguientes atributos de recursos de la convención semántica de OpenTelemetry a cada intervalo emitido:

Atributo Descripción
service.name Se corrigió el valor apigee.googleapis.com.
service.instance.id Es el identificador de la instancia del procesador de mensajes que emitió el intervalo. Se omite cuando no está disponible la identidad del Pod de entorno de ejecución.
cloud.provider Siempre gcp.
cloud.platform Siempre gcp_apigee.
cloud.region Región que aloja el entorno de ejecución de Apigee. Si no se configura ninguna región, se recurre a global.
cloud.resource_id Ruta de acceso al recurso de Apigee completamente calificada con el formato /apigee.googleapis.com/organizations/ORG/environments/ENV.
gcp.apigee.organization Es el nombre de la organización de Apigee.
gcp.apigee.environment Es el nombre del entorno de Apigee.
gcp.project_id ID del proyecto Google Cloud . Se emite solo cuando el exportador es OPEN_TELEMETRY_CLOUD_TRACE.

Tipos de intervalos

Se aplica a: ambas configuraciones de OpenTelemetry y OpenCensus.

Apigee emite intervalos con los siguientes valores de SpanKind:

SpanKind Intervalos emitidos con este tipo
SERVER Es el intervalo del proxy raíz (uno por invocación del proxy), que representa la solicitud entrante que recibió el entorno de ejecución de Apigee.
INTERNAL Todos los demás intervalos, incluidos los intervalos de flujo (por ejemplo, RESP_SENT y PROXY_POST_RESP_SENT) y cada intervalo de paso de política (por ejemplo, AssignMessage, VerifyAPIKey, ServiceCallout, JavaScript, KeyValueMapOperations).

Apigee no emite intervalos CLIENT, PRODUCER ni CONSUMER. En particular, las llamadas salientes de Apigee al backend de destino no se emiten como intervalos CLIENT separados; la llamada saliente se representa dentro de los intervalos de flujo INTERNAL existentes y el encabezado traceparent se propaga al destino para que el servicio de destino pueda emitir su propio intervalo SERVER y unirse al mismo seguimiento.

Variables en el intervalo RESP_SENT

Las siguientes variables son visibles en el intervalo RESP_SENT. La columna Variable semántica de OTEL muestra el nombre de la convención semántica de OpenTelemetry que se usa cuando spanSemantics se establece en OTEL; la columna Atributo muestra el nombre del atributo heredado.

Variable heredada Variable semántica de OTEL Atributo Descripción
REQUEST_URL url.full request.url Es la URL completa de la solicitud entrante del cliente que recibió el proxy.
REQUEST_VERB http.request.method request.verb Verbo HTTP de la solicitud del cliente entrante (por ejemplo, GET o POST).
RESPONSE_STATUS_CODE http.response.status_code response.status.code Es el código de estado de respuesta que muestra el servidor de destino.
ROUTE_NAME gcp.apigee.route.name route.name Es el nombre de la regla de enrutamiento que seleccionó el destino para esta solicitud.
ROUTE_TARGET gcp.apigee.route.target route.target Nombre del extremo de destino seleccionado por la regla de enrutamiento.
TARGET_BASE_PATH gcp.apigee.target.basepath target.basepath Es la parte de la ruta base de la URL de destino.
TARGET_HOST server.address target.host Es el nombre de host del servidor de destino con el que se comunica el proxy.
TARGET_IP server.address target.ip Es la dirección IP resuelta del servidor de destino.
TARGET_NAME gcp.apigee.target.name target.name Nombre del extremo de destino definido en el proxy de API.
TARGET_PORT server.port target.port Es el puerto TCP que se usa para conectarse al servidor de destino.
TARGET_RECEIVED_END_TIMESTAMP gcp.apigee.target.received_end_timestamp target.received.end.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy terminó de recibir la respuesta del servidor de destino.
TARGET_RECEIVED_START_TIMESTAMP gcp.apigee.target.received_start_timestamp target.received.start.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy comenzó a recibir la respuesta del servidor de destino.
TARGET_SENT_END_TIMESTAMP gcp.apigee.target.sent_end_timestamp target.sent.end.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy terminó de enviar la solicitud al servidor de destino.
TARGET_SENT_START_TIMESTAMP gcp.apigee.target.sent_start_timestamp target.sent.start.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy comenzó a enviar la solicitud al servidor de destino.
TARGET_SSL_ENABLED gcp.apigee.target.ssl_enabled target.ssl.enabled Es un valor booleano que indica si la conexión al servidor de destino usó TLS.
TARGET_URL url.full target.url Es la URL completa del servidor de destino con el que se comunica el proxy.

Variables en el intervalo PROXY_POST_RESP_SENT

Las siguientes variables son visibles en el intervalo PROXY_POST_RESP_SENT. La columna Variable semántica de OTEL muestra el nombre de la convención semántica de OpenTelemetry que se usa cuando spanSemantics se establece en OTEL. La columna Atributo muestra el nombre del atributo heredado.

Variable heredada Variable semántica de OTEL Atributo Descripción
API_PROXY_REVISION gcp.apigee.proxy.revision apiproxy.revision Número de revisión del proxy de API que controló la solicitud.
APIPROXY_NAME gcp.apigee.proxy.name apiproxy.name Nombre del proxy de API que controló la solicitud.
CLIENT_RECEIVED_END_TIMESTAMP gcp.apigee.client.received_end_timestamp client.received.end.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy terminó de recibir la solicitud del cliente.
CLIENT_RECEIVED_START_TIMESTAMP gcp.apigee.client.received_start_timestamp client.received.start.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy comenzó a recibir la solicitud del cliente.
CLIENT_SENT_END_TIMESTAMP gcp.apigee.client.sent_end_timestamp client.sent.end.timestamp Es la marca de tiempo (milisegundos de época) en la que el proxy terminó de enviar la respuesta al cliente.
CLIENT_SENT_START_TIMESTAMP gcp.apigee.client.sent_start_timestamp client.sent.start.timestamp Marca de tiempo (milisegundos de época) en la que el proxy comenzó a enviar la respuesta al cliente.
ENVIRONMENT_NAME gcp.apigee.environment environment.name Nombre del entorno de Apigee en el que se ejecutó el proxy.
FAULT_SOURCE gcp.apigee.fault_source message.header.X-Apigee-fault-source Es la fuente de la falla cuando se produce un error durante la ejecución del proxy. Se propaga solo en los flujos de errores.
IS_ERROR gcp.apigee.is_error is.error Es un valor booleano que indica si la ejecución del proxy finalizó en un flujo de errores.
MESSAGE_ID gcp.apigee.message.id message.id Es el identificador único que Apigee asigna a la solicitud y que resulta útil para correlacionar registros y tramos de seguimiento.
MESSAGE_STATUS_CODE http.response.status_code message.status.code Es el código de estado de la respuesta final, incluso para las llamadas sin objetivos y para los flujos de errores.
PROXY_BASE_PATH http.route proxy.basepath Es la ruta base del proxy de API que coincidió con la solicitud entrante.
PROXY_CLIENT_IP client.address proxy.client.ip Dirección IP del cliente que envió la solicitud al proxy.
PROXY_NAME gcp.apigee.proxy.name proxy.name Nombre del extremo de proxy dentro del proxy de API que controló la solicitud.
PROXY_PATH_SUFFIX url.path proxy.pathsuffix Es la parte de la ruta de URL de la solicitud que sigue a la ruta base del proxy.
PROXY_URL url.full proxy.url Es la URL completa del extremo del proxy tal como se recibió del cliente.

Sistemas de seguimiento distribuido compatibles

Puedes configurar tu entorno de ejecución de Apigee para que envíe datos de seguimiento a los siguientes sistemas de seguimiento distribuido:

Sistemas de seguimiento distribuido Descripción
Cloud Trace con OpenTelemetry

Es ideal para los usuarios que desean una configuración simple con OpenTelemetry y cuyo backend de seguimiento principal o único es Cloud Trace.

Para enviar datos de seguimiento a Cloud Trace con OpenTelemetry, haz lo siguiente:

  1. Configura el entorno de ejecución de Apigee para Cloud Trace.
  2. Habilita el seguimiento distribuido para Cloud Trace con OpenTelemetry.
OpenTelemetry Collector

Administra tu propio recopilador de OpenTelemetry para controlar la recopilación y el procesamiento de datos de seguimiento. Esto es ideal si necesitas enviar datos a varios sistemas (incluidos los que no son de Google) o personalizar la forma en que se procesan, agrupan o mejoran los datos.

Para enviar datos de seguimiento a un recopilador de OpenTelemetry, haz lo siguiente:

  1. Implementa y administra un recopilador de OpenTelemetry, como se describe en Recopilador de OpenTelemetry.
  2. Habilita el seguimiento distribuido para un recopilador de OpenTelemetry.

Consulta Consideraciones para usar un recopilador de OpenTelemetry para conocer los requisitos de alcance de la red, TLS y transporte que debes cumplir antes de habilitar esta opción.
Cloud Trace con OpenCensus

Para enviar datos de seguimiento a Cloud Trace con OpenCensus, haz lo siguiente:

  1. Configura el entorno de ejecución de Apigee para Cloud Trace (OpenCensus).
  2. Habilita el seguimiento distribuido para Cloud Trace con OpenCensus.
Jaeger con OpenCensus

Para enviar datos de seguimiento a Jaeger con OpenCensus, habilita el seguimiento distribuido para Jaeger.

Variables de entorno

En los procedimientos de esta página, se usan las siguientes variables de entorno. Te recomendamos que los configures en tu entorno antes de comenzar.

TOKEN="Authorization: Bearer $(gcloud auth application-default 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 .

Configura el entorno de ejecución de Apigee para OpenTelemetry o OpenCensus

El entorno de ejecución de Apigee admite dos estándares de seguimiento: OpenTelemetry (recomendado para implementaciones nuevas) y OpenCensus. Elige el estándar de registro que sea adecuado para tu entorno y, luego, sigue los pasos de configuración correspondientes en la siguiente sección.

En el caso de OpenTelemetry, el entorno de ejecución de Apigee reconoce el formato del encabezado de contexto de seguimiento W3C, incluidos los encabezados traceparent, tracestate y baggage.

Configura los requisitos previos para Cloud Trace (OpenTelemetry)

El entorno de ejecución de Apigee (ApigeeX) admite el seguimiento distribuido con Cloud Trace y OpenTelemetry. Si usas un recopilador de OpenTelemetry administrado por el cliente, puedes omitir esta sección y continuar con Habilita el seguimiento distribuido para un recopilador de OpenTelemetry.

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

Para configurar tu entorno de ejecución de Apigee para Cloud Trace, tu proyecto Google Cloud debe tener habilitadas las siguientes APIs:

Si habilitas estas APIs, tu proyecto de Google Cloud podrá recibir datos de seguimiento a través de OpenTelemetry desde fuentes autenticadas.

Para habilitar las API, sigue estos pasos:

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

    Ir a API y Services.

  2. Haz clic en Habilitar APIs y servicios para abrir la Biblioteca de APIs.
  3. En la Biblioteca de APIs, habilita la API de Cloud Trace, la API de Telemetry y la API de Service Usage. Puedes encontrar cada API buscándola por su nombre (por ejemplo, Telemetry API) en la barra de búsqueda de la biblioteca de APIs.

Además de habilitar las APIs, debes otorgar los siguientes roles a la cuenta del agente de servicio:

  • roles/telemetry.tracesWriter
  • roles/serviceusage.serviceUsageConsumer

La cuenta de servicio específica depende de tu entorno de Apigee:

  • ApigeeX (no híbrido): Otorga los roles al agente de servicio de Apigee, una P4SA (cuenta de servicio por producto y por proyecto) administrada por Google que Apigee aprovisiona automáticamente para el proyecto. La cuenta del agente de servicio tiene el formato service-PROJECT_NUMBER@gcp-sa-apigee..

Consulta Otorga un rol de IAM con la consola de Google Cloud .

Habilita el seguimiento distribuido (OpenTelemetry)

Antes de habilitar el seguimiento distribuido, crea las variables de entorno necesarias.

Habilita el seguimiento distribuido para Cloud Trace

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

  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":"OPEN_TELEMETRY_CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

    El cuerpo de la solicitud de ejemplo consta de los siguientes elementos:

    • Para admitir Cloud Trace con OpenTelemetry, el parámetro exporter se establece en OPEN_TELEMETRY_CLOUD_TRACE y el parámetro traceProtocol se establece en OTLP.
    • El valor de samplingRate se establece en 0.05. Esto significa que aproximadamente el 5% de las llamadas a la API se envían para el seguimiento distribuido. En el caso de OpenTelemetry, puedes especificar una tasa de muestreo de hasta 1.0 (100%). Para obtener más información, consulta Consideraciones sobre el rendimiento.
    • El parámetro endpoint se establece en el ID del proyecto Google Cloud que debe recibir los datos de seguimiento (una cadena de ID del proyecto sin formato, no una URL).
    • El parámetro spanSemantics es opcional y controla los nombres de los atributos y los intervalos que se usan en los intervalos emitidos. Valores admitidos:
      • LEGACY (predeterminado): Usa los nombres históricos de atributos y tramos de Apigee que se muestran en la columna Atributo de las tablas de variables.
      • OTEL: Usa los nombres de las convenciones semánticas de OpenTelemetry que se muestran en la columna Variable semántica de OTEL. Requiere que traceProtocol sea OTLP.

    Una respuesta correcta es similar a la siguiente:

    {
  "exporter": "OPEN_TELEMETRY_CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}

Habilita el seguimiento distribuido para un recopilador de OpenTelemetry

Para habilitar el seguimiento distribuido para un recopilador de OpenTelemetry administrado por el cliente, 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":"OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

El cuerpo de la solicitud de ejemplo consta de los siguientes elementos:

  • Para admitir un recopilador de OpenTelemetry administrado por el cliente, el parámetro exporter se establece en OPEN_TELEMETRY_COLLECTOR y el parámetro traceProtocol se establece en OTLP.
  • El parámetro endpoint se establece en la URL completa de HTTP/HTTPS del extremo de transferencia de OTLP de tu OpenTelemetry Collector (por ejemplo, http://my-otel-collector.example.com:4318/v1/traces). A diferencia del exportador de Cloud Trace, que toma un ID de proyecto Google Cloud sin formato, el exportador de OPEN_TELEMETRY_COLLECTOR requiere una URL completa que incluya el esquema, el host, el puerto y la ruta de acceso. A diferencia del extremo de Cloud Trace, el recopilador de OpenTelemetry endpoint es mutable: puedes volver a configurarlo más adelante con otro PATCH para traceConfig.
  • El valor de samplingRate se establece en 0.05. Esto significa que aproximadamente el 5% de las llamadas a la API se envían para el seguimiento distribuido. Para obtener más información, consulta Consideraciones sobre el rendimiento.
  • El parámetro otelCollectorSecurityScheme es opcional y, de forma predeterminada, se establece en NONE. Establécelo en MTLS para habilitar TLS mutua entre Apigee y el recopilador. Consulta Configura mTLS para un recopilador de OpenTelemetry para conocer los campos mtlsConfig obligatorios y el cuerpo completo de la solicitud a la API.

Una respuesta correcta es similar a la siguiente:

{
  "exporter": "OPEN_TELEMETRY_COLLECTOR",
  "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}

Consideraciones para usar un recopilador de OpenTelemetry

Antes de habilitar el registro de seguimiento distribuido en un Collector de OpenTelemetry administrado por el cliente, revisa los siguientes requisitos.

Accesibilidad de la red

  • Asegúrate de que Apigee pueda acceder al recopilador de OpenTelemetry.
  • Para llegar a un recopilador que no está expuesto en la Internet pública, usa Private Service Connect (PSC).
  • Si hay un proxy de reenvío en tu configuración, configúralo en el recopilador de OpenTelemetry. Las conexiones del procesador de mensajes al recopilador de OpenTelemetry siempre son directas.

Protocolo de transporte

Solo se admite el transporte OTLP/HTTP para los recopiladores de OpenTelemetry (puerto 4318 y ruta de acceso /v1/traces según la convención de OTLP). No se admite OTLP/gRPC (puerto 4317).

TLS y mTLS

Apigee admite dos esquemas de seguridad para la conexión a un recopilador de OpenTelemetry, que se configuran a través de otelCollectorSecurityScheme en traceConfig:

  • Sin seguridad (HTTP) (NONE, predeterminado): Apigee se conecta al recopilador a través de HTTP sin TLS mutua.
  • mTLS (MTLS): TLS mutua, por lo que el recopilador también puede autenticar Apigee como cliente. Para habilitar mTLS, configura otelCollectorSecurityScheme como MTLS en traceConfig y proporciona un mtlsConfig que haga referencia a los almacenes de claves y los almacenes de confianza administrados por Apigee. Consulta Configura mTLS para un recopilador de OpenTelemetry para ver la configuración de extremo a extremo.

Configura mTLS para un recopilador de OpenTelemetry

La TLS mutua (mTLS) permite que tu OpenTelemetry Collector autentique el entorno de ejecución de Apigee como cliente, además de que Apigee valide el certificado del servidor del recopilador.

Antes de configurar mTLS, verifica los siguientes requisitos previos:

  • Tu recopilador está configurado para requerir la autenticación de certificados de cliente (por ejemplo, el parámetro de configuración tls.client_ca_file del recopilador de OpenTelemetry) y se implementa con un archivo de autoridad certificadora (CA) que contiene la cadena de certificados que subiste en el paso 1 de la configuración.
  • endpoint usa el esquema https://.
  • El exporter es OPEN_TELEMETRY_COLLECTOR y el traceProtocol es OTLP. La mTLS no se aplica al exportador de OPEN_TELEMETRY_CLOUD_TRACE, que se autentica con Google Cloud OAuth en su lugar.

Paso 1: Sube la clave y el certificado del cliente

Crea un almacén de claves para el certificado de cliente de Apigee con el que se autentica el recopilador y, luego, sube la clave y el certificado como un alias:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases?alias=mp-client&format=keycertfile" \
    -X POST \
    -F "keyFile=@client.key" \
    -F "certFile=@client.crt"

El archivo client.crt debe estar firmado por una autoridad certificadora en la que confíe el tls.client_ca_file del recopilador. Para una configuración autofirmada, client.crt puede ser el mismo archivo que el recopilador usa como su client_ca_file.

Paso 2: Sube el certificado del servidor del recopilador

Crea un almacén de confianza que el entorno de ejecución de Apigee use para validar el certificado del servidor del recopilador y, luego, sube el certificado de la CA del recopilador como un alias de CERT:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls-truststore" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls-truststore/aliases?alias=server-ca&format=keycertfile" \
    -X POST \
    -F "certFile=@server-ca.pem"

Paso 3: Habilita la mTLS en traceConfig

Aplica el parche a traceConfig para establecer el esquema de seguridad en MTLS y hacer referencia al almacén de claves y al almacén de certificados de confianza que acabas de crear:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter": "OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL",
          "otelCollectorSecurityScheme": "MTLS",
          "mtlsConfig": {
            "keyStore":   "otel-mtls",
            "keyAlias":   "mp-client",
            "trustStore": "otel-mtls-truststore"
          }
        }'

El objeto mtlsConfig tiene tres campos obligatorios:

  • keyStore: Es el nombre del almacén de claves que contiene la clave y el certificado del cliente de Apigee del paso 1 (por ejemplo, otel-mtls). Para usar una referencia de Apigee, especifica ref://REFERENCE_NAME.
  • keyAlias: Es el nombre del alias KEY_CERT dentro de keyStore (por ejemplo, mp-client).
  • trustStore: Es el nombre del almacén de claves que contiene el certificado de la AC del servidor del recopilador del paso 2 (por ejemplo, otel-mtls-truststore). Para usar una referencia de Apigee, especifica ref://REFERENCE_NAME.

Apigee aplica la siguiente validación en traceConfig cuando otelCollectorSecurityScheme es MTLS:

  • exporter debe ser OPEN_TELEMETRY_COLLECTOR
  • traceProtocol debe ser OTLP
  • endpoint debe usar el esquema https://.
  • Se deben completar los tres campos de mtlsConfig. Si falta algún campo, se devuelve el error HTTP 400.
  • Los almacenes de claves, los alias y las referencias a los que se hace referencia ya deben existir. Los recursos faltantes devuelven el error HTTP 400.

Rota la clave o el certificado del cliente

Para rotar la clave o el certificado del cliente sin un cambio en traceConfig, sube el nuevo material de la clave al alias mp-client existente con un PUT:

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases/mp-client" \
    -X PUT \
    -F "keyFile=@client-v2.key" \
    -F "certFile=@client-v2.crt"

El entorno de ejecución de Apigee detecta el cambio de alias y revisión en su próxima sincronización de configuración y vuelve a compilar el exportador de OTLP de mTLS con las nuevas credenciales. No es necesario reiniciar el pod ni se descartan las solicitudes en curso.

Criterios de muestreo

El tiempo de ejecución de Apigee decide si se debe registrar un seguimiento para cada solicitud combinando los encabezados de solicitud entrantes con la configuración de seguimiento del entorno.

Encabezado de contexto de seguimiento de W3C

En la configuración de OpenTelemetry, el tiempo de ejecución respeta el encabezado contexto de seguimiento W3C traceparent. El último byte de traceparent (el byte trace-flags) contiene la marca sampled: un valor de 01 indica que el llamador ya decidió registrar el registro, y 00 indica que no lo hizo.

Las recomendaciones para la marca de muestreo de la especificación de contexto de seguimiento de W3C indican que un componente debe respetar la marca de muestreo entrante cuando toma una decisión de grabación y reflejar una decisión de grabación definitiva en la marca. Apigee sigue estas recomendaciones: respeta la marca de muestreo entrante cuando decide si registrar un seguimiento (consulta Precedencia del encabezado sobre la configuración local) y establece la marca de muestreo en el encabezado traceparent que propaga a los servicios descendentes para reflejar si se está registrando la solicitud. Como control de seguridad contra el registro no deseado impulsado por la marca entrante, establece sampler en OFF (consulta Cómo inhabilitar la configuración del registro distribuido), lo que inhabilita el registro incluso para las solicitudes cuyo traceparent tenga establecida la marca de muestreo.

Precedencia del encabezado sobre la configuración local

Cuando una solicitud entrante incluye un encabezado traceparent, el entorno de ejecución de Apigee usa la marca de muestreo de ese encabezado en lugar de su samplingConfig local. Una solicitud con la marca de muestreo establecida en 01 siempre se rastrea; una solicitud con la marca establecida en 00 no se rastrea. El samplingConfig a nivel del entorno solo se aplica a las solicitudes que llegan sin un encabezado traceparent.

Cómo inhabilitar el registro

Para inhabilitar el registro de seguimiento para cada proxy en un entorno (excluye las anulaciones de proxy), establece sampler en OFF en el traceConfig del entorno. Consulta Inhabilita la configuración de seguimiento distribuido.

Anulaciones por proxy

Para habilitar el registro de seguimiento solo para un subconjunto de proxies en un entorno, deja el entorno samplingConfig con sampler establecido en OFF y crea una anulación por proxy (con sampler establecido en PROBABILITY y un samplingRate distinto de cero) para cada proxy del que desees realizar un seguimiento. Consulta Anula la configuración de seguimiento para proxies de API.

Impacto en el rendimiento de la tasa de muestreo

El samplingRate que configures afectará directamente el rendimiento del tiempo de ejecución. Cada solicitud muestreada genera trabajo adicional de CPU en el procesador de mensajes (generación y exportación de intervalos) y agrega latencia a la ruta de la solicitud. A medida que aumenta la frecuencia de muestreo, también lo hace el volumen de tráfico rastreado por MP, lo que puede reducir la capacidad de procesamiento y aumentar la latencia de cola (p95, p99). El impacto aumenta con el volumen de tráfico: con tasas de solicitudes bajas, la sobrecarga suele ser insignificante, mientras que, con tasas de solicitudes altas, una tasa de muestreo alta puede reducir significativamente la capacidad de procesamiento sostenible y requerir capacidad adicional de MP. En las comparativas internas, la ejecución en samplingRate=1.0 (muestreo del 100%) con tráfico intenso sostenido redujo la capacidad de procesamiento en hasta un 15% aproximadamente en comparación con la ejecución con el registro de seguimiento inhabilitado.

Como regla general, mantén samplingRate bajo (por ejemplo, 0.1 o menos) en producción y auméntalo solo para proxies específicos a través de invalidaciones por proxy cuando necesites una visibilidad más profunda. Para obtener un desglose detallado del impacto esperado y la orientación sobre la capacidad, consulta Consideraciones sobre el rendimiento.

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 depende de la complejidad del proxy de API (por ejemplo, la cantidad de políticas), la tasa de muestreo probabilística (establecida como samplingRate) y, lo que es más importante, del volumen de tráfico rastreado en relación con la capacidad de exportación de intervalos por procesador de mensajes (MP).

El MP de Apigee tiene una tasa de exportación de tramos finita. Con la configuración predeterminada, un solo MP puede exportar de forma sostenible aproximadamente 820 intervalos por segundo. Una ejecución típica de proxy de API emite aproximadamente 10 intervalos (preflujo del proxy, flujo de destino, posflujos, políticas adjuntas), por lo que un solo MP puede hacer un seguimiento sostenible de aproximadamente 82 solicitudes por segundo con un muestreo del 100%. El aumento del recuento de réplicas de MP incrementa el límite agregado de forma lineal.

En la siguiente tabla, se resume el impacto esperado en samplingRate=1.0 (probabilidad del 100%) en dos regímenes de tráfico:

Régimen de tráfico (por MP) Impacto esperado a las samplingRate=1.0 Acción recomendada
Poco tráfico (menos de 82 solicitudes registradas por segundo por MP, aproximadamente) La capacidad de procesamiento disminuye en aproximadamente un 1 o 2%; la latencia media aumenta en aproximadamente un 1%; la latencia p99 aumenta en aproximadamente un 15 o 20%. Es insignificante en la práctica. Es seguro habilitar el 100%.
Mucho tráfico (significativamente superior a aproximadamente 82 solicitudes rastreadas por segundo por MP) La capacidad de procesamiento disminuye en aproximadamente un 14%; la latencia media aumenta en aproximadamente un 24%; la latencia del percentil 75 aumenta en aproximadamente un 52%, y la tasa de error aumenta en aproximadamente 1 punto porcentual. Puedes reducir samplingRate (por ejemplo, a 0.1 o 0.05) o aumentar la cantidad de réplicas de tu MP para que cada MP procese menos solicitudes rastreadas por segundo.

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 a través de anulaciones por proxy.

Configura los entornos de ejecución de Apigee para Cloud Trace (OpenCensus)

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

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

Para configurar tu entorno de ejecución de Apigee para Cloud Trace, tu proyecto Google Cloud debe tener habilitada la API de Cloud Trace.

Para habilitar la API, haz lo siguiente:

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

    Ir a API y Services.

  2. Haz clic en Habilitar APIs y servicios.
  3. Habilita la API de Cloud Trace.

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

Para configurar el entorno de ejecución de Apigee Hybrid para Cloud Trace, habilita la API de Cloud Trace.

Además de habilitar la API, debes agregar la cuenta de servicio para usar Cloud Trace con el entorno de ejecución híbrido. Para agregar la cuenta de servicio, junto con el rol y las claves roles/cloudtrace.agent requeridos, sigue estos pasos:

  1. Cree una cuenta de servicio nueva: 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. 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." \
    --role=roles/cloudtrace.agent --project PROJECT_ID
  3. Crea una clave de cuenta de servicio y actualiza tu overrides.yaml como se describe en los siguientes pasos.
  4. 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.
  5. 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
  6. Aplica los cambios al entorno de ejecución con Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Habilita el seguimiento distribuido (OpenCensus)

Antes de habilitar el seguimiento distribuido, crea las variables de entorno necesarias.

Habilita el seguimiento distribuido para Cloud Trace con OpenCensus

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

  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:

    • Para admitir Cloud Trace, el parámetro exporter se establece en CLOUD_TRACE. El parámetro traceProtocol, que no se especifica, se establece en OpenCensus de forma predeterminada.
    • El parámetro endpoint se establece en el proyecto Google Cloud al que deseas que se envíe el registro.
    • 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. En el caso de OpenCensus, la tasa de muestreo máxima configurable es 0.5.

    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 con OpenCensus

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:

  • Para admitir Jaeger, el parámetro exporter se establece en JAEGER. El parámetro traceProtocol, que no se especifica, se establece en OpenCensus de forma predeterminada.
  • El parámetro endpoint se establece en el lugar en el que Jaeger está instalado y configurado.
  • 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.

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.

Para obtener más información, consulta Consideraciones sobre el rendimiento.

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": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  },
  "revisionId": "7",
  "updateTime": "2026-06-08T14:25:13.512000Z"
}

El valor de revisionId aumenta con cada actualización correcta, y updateTime refleja la marca de tiempo del servidor del cambio más reciente. Usa estos dos campos para confirmar que el plano de control aceptó una actualización de configuración. Ambos también se muestran en la respuesta de PATCH .../traceConfig.

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 -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.6}
        }'

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

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}
 En este ejemplo, la tasa de muestreo se actualiza a 0.6.

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 '{
          "samplingConfig": {"sampler": "OFF"}
        }'

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

{
  "samplingConfig": {
    "sampler": "OFF"
  },
  "traceProtocol": "OTLP"
}

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:

  1. 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
      }
    }
  ]
}
  2. 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:

  1. 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
      }
    }
  ]
}
  2. 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 \

Soluciona problemas del seguimiento distribuido

Para solucionar problemas relacionados con el registro de seguimiento distribuido, haz lo siguiente:

  • Verifica la configuración del seguimiento distribuido con la API de traceConfig para asegurarte de que coincida con tus necesidades.
  • Confirma que la cuenta de servicio tenga los permisos de IAM (roles) correctos en el proyecto de destino.
  • Si usas Cloud Trace con OpenTelemetry, verifica si hay intervalos entrantes y errores de habilitación de la API o de cuota.
  • Si usas un recopilador de OpenTelemetry administrado por el cliente, haz lo siguiente:
    • Confirma que Apigee pueda acceder al extremo del recopilador. Verifica la configuración de Private Service Connect (PSC) si se usa.
    • Revisa los registros del recopilador de OpenTelemetry para detectar problemas de datos o de conexión.
    • Asegúrate de que el certificado TLS del recopilador sea válido.
  • Examina los registros del entorno de ejecución de Apigee en busca de errores de exportación de seguimiento.