Contexto de rastreamento

O contexto de trace e a propagação de contexto permitem que seus aplicativos distribuídos transmitam identificadores de solicitação entre serviços em cabeçalhos ou metadados. O Cloud Trace usa esse contexto compartilhado para vincular períodos individuais a rastreamentos distribuídos completos, reconstruir hierarquias de execução e avaliar se as solicitações são amostradas.

Como a propagação de contexto funciona

Quando seu aplicativo processa uma solicitação e chama serviços downstream, ele transmite identificadores, como o ID do rastreamento, o ID do período pai e o status de amostragem, usando cabeçalhos de solicitação ou metadados. As operações filhas usam esse contexto para preencher os seguintes campos em novos intervalos:

  • ID do intervalo: um identificador exclusivo da operação secundária. Se uma operação for executada várias vezes, cada invocação vai gerar um intervalo com um ID de intervalo distinto.
  • ID do rastreamento: o identificador exclusivo da solicitação completa de ponta a ponta, fornecido pelo elemento pai.
  • ID do período principal: o identificador exclusivo do período principal de invocação. Esse campo é null para intervalos raiz.

Usando esses identificadores compartilhados, o Trace reconstrói a hierarquia de execução e mede a latência em todos os serviços participantes. O contexto também pode incluir outras informações de estado, como se uma solicitação foi amostrada.

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 geralmente é realizada por cabeçalhos HTTP, como traceparent e tracestate, que foram padronizados pelo W3C. O cabeçalho traceparent contém os identificadores para identificar exclusivamente uma solicitação. Em contraste, o cabeçalho tracestate é opcional e contém metadados específicos do fornecedor.

O cabeçalho traceparent tem o seguinte formato:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

Os campos do cabeçalho traceparent são definidos da seguinte maneira:

  • VERSION é a versão do cabeçalho. Precisa ser 00.
  • TRACE_ID é um valor hexadecimal de 32 caracteres que representa um número de 128 bits.
  • PARENT_SPAN_ID é um valor hexadecimal de 16 caracteres que identifica o período principal.
  • TRACE_FLAGS é um valor hexadecimal de dois caracteres que identifica a decisão de amostragem do elemento pai. Quando um pai faz a amostragem do intervalo, o valor é 01.

Google Cloud serviços que oferecem suporte à propagação do contexto de traces normalmente são compatíveis com o traceparent e o cabeçalho X-Cloud-Trace-Context legado.

Quando possível, use o cabeçalho traceparent nos seus aplicativos. Se um aplicativo oferecer suporte apenas ao cabeçalho X-Cloud-Trace-Context, recomendamos que você o atualize para oferecer 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 Cabeçalho traceparent
 Cabeçalho X-Cloud-Trace-Context
Separadores hifens (-) barra para a direita (/) 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 por Google Cloud é anterior à especificação do W3C. Para oferecer compatibilidade com versões anteriores, alguns serviços do Google Cloud continuam aceitando, gerando e propagando o cabeçalho X-Cloud-Trace-Context. No entanto, é provável que esses sistemas também sejam compatíveis com o 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 intervalo não assinado.
  • O OPTIONS oferece suporte a 0 (o pai não foi amostrado) e 1 (o pai foi amostrado).

Solicitações gRPC

Para solicitações gRPC, a propagação de contexto é realizada usando metadados gRPC, que são implementados sobre 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 usar o cabeçalho traceparent.

Propagação de contexto para serviços Google Cloud

Os serviços doGoogle Cloud podem atuar como iniciadores ou intermediários no processamento de solicitações. Por exemplo, os seguintes serviços participam do processamento de solicitações:

O suporte para iniciação e propagação do contexto de traces depende do serviçoGoogle Cloud específico. Para pedir que um serviço 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, podem propagar um objeto context que contém os dados necessários para o rastreamento. Para conferir uma lista de bibliotecas do OpenTelemetry que oferecem suporte ao rastreamento, consulte APIs e SDKs de linguagem.

Se você usa uma biblioteca de código aberto, determine se a propagação de contexto está disponível e se é necessário fazer alguma configuração. Por exemplo, se você usar o OpenTelemetry para instrumentar um app Go, ele vai chamar SetTextMapPropagator, que configura o contexto para usar o formato traceparent do W3C. Para ver um exemplo, consulte Exemplo de instrumentação em Go.

Quando não há uma biblioteca de instrumentação adequada, é preciso garantir que o aplicativo propague o contexto de traces para operações secundárias.

A seguir