En este documento, se describe brevemente el contexto, que hace referencia al estado, y a la propagación del contexto, que hace referencia 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 procesa deben pasarse a las operaciones secundarias.
Las operaciones secundarias crean un intervalo y establecen los siguientes campos:
- ID de intervalo: 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 se llevó a cabo esta operación general en particular. El elemento superior proporciona el valor de este campo.
- ID de intervalo principal: Es el identificador único del intervalo superior.
El elemento superior proporciona el valor de este campo.
Para los intervalos raíz, este ID es
null
.
Los valores de los campos de ID de seguimiento, ID de intervalo y superior ID de intervalo permiten que un sistema de seguimiento distribuido vincule de forma correcta 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 el intervalo superior se muestreó.
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 generalmente se logra a través de encabezados HTTP, como los encabezados traceparent
y tracestate
, que W3C estandarizó.
Los servicios de Google Cloud que admiten la propagación del contexto de seguimiento suelen admitir el traceparent
y el encabezado X-Cloud-Trace-Context
heredado.
Cuando sea posible, te recomendamos que uses el encabezado traceparent
en tus aplicaciones. Es posible que tu aplicación necesite usar el encabezado X-Cloud-Trace-Context
heredado 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 actualices tu aplicación para admitir el encabezado traceparent
y priorizarlo. La aplicación puede seguir usando el encabezado X-Cloud-Trace-Context
como solución de resguardo.
En la siguiente tabla, se resumen algunas diferencias significativas entre los dos encabezados:
Atributo | traceparent Encabezado |
Encabezado X-Cloud-Trace-Context |
---|---|---|
Separadores | guiones (-) |
barra diagonal (/) y punto y coma (;) |
Representación de 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 W3C.
Para la retrocompatibilidad, algunos servicios de Google Cloud continúan 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 de 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
admite0
(el elemento superior no se muestreó) y1
(el elemento superior se muestreó).
Solicitudes de gRPC
Para las solicitudes gRPC, la propagación del contexto se logra mediante metadatos de gRPC, que se implementa 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 de tu propiedad, te recomendamos que uses el encabezado traceparent
.
Propagación del contexto para los servicios de Google Cloud
Los servicios de Google 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:
- Apigee
- App Engine
- Cloud Endpoints
- Cloud Functions
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
La asistencia para la iniciación y propagación del contexto de seguimiento depende del servicio específico de Google Cloud. Si deseas 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, propagan automáticamente un objeto context
que contiene los datos necesarios para el seguimiento. Si usas este tipo de bibliotecas, los intervalos que genera tu aplicación están configurados correctamente. Para obtener una lista de las bibliotecas de OpenTelemetry que admiten el seguimiento, consulta APIs y SDKs de lenguaje. Para ver un ejemplo de instrumentación, consulta Genera seguimientos y métricas con Go.
Si dependes de una biblioteca de código abierto, determina si la propagación de contexto está disponible y si se requiere configuración.
Cuando no haya una biblioteca de instrumentación adecuada, debes asegurarte de que tu aplicación propague el contexto de seguimiento a las operaciones secundarias.
¿Qué sigue?
Obtén información sobre el muestreo de seguimiento.
Recursos de OpenTelemetry: