Contexto de rastreamento

Este documento descreve brevemente o contexto, que se refere ao estado, e a propagação de contexto, que se refere à transmissão de informações de estado para operações filhas. Para o trace distribuído, o ID do trace e o ID do período que está sendo processado precisam ser transmitidos para operações filhas.

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

  • _ID do período_: um identificador exclusivo da operação filha. Se a mesma operação for executada várias vezes, haverá vários períodos para essa operação, cada um com um identificador exclusivo.
  • ID do trace: o identificador exclusivo da operação de ponta a ponta 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 do período e ID do período pai permitem que um sistema de trace distribuído vincule corretamente os períodos 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 trace distribuído. 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 cabeçalhos HTTP, como os cabeçalhos traceparent e tracestate, que foram padronizados pelo W3C. Google Cloud Os serviços que oferecem suporte à propagação de contexto de trace geralmente oferecem suporte ao cabeçalho traceparent e ao cabeçalho legado X-Cloud-Trace-Context.

Sempre que possível, recomendamos que você use o traceparent cabeçalho nos seus aplicativos. Seu aplicativo pode precisar usar o cabeçalho legado X-Cloud-Trace-Context ou oferecer suporte ao recebimento do contexto de trace em um formato diferente.

Se você tiver um aplicativo que só oferece suporte 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 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 pelo 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 foi 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 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 é dependente doserviç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 seus aplicativos

Algumas bibliotecas de instrumentação, como o OpenTelemetry, podem propagar um objeto context que contém os dados necessários para o trace. Para uma lista de bibliotecas do OpenTelemetry que oferecem suporte ao trace, consulte APIs e SDKs de linguagem.

Se você depende de 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, seu app vai precisar 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