Contexto do trace

Neste documento, descrevemos 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 trace e o ID do período 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 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 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 de trace, ID de período e ID de período pai permitem que um sistema de rastreamento 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 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 normalmente é realizada por cabeçalhos HTTP, como traceparent e tracestate, que foram padronizados pelo W3C. Os serviços do Google Cloud compatíveis com a propagação de contexto de trace normalmente aceitam traceparent e o cabeçalho X-Cloud-Trace-Context legado.

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

Caso você tenha um aplicativo que ofereça suporte apenas ao cabeçalho X-Cloud-Trace-Context, recomendamos atualizar seu aplicativo 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 substituta.

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 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 à especificação do W3C. Para garantir a 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 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 oferece suporte a 0 (pai não amostrado) e 1 (o pai foi amostrado).

Solicitações gRPC

Para solicitações gRPC, a propagação de contexto é realizada usando metadados do 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 pertencem a você, recomendamos o uso do 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 do processamento de solicitações:

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

Propagação de contexto nos aplicativos

Algumas bibliotecas de instrumentação, como o OpenTelemetry, propagam automaticamente um objeto context que contém os dados necessários para o rastreamento. Se você usar esses tipos de bibliotecas, os períodos gerados pelo aplicativo serão configurados corretamente. Para conferir uma lista de bibliotecas do OpenTelemetry que oferecem suporte ao rastreamento, consulte APIs e SDKs de linguagem. Para conferir um exemplo de instrumentação, consulte Gerar traces e métricas com o Go.

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.

Quando não há uma biblioteca de instrumentação adequada, o app precisa propagar o contexto de rastreamento para as operações filhas.

A seguir