Contexto de seguimiento

El contexto de seguimiento y la propagación del contexto son los mecanismos que se usan para pasar metadatos entre operaciones y servicios, de modo que Cloud Trace pueda vincular intervalos individuales en un seguimiento distribuido completo de extremo a extremo.

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

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

Con estos identificadores compartidos, Cloud 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

Para las solicitudes HTTP, la propagación del contexto suele realizarse a través de encabezados HTTP, como los encabezados traceparent y tracestate, que fueron estandarizados por 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 superior.
  • 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.

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

Cuando sea posible, usa el traceparent encabezado en tus aplicaciones. Si una aplicación solo admite el encabezado X-Cloud-Trace-Context, te recomendamos que la actualices para admitir y priorizar 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 traceparent
encabezado		 X-Cloud-Trace-Context
encabezado
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 Google Cloud servicios siguen aceptando, generando y propagando el X-Cloud-Trace-Context encabezado. 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 de intervalo sin firma.
  • OPTIONS admite 0 (elemento superior no muestreado) y 1 (elemento superior muestreado).

Solicitudes gRPC

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

Para los componentes que son de tu propiedad, te recomendamos que uses el encabezado traceparent.

Propagación del contexto para Google Cloud servicios

Google Cloud Los servicios 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 el inicio y la propagación del contexto de seguimiento depende del servicio específico Google Cloud Para solicitar que un Google Cloud servicio agregue compatibilidad con la propagación del 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 SDK y APIs de lenguaje.

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 de Go, tu app debe llamar a SetTextMapPropagator, que configura el contexto para usar el formato traceparent de W3C. Para ver un ejemplo, consulta la muestra 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?