Contexto do trace

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 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 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 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 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 spans em um repositório e usa esses campos de ID para identificar quais spans compõem um rastro.

O contexto pode incluir outras informações de estado que são úteis para o rastreamento 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 geralmente é feita por cabeçalhos HTTP, como traceparent e tracestate, que foram padronizados pelo W3C. Os serviçosGoogle Cloud que oferecem suporte à propagação de contexto de rastreamento geralmente oferecem suporte a traceparent e ao cabeçalho X-Cloud-Trace-Context legado.

Sempre que possível, recomendamos o uso do cabeçalho traceparent nos seus aplicativos. Talvez seu aplicativo precise usar o cabeçalho X-Cloud-Trace-Context legado ou precisa oferecer suporte ao recebimento de contexto de rastreamento em um formato diferente.

Se você tiver um aplicativo que só oferece suporte ao cabeçalho X-Cloud-Trace-Context, recomendamos que atualize o aplicativo 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 Google Cloud continuam aceitando, gerando e propagando 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 com 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 é 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 Google Cloud serviços

Os serviçosGoogle 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 a iniciação e a propagação do contexto de rastreamento depende do serviço Google Cloud específico. Para solicitar que um Google Cloud serviço adicione suporte à propagação de contexto, use o Rastreador de problemas do Google.

Propagação de contexto nos seus apps

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

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