Contexto do trace

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 de rastreamento e o ID do o período que está sendo processado precisa ser passado para operações filhas.

As operações filhas criam um período e definem os seguintes campos:

  • ID da extensão: um identificador exclusivo da operação filha. Se a mesma operação for executada várias vezes, haverá vários spans para essa operação, cada um com um identificador exclusivo.
  • ID do trace: o identificador exclusivo da operação completa na qual este uma determinada operação geral. O valor desse campo é fornecido pelo pai.
  • ID do período pai: o identificador exclusivo do período do pai. O valor deste campo é fornecido pelo pai. Para períodos raiz, esse ID é null.

Os valores dos campos "ID do trace", "ID do período" e "ID do período pai" permitem que uma o sistema de rastreamento distribuído liga os períodos corretamente 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 e propagar 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 a usar o X-Cloud-Trace-Context como uma solução substituta.

A tabela a seguir resume algumas diferenças significativas entre os dois cabeçalhos:

Atributo traceparentCabeçalho
X-Cloud-Trace-Context
header
Separadores hífens (-) 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 do período não assinado.
  • OPTIONS é compatível com 0 (o elemento pai não foi de amostra) e 1 (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 seus componentes, recomendamos usar o 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 no processamento de solicitações. Por exemplo, os serviços a seguir são conhecidos por participar processando solicitações:

O suporte para iniciação e propagação de contexto de trace é de acordo com o 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 apps

Algumas bibliotecas de instrumentação, como OpenTelemetry, propagar automaticamente um objeto context que contenha os dados necessários para rastreamento. Se você usar esses tipos de bibliotecas, os períodos geradas pelo aplicativo estão configuradas corretamente. Para uma lista de Bibliotecas do OpenTelemetry compatíveis com rastreamento, consulte APIs de linguagem e SDKs do Terraform. Para uma instrumentação exemplo, 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, você precisa garantir que seu aplicativo seja propagado o contexto de trace para operações filhas.

A seguir