Contexto de traza

En este documento se describe brevemente el contexto, que hace referencia al estado, y la propagación del contexto, que hace referencia a la transferencia de información de estado a operaciones secundarias. En el caso del rastreo distribuido, el ID de rastreo y el ID del intervalo que se está procesando deben enviarse a las operaciones secundarias.

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

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

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

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

Protocolos para la propagación del contexto

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

Solicitudes HTTP

En las solicitudes HTTP, la propagación del contexto se suele llevar a cabo mediante encabezados HTTP, como los encabezados traceparent y tracestate, que estandarizó el W3C. Los serviciosGoogle Cloud que admiten la propagación del contexto de rastreo suelen admitir tanto el encabezado traceparent como el encabezado X-Cloud-Trace-Context antiguo.

Cuando sea posible, te recomendamos que utilices el encabezado traceparent en tus aplicaciones. Es posible que tu aplicación tenga que usar el encabezado X-Cloud-Trace-Context antiguo o que tenga que admitir la recepción del contexto de rastreo en otro formato.

Si tienes una aplicación que solo admite el encabezado X-Cloud-Trace-Context , te recomendamos que la actualices para que admita y dé prioridad al 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
 X-Cloud-Trace-Context
encabezado
Separadores guiones (-) barra inclinada (/) y punto y coma (;)
Representación de Span ID
 Hexadecimal Decimal

Encabezado X-Cloud-Trace-Context antiguo

El encabezado X-Cloud-Trace-Context que usa Google Cloud es anterior a la especificación del W3C. Para mantener la compatibilidad con versiones anteriores, 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 de intervalo sin signo.
  • OPTIONS admite 0 (no se ha tomado una muestra del elemento superior) y 1 (se ha tomado una muestra del elemento superior).

Solicitudes gRPC

En 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.

En el caso de 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 iniciación y la propagación del contexto de rastreo depende del Google Cloud servicio concreto. Para solicitar que un Google Cloud servicio añada compatibilidad con la propagación de contexto, usa Google Issue Tracker.

Propagación del contexto en tus aplicaciones

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

Si utilizas una biblioteca de código abierto, determina si la propagación de contexto está disponible y si es necesario configurarla. Por ejemplo, si usas OpenTelemetry para instrumentar una aplicación Go, tu aplicación debería llamar a SetTextMapPropagator, que configura el contexto para usar el formato traceparent de W3C. Para ver un ejemplo, consulta Instrumentación de Go de muestra.

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

Siguientes pasos