Contexto de seguimiento

El contexto de seguimiento y la propagación del contexto permiten que tus aplicaciones distribuidas pasen identificadores de solicitudes entre servicios en encabezados o metadatos. Cloud Trace usa este contexto compartido para vincular intervalos individuales en seguimientos distribuidos completos, reconstruir jerarquías de ejecución y evaluar si se muestrean las solicitudes.

Cómo funciona la propagación del contexto

Cuando tu aplicación controla una solicitud y llama a servicios descendentes, pasa identificadores (como el ID de seguimiento, el ID del intervalo principal y el estado de muestreo) a través de encabezados de solicitud o metadatos. Las operaciones secundarias usan este contexto para propagar los siguientes campos en los nuevos intervalos:

  • ID de tramo: Es un identificador único para la operación secundaria. Si una operación se ejecuta varias veces, cada invocación genera un tramo con un ID de tramo distinto.
  • ID de seguimiento: Es el identificador único de la solicitud general de extremo a extremo, proporcionado por el elemento superior.
  • ID del intervalo principal: Es el identificador único del intervalo principal de invocación. Este campo es null para los intervalos raíz.

Con estos identificadores compartidos, Trace reconstruye la jerarquía de ejecución y mide la latencia en todos los servicios participantes. El contexto también puede incluir información de estado adicional, como si se muestreó una solicitud.

Protocolos para la propagación del contexto

En las siguientes secciones, se describe cómo los protocolos de solicitud específicos propagan el contexto.

Solicitudes HTTP

En el caso de las solicitudes HTTP, la propagación del contexto suele lograrse a través de encabezados HTTP, como los encabezados traceparent y tracestate, que fueron estandarizados por el W3C. El encabezado traceparent contiene los identificadores para identificar de forma única una solicitud. Por el contrario, el encabezado tracestate es opcional y contiene metadatos específicos del proveedor.

El encabezado traceparent tiene el siguiente formato:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

Los campos del encabezado traceparent se definen de la siguiente manera:

  • VERSION es la versión del encabezado. Debe ser 00.
  • TRACE_ID es un valor hexadecimal de 32 caracteres que representa un número de 128 bits.
  • PARENT_SPAN_ID es un valor hexadecimal de 16 caracteres que identifica el intervalo principal.
  • TRACE_FLAGS es un valor hexadecimal de 2 caracteres que identifica la decisión de muestreo del elemento superior. Cuando un elemento superior muestreó el intervalo, el valor es 01.

Los servicios deGoogle Cloud que admiten la propagación del contexto de seguimiento suelen admitir tanto el encabezado traceparent como el encabezado X-Cloud-Trace-Context heredado.

Cuando sea posible, usa el encabezado traceparent en tus aplicaciones. Si una aplicación solo admite el encabezado X-Cloud-Trace-Context, te recomendamos que la actualices para que admita y priorice el encabezado traceparent. Tu aplicación puede seguir usando el encabezado X-Cloud-Trace-Context como solución alternativa.

En la siguiente tabla, se resumen algunas diferencias significativas entre los dos encabezados:

Atributo Encabezado traceparent
 Encabezado X-Cloud-Trace-Context
Separadores guiones (-) barra diagonal (/) y punto y coma (;)
Representación del ID de intervalo
 Hexadecimal Decimal

Encabezado X-Cloud-Trace-Context heredado

El encabezado X-Cloud-Trace-Context que usa Google Cloud es anterior a la especificación de W3C. Para la retrocompatibilidad, algunos servicios de Google Cloud siguen aceptando, generando y propagando el encabezado X-Cloud-Trace-Context. Sin embargo, es probable que estos sistemas también admitan el encabezado traceparent.

El encabezado X-Cloud-Trace-Context tiene el siguiente formato:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

Los campos del encabezado se definen de la siguiente manera:

  • TRACE_ID es un valor hexadecimal de 32 caracteres que representa un número de 128 bits.
  • SPAN_ID es una representación decimal de 64 bits del ID del intervalo sin firma.
  • OPTIONS admite 0 (la matriz no se muestreó) y 1 (la matriz se muestreó).

Solicitudes de gRPC

En el caso de las solicitudes de gRPC, la propagación del contexto se logra con los metadatos de gRPC, que se implementan sobre los encabezados HTTP. Las aplicaciones de gRPC pueden usar el encabezado traceparent o una clave de contexto de metadatos llamada grpc-trace-bin.

Para los componentes que te pertenecen, te recomendamos que uses el encabezado traceparent.

Propagación del contexto para los servicios de Google Cloud

Los servicios deGoogle Cloud pueden actuar como iniciadores o intermediarios en el procesamiento de solicitudes. Por ejemplo, se sabe que los siguientes servicios participan en el procesamiento de solicitudes:

La compatibilidad con la propagación y la inicialización del contexto de seguimiento depende del servicio deGoogle Cloud específico. Para solicitar que un servicio de Google Cloud agregue compatibilidad con la propagación de contexto, usa la Herramienta de seguimiento de errores de Google.

Propagación del contexto en tus aplicaciones

Algunas bibliotecas de instrumentación, como OpenTelemetry, pueden propagar un objeto context que contiene los datos necesarios para el seguimiento. Para obtener una lista de las bibliotecas de OpenTelemetry que admiten el seguimiento, consulta APIs y SDKs de lenguajes.

Si dependes de una biblioteca de código abierto, determina si la propagación del contexto está disponible y si se requiere configuración. Por ejemplo, si usas OpenTelemetry para instrumentar una app en Go, esta debe llamar a SetTextMapPropagator, que configura el contexto para usar el formato traceparent de W3C. Para ver un ejemplo, consulta Ejemplo de instrumentación de Go.

Cuando no hay una biblioteca de instrumentación adecuada, debes asegurarte de que tu aplicación propague el contexto de seguimiento a las operaciones secundarias.

¿Qué sigue?