Contexto de seguimiento

En este documento, se describe brevemente el contexto, que se refiere al estado, y la propagación del contexto, que se refiere a pasar información de estado a las operaciones secundarias. Para el seguimiento distribuido, el ID de seguimiento y el ID del intervalo que se está procesando deben pasarse a las operaciones secundarias.

Las operaciones secundarias crean un intervalo y configuran los siguientes campos:

  • ID de intervalo: Es un identificador único para la operación secundaria. Si la misma operación se ejecuta varias veces, habrá varios intervalos para esa operación, cada uno con un identificador único.
  • ID de seguimiento: Es el identificador único de la operación de extremo a extremo en la que tuvo lugar esta operación general en particular. El valor de este campo lo proporciona el elemento superior.
  • ID de intervalo superior: Es el identificador único del intervalo del elemento superior. El valor de este campo lo proporciona el elemento superior. Para los intervalos raíz, este ID es null.

Los valores de los campos de ID de seguimiento, ID de intervalo y ID de intervalo superior permiten que un sistema de seguimiento distribuido vincule correctamente los intervalos para formar un seguimiento. Por ejemplo, Cloud Trace almacena intervalos en un repositorio y usa estos campos de ID para identificar qué intervalos componen un seguimiento.

El contexto puede incluir otra información de estado que sea útil para el seguimiento distribuido. Por ejemplo, el estándar del World Wide Web Consortium (W3C) incluye información sobre si se muestreó el intervalo superior.

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. 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, te recomendamos que uses el traceparent encabezado en tus aplicaciones. Es posible que tu aplicación deba usar el encabezado heredado X-Cloud-Trace-Context o que deba admitir la recepción del contexto de seguimiento en un formato diferente.

Si tienes una aplicación que 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 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 (no se muestreó el elemento superior) y 1 (se muestreó el elemento superior).

Solicitudes gRPC

Para las solicitudes gRPC, la propagación del contexto se realiza mediante 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 es dependiente del servicio en particular 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 APIs y SDKs 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 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?