Neste documento, há uma breve descrição de contexto, que se refere ao estado. à propagação de contexto, que se refere à transmissão de informações de estado para operações filhas. Para o rastreamento distribuído, o ID do rastreamento e o ID do intervalo que está sendo processado precisam ser transmitidos para as operações filhas.
As operações filhas criam um período e definem os seguintes campos:
- ID do período: um identificador exclusivo para a operação filha. Se a mesma operação for executada várias vezes, não haverá vários períodos para essa operação, cada um com um identificador exclusivo.
- ID do rastreamento: o identificador exclusivo da operação completa em que essa operação geral específica ocorreu. O valor desse campo é fornecido pelo pai.
- ID do período pai: o identificador exclusivo do período do pai.
O valor desse campo é fornecido pelo pai.
Para períodos raiz, esse ID é
null
.
Os valores dos campos de ID do trace, ID da extensão e ID da extensão pai permitem que um sistema de rastreamento distribuído vincule corretamente as extensões para formar um trace. Por exemplo, o Cloud Trace armazena períodos em um repositório e usa esses Campos de ID para identificar quais períodos compõem um trace.
O contexto pode incluir outras informações de estado úteis para o rastreamento de dados. Por exemplo, o padrão do World Wide Web Consortium (W3C) inclui informações sobre se o período pai foi amostrado.
Protocolos para propagação de contexto
As seções a seguir descrevem como protocolos de solicitação específicos propagam o contexto.
Solicitações HTTP
Para solicitações HTTP, a propagação de contexto é normalmente realizada por meio de
cabeçalhos HTTP, como traceparent
e tracestate
, que foram
padronizado pelo W3C.
Os serviços do Google Cloud com suporte à propagação de contexto de trace geralmente têm suporte
o traceparent
e o cabeçalho X-Cloud-Trace-Context
legado.
Sempre que possível, recomendamos que você use o
cabeçalho traceparent
nos aplicativos. Seu
o aplicativo pode precisar usar o cabeçalho X-Cloud-Trace-Context
legado ou ele
pode precisar oferecer suporte ao recebimento do contexto de rastreamento em um formato diferente.
Se você tiver um aplicativo que só oferece suporte aos X-Cloud-Trace-Context
cabeçalho, recomendamos que você atualize seu aplicativo para suporte e
priorizar, o cabeçalho traceparent
. Seu aplicativo pode continuar usando o
cabeçalho X-Cloud-Trace-Context
como uma solução alternativa.
A tabela a seguir resume algumas diferenças significativas entre os dois cabeçalhos:
Atributo | traceparent Cabeçalho |
X-Cloud-Trace-Context cabeçalho |
---|---|---|
Separadores | hifens (-) |
barra (/) e ponto e vírgula (;) |
Representação do ID do período |
Codificação | Decimal |
Cabeçalho X-Cloud-Trace-Context
legado
O cabeçalho X-Cloud-Trace-Context
usado pelo Google Cloud é anterior aos
especificação W3C.
Para manter a compatibilidade com versões anteriores, alguns serviços do Google Cloud continuam a aceitar,
gerar e propagar o cabeçalho X-Cloud-Trace-Context
. No entanto, é
provável que esses sistemas também ofereçam suporte ao cabeçalho traceparent
.
O cabeçalho X-Cloud-Trace-Context
tem o seguinte formato:
X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS
Os campos do cabeçalho são definidos da seguinte maneira:
TRACE_ID
é um valor hexadecimal de 32 caracteres que representa um número de 128 bits.SPAN_ID
é uma representação decimal de 64 bits do ID de período não assinado.OPTIONS
é compatível com0
(o pai não foi amostrado) e1
(o pai foi amostrado).
Solicitações gRPC
Para solicitações gRPC, a propagação de contexto é feita usando
metadados do gRPC, que é implementado em cima dos cabeçalhos HTTP.
Os aplicativos gRPC podem usar o cabeçalho traceparent
ou uma
chave de contexto de metadados chamada grpc-trace-bin
.
Para componentes que você possui, recomendamos o uso do cabeçalho traceparent
.
Propagação de contexto para serviços do Google Cloud
Os serviços do Google Cloud podem atuar como iniciadores ou intermediários na solicitação processamento. Por exemplo, os seguintes serviços participam do processamento de solicitações:
- Apigee
- App Engine
- Cloud Endpoints
- Funções do Cloud Run
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
O suporte para a iniciação e a propagação do contexto de rastreamento depende do serviço específico do Google Cloud. Para solicitar que um serviço do Google Cloud adicione suporte à propagação de contexto, use o Google Issue Tracker.
Propagação de contexto nos seus aplicativos
Algumas bibliotecas de instrumentação, como o OpenTelemetry,
propagam automaticamente um objeto context
que contém os dados necessários
para o rastreamento. Se você usar esses tipos de bibliotecas, os spans
gerados pelo aplicativo serão configurados corretamente. Para conferir uma lista de
bibliotecas do OpenTelemetry que oferecem suporte ao rastreamento, consulte
APIs e SDKs de linguagem. Para conferir um exemplo de instrumentação, consulte Gerar traces e métricas com o Go.
Se você usa uma biblioteca de código aberto, determine se a propagação de contexto está disponível e se a configuração é necessária.
Quando não há uma biblioteca de instrumentação adequada, é necessário garantir que o aplicativo propague o contexto de rastreamento para operações filhas.
A seguir
Saiba mais sobre a amostragem de traços.
Recursos do OpenTelemetry: