Contexto de rastreamento

O contexto de trace e a propagação de contexto são os mecanismos usados para transmitir metadados entre operações e serviços para que o Cloud Trace possa vincular períodos individuais em um trace distribuído completo de ponta a ponta.

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

  • ID do período: um identificador exclusivo para a operação filha. Se uma operação for executada várias vezes, cada invocação vai gerar um período com um ID de período diferente.
  • ID do trace: o identificador exclusivo da solicitação geral de ponta a ponta, fornecido pelo pai.
  • ID do período pai: o identificador exclusivo do período pai de invocação. Esse campo é null para períodos raiz.

Usando esses identificadores compartilhados, o Cloud 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 é normalmente realizada por cabeçalhos HTTP, como os cabeçalhos traceparent e tracestate, que foram padronizados pelo W3C. O cabeçalho traceparent contém os identificadores para identificar uma solicitação de forma exclusiva. Já 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 pai.
  • TRACE_FLAGS é um valor hexadecimal de 2 caracteres que identifica a decisão de amostragem do pai. Quando um pai amostrou o período, o valor é 01.

Google Cloud Os serviços que oferecem suporte à propagação de contexto de trace normalmente oferecem suporte ao traceparent e ao cabeçalho legado X-Cloud-Trace-Context.

Sempre que possível, use o traceparent cabeçalho nos aplicativos. Se um aplicativo só oferece suporte ao cabeçalho X-Cloud-Trace-Context, recomendamos que você o atualize para oferecer suporte e priorizar o cabeçalho traceparent. O 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 para a direita (/) e ponto e vírgula (;)
Representação do ID do período
 Codificação Decimal

Cabeçalho legado X-Cloud-Trace-Context

O cabeçalho X-Cloud-Trace-Context usado por Google Cloud é anterior à especificação do W3C. Para oferecer compatibilidade com versões anteriores, alguns Google Cloud serviços continuam aceitando, gerando e propagando o X-Cloud-Trace-Context cabeçalho. 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 oferece suporte a 0 (pai não amostrado) e 1 (pai amostrado).

Solicitações gRPC

Para solicitações gRPC, a propagação de contexto é realizada usando metadados gRPC, que são implementados em 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 Google Cloud serviços

Google Cloud Os serviços podem atuar como iniciadores ou intermediários no processamento de solicitações. Por exemplo, os seguintes serviços são conhecidos por participar do processamento de solicitações:

O suporte à iniciação e propagação do contexto de trace depende do serviço específico Google Cloud . Para solicitar que um Google Cloud serviço adicione suporte à propagação de contexto, use o Issue Tracker do Google.

Propagação de contexto nos 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 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 a configuração é necessária. Por exemplo, se você usar o OpenTelemetry para instrumentar um app Go, o app vai chamar SetTextMapPropagator, que configura o contexto para usar o formato traceparent do W3C. Para conferir um exemplo, consulte o exemplo de instrumentação do Go.

Quando não há uma biblioteca de instrumentação adequada, é necessário garantir que o aplicativo propague o contexto de trace para operações filhas.

A seguir